Skip to main content

code-outline-graph

Symbol-level code indexer and MCP server. Parses your codebase with tree-sitter, stores symbols in SQLite + vector DB, and exposes a confirm-before-read protocol so AI assistants read only the symbols they need — not whole files.

10x–50x fewer tokens compared to reading files directly.

Install

pip install code-outline-graph

Quick Start

cd your-project
code-outline-graph build .

build runs once and configures everything — index, MCP configs, hooks, skill. Output:

╔══════════════════════════════════════════════════════════╗
║         code-outline-graph  •  Building Index            ║
╚══════════════════════════════════════════════════════════╝

[1/7] Indexing /home/user/myproject ...

      SKIP   .env                        (secret file)
      WARN   src/broken.py               parse error line 42
      OK     src/auth/views.py           23 symbols   0.04s
      OK     src/api/routes.py           45 symbols   0.11s

      src/auth/      →   3 files    67 symbols
      src/api/       →   8 files   203 symbols

      [████████████████████] 100%  186 files · 1789 symbols  →  Done!
      Skipped: 1  •  Errors: 1  •  Time: 3.2s

[2/7] Writing MCP configs (Claude/Cursor/Antigravity) ...
      Written: /home/user/myproject/.mcp.json  ✓
      Written: /home/user/myproject/.cursor/mcp.json  ✓
      Written: /home/user/.gemini/antigravity/mcp_config.json  ✓
[3/7] Writing Codex CLI config + hooks ...
      Written: .codex/config.toml  ✓
      Written: .codex/hooks.json   ✓
[4/7] Writing Gemini CLI config + hooks ...
      Written: .gemini/settings.json  ✓
[5/7] Writing Claude Code SessionStart + PostToolUse hooks ...
      Written: .claude/settings.json  ✓
[6/7] Writing AI instruction blocks ...
      Updated: AGENTS.md  ✓
      Updated: GEMINI.md  ✓
[7/7] Installing Claude Code skill ...
      Installed: SKILL.md     ✓
      Installed: examples.md  ✓

══════════════════════════════════════════════════════════
  Build complete in 5.1s
  186 files  •  1789 symbols  •  1 skipped  •  1 error
══════════════════════════════════════════════════════════

CLI Commands

Command Description
code-outline-graph build [path] Index project + write MCP configs for all clients
code-outline-graph build --embeddings [path] Also build semantic vector embeddings
code-outline-graph update [path] Reindex changed files only
code-outline-graph update --embeddings [path] Reindex changed files and refresh embeddings
code-outline-graph search <query> Search symbols by keyword
code-outline-graph outline <file> List all symbols in a file
code-outline-graph status [path] Show index stats
code-outline-graph prune [path] Remove stale rows for deleted or ignored files
code-outline-graph doctor [path] Check DB, parser, embeddings, and MCP config health
code-outline-graph serve [path] Start MCP server (stdio), watcher off by default
code-outline-graph serve --watch [path] Start MCP server with file watching
code-outline-graph install-skill Install Claude Code skill to ~/.claude/skills/

MCP Tools

The server exposes 11 tools to AI assistants:

Tool Description
resolve_edit_target NL description → top-5 symbol candidates (signatures only, no body)
read_symbol_body Read source lines for one symbol only
list_outline All symbols in a file with line ranges
get_outline_summary Compressed signatures-only outline
get_file_header Imports + top-level constants only
get_symbol Exact symbol metadata by name
find_by_keyword Keyword search across all symbol names
get_line_range Read arbitrary line slice from a file
index_project Index a directory; pass watch: true to start file watcher
update_project Reindex only changed files (faster than index_project)
prune_project Remove stale index rows for deleted or ignored files

Confirm-Before-Read Protocol

1. resolve_edit_target({"description": "user login handler"})
   → [{name: "login", file: "views/auth.py", start: 45, end: 89, signature: "def login(...)"}]

2. AI picks correct candidate from signatures (no body read yet)

3. read_symbol_body({"name": "login", "file": "views/auth.py"})
   → 44 lines instead of 300-line file

Supported Languages

50+ languages and formats — symbols extracted where applicable, files tracked for all others.

Systems & Backend Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, C, C++, C#, Kotlin, Swift, Dart, Scala, Groovy, Zig, Lua

Web & Frontend HTML, CSS, SCSS, Sass, Less, Vue, Svelte

Shell & Scripting Bash/Zsh (.sh/.bash/.zsh), Fish, PowerShell, Batch/CMD, Perl, R

Functional Elixir, Erlang, Haskell, OCaml, Clojure/ClojureScript, Nix

Data & Config JSON, YAML, TOML, INI/CFG, XML, PLIST, SQL, SQLite (.db — tables/views), CSV

Infrastructure & Build Terraform/HCL, Protobuf, GraphQL, Makefile, Dockerfile

Mac / Windows system files (.DS_Store, .exe, .dll, .lnk, etc.) are binary and are skipped automatically.

Architecture

cli.py          CLI entry point — build/update/search/outline/status/serve
server.py       MCP server — tools, optional file watcher lifecycle
indexer.py      Orchestrates parse → checksum → DB upsert → embeddings
parser.py       tree-sitter parsing → Symbol extraction per language
db.py           SQLite + sqlite-vec — symbols table + FTS5 + vector index
search.py       FTS search, keyword search, vector search, resolve_edit_target
watcher.py      watchdog file watcher — debounced file-level reindex
embeddings.py   fastembed vector embeddings for semantic search
paths.py        Per-project DB path resolution (.code-outline-graph/index.db)

Each project gets its own SQLite DB at .code-outline-graph/index.db inside the project. The watcher is opt-in and only reindexes changed files on save or removes symbols for deleted files. Git branch switches no longer trigger a full project reindex automatically.

Large Codebases

The default runtime is conservative so AI-assisted sessions do not saturate the machine:

  • Parser workers default to min(4, cpu_count); override with CODE_OUTLINE_INDEX_WORKERS=2 or build --workers 2.
  • Embeddings are disabled by default; enable with --embeddings or CODE_OUTLINE_ENABLE_EMBEDDINGS=1.
  • Files >=512KB are skipped by default; enable background indexing with --background-large-files or CODE_OUTLINE_BACKGROUND_LARGE_FILES=1.
  • File watching is disabled by default; enable with serve --watch or CODE_OUTLINE_WATCH=1 for MCP index_project.

MCP Configuration

build auto-configures all supported clients in one shot:

Client MCP config SessionStart hook
Claude Code .mcp.json .claude/settings.json
Cursor .cursor/mcp.json none
Antigravity ~/.gemini/antigravity/mcp_config.json none
Codex CLI .codex/config.toml .codex/hooks.json
Gemini CLI .gemini/settings.json .gemini/settings.json

It also appends usage instructions (sentinel-bounded, safe to re-run) to AGENTS.md and GEMINI.md so clients that read those files know to use the MCP tools.

The SessionStart hook runs code-outline-graph update . at the start of every AI session, keeping the index fresh without manual intervention.

Claude Code Skill

build automatically installs the Claude Code skill to ~/.claude/skills/code-outline-graph/ (SKILL.md + examples.md). The skill teaches Claude the confirm-before-read protocol and tool reference.

To install manually or update after upgrading:

code-outline-graph install-skill

Development

pip install -e ".[dev]"
pytest                        # run all tests
pytest tests/test_parser.py   # run single test file

License

MIT

Metadata

Release files for code-outline-graph 0.2.47

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for code-outline-graph 0.2.47
File Size Uploaded Provenance Actions
code_outline_graph-0.2.47.tar.gz 43.8 kB Without provenance Details for code_outline_graph-0.2.47.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for code-outline-graph 0.2.47
File Interpreter ABI Platform Actions
code_outline_graph-0.2.47-py3-none-any.whl Python 3 none any Details for code_outline_graph-0.2.47-py3-none-any.whl

Total release size: 85.3 kB

Release files / code_outline_graph-0.2.47.tar.gz

Download URL code_outline_graph-0.2.47.tar.gz
Size 43.8 kB
Tags Source
SHA-256 checksum
How to use checksums
dea6f054e6b0f6168791ca9db522c5ded6a4e7b6b8eb2bb69b02a2ba1e494f7e
BLAKE2b-256 checksum
How to use checksums
11f5ceb3797ed361e81172dee925a3d9dc4e6497e7cb599b1ad5f0b6ae9e4df8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.12

Release files / code_outline_graph-0.2.47-py3-none-any.whl

Download URL code_outline_graph-0.2.47-py3-none-any.whl
Size 41.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b7f2a17d4d1c5f1c0986adb4f04182b4e31f7d20878b31dfb9baa1c204470720
BLAKE2b-256 checksum
How to use checksums
a6590bbd4a76382d5ed8a9d2d3de2a0479e9c75754fba8ee281898235e0792b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.12

Security for code-outline-graph 0.2.47

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.47 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page