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:

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

From a local checkout:

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

Quick check:

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

From a local checkout, prefix commands with uv run:

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

Without installing, run directly from GitHub:

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

CLI Examples

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:

codeskel-mcp

Codex

codex mcp add codeskeleton -- codeskel-mcp

Verify:

codex mcp list

Claude Code

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:

{
  "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

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.