# CodeSkeleton

Compact Python code reader for AI agents. It returns file skeletons first, then lets the
agent fetch only the implementation regions it actually needs.

Why: reading whole files is often noisy and expensive. CodeSkeleton exposes compact CLI
and MCP tools for signatures, globals, symbols, targeted line ranges, and batch reads.

## Install

From GitHub:

```bash
uv tool install "codeskeleton[mcp] @ git+https://github.com/dugd/CodeSkeleton.git"
```

From a local checkout:

```bash
git clone https://github.com/dugd/CodeSkeleton.git
cd CodeSkeleton
uv sync --all-extras --dev
```

Quick check:

```bash
codeskel --help
codeskel skeleton "src/**/*.py" --preset min
```

From a local checkout, prefix commands with `uv run`:

```bash
uv run codeskel --help
uv run codeskel skeleton "codeskeleton/*.py" --preset min
uv run codeskel-mcp
```

Without installing, run directly from GitHub:

```bash
uvx --from "codeskeleton[mcp] @ git+https://github.com/dugd/CodeSkeleton.git" codeskel --help
```

## CLI Examples

```bash
codeskel skeleton codeskeleton/core.py
codeskel skeleton "codeskeleton/*.py" --preset min
codeskel skeleton codeskeleton/core.py --inline-bodies --inline-max-lines 2
codeskel symbols codeskeleton/core.py
codeskel implementation codeskeleton/core.py --symbol render_skeleton
codeskel implementation codeskeleton/core.py --lines 1-80 --preset min
codeskel implementation-batch '[{"path":"a.py","symbol":"foo"},{"path":"b.py","lines":"1-80"}]'
codeskel smart-batch render_skeleton "codeskeleton/**/*.py"
```

Presets:

- `min`: line ranges and signatures.
- `medium`: default; compact hashes, docstrings, globals, signatures.
- `full`: detailed metadata.

## MCP Setup

The MCP server command is:

```bash
codeskel-mcp
```

### Codex

```bash
codex mcp add codeskeleton -- codeskel-mcp
```

Verify:

```bash
codex mcp list
```

### Claude Code

```bash
claude mcp add --transport stdio codeskeleton -- codeskel-mcp
```

Inside Claude Code, run `/mcp` to verify the server is connected.

### Gemini CLI

Add this to `.gemini/settings.json` in a project, or to the user settings file:

```json
{
  "mcpServers": {
    "codeskeleton": {
      "command": "codeskel-mcp"
    }
  }
}
```

Restart Gemini CLI after changing settings.

## MCP Tools

- `skeleton`, `skeletons`: compact file maps for paths or globs.
- `symbols`: symbol list for a file.
- `implementation`, `implementations`: targeted code reads.
- `implementation_batch`: targeted reads across multiple files.
- `smart_batch`: find a symbol across files/globs and return matching implementations.

Suggested agent workflow:

1. Use `skeletons` with `preset="medium"` first.
2. Use `preset="min"` for broad scans.
3. Use `implementation_batch` or `smart_batch` instead of full-file reads.

## Development

```bash
uv sync --all-extras --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
```

## Status

Prototype. Currently Python-focused and AST-based.