convez.ai
AgenteDesenvolvimento WebAvançado
Kasho323

Codebase Explainer Agent

Kasho323/codebase-explainer-agent

Navegue codebases com respostas verificáveis e citações precisas

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que responde perguntas técnicas sobre repositórios Python usando grafos de símbolos via tree-sitter e Claude tool use. Indexa o código em SQLite, resolve chamadas via grafo de dependências e cita `path:line` específicas para cada afirmação, evitando alucinações.

Instalação

$npx convez-ai Kasho323/codebase-explainer-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Onboarding em novos projetos e codebases
  • Auditoria técnica de dependências e bibliotecas
  • Análise de fluxo de chamadas e dependências entre módulos
  • Responder perguntas de arquitetura com evidências do código

Veredito

Ferramenta sólida em fase ativa de desenvolvimento (196 testes, CI verde). Combina tree-sitter, SQLite e Claude de forma inteligente para eliminar alucinações em análise de código. Aguarda deploy público e suporte a linguagens adicionais; viável hoje para Python.

README

A tradução para o português deste README ainda está na fila.

Codebase Explainer Agent

An LLM agent that answers engineering questions about any Python repo. Backed by a tree-sitter symbol graph in SQLite — every claim cites path:line you can click to verify.

CI License: MIT Python 3.11+

Grounded answer with citations A grounded answer with path:line citations — every claim is verifiable against the indexed source.

Status: Python indexer, six-tool agent loop, semantic search, initial golden-case eval harness, and local Gradio demo are all working today (196 tests, CI green). Remaining work: additional language grammars and a public Hugging Face Spaces deploy. See Roadmap.


Why

When joining a new codebase — onboarding to a new job, contributing to open source, auditing a dependency — most of the work is navigation: figuring out what calls what, why a module exists, and where to make a change. LLM chat alone is not enough: it hallucinates without grounding. Naive RAG is not enough: it retrieves text but loses the call graph.

This project combines a tree-sitter symbol graph in SQLite with a Claude agent that navigates it via tool use, citing specific path:line for every claim.


What it does

Input: a Python repo on disk.

Output: an interactive chat that can answer questions like:

  • "Who calls the authenticate function?"
  • "What's the design intent behind the Storage abstraction?"
  • "If I wanted to add OAuth support, which files would I need to touch?"
  • "Walk me through what happens when a request hits /api/users."

Every answer cites concrete path:line references that you can click to verify.


Architecture

graph LR
    User[User] --> CLI[CLI: chat REPL]
    CLI --> Agent[Agent Loop<br/>Claude Sonnet 4.6<br/>+ adaptive thinking<br/>+ prompt caching]

    Agent <--> Tools{Tool dispatcher}
    Tools --> T1[read_file]
    Tools --> T2[grep]
    Tools --> T3[find_definition]
    Tools --> T4[find_callers]
    Tools --> T5[view_symbol]
    Tools --> T6[search_semantic]
    Tools -.-> T7[git_log — Week 5]

    T1 --> Files[(Repo on disk)]
    T2 --> Files
    T3 --> Symbols[(SQLite symbol graph)]
    T4 --> Symbols
    T5 --> Symbols
    T5 --> Files
    T6 --> Vectors[(FAISS index)]

    Indexer[Tree-sitter indexer<br/>+ resolver<br/>+ embedder] --> Symbols
    Indexer --> Vectors

    style Agent fill:#e1f5ff
    style Indexer fill:#fff4e1

How it answers:

  1. Symbol layer — tree-sitter extracts every function, class, method, import, and call edge into a SQLite graph. A resolution pass turns textual callees (basket.build_graph) into symbols.id foreign keys via import-aware lookup, so "who calls X" becomes a JOIN, not a regex.
  2. Embedding layer — every symbol's signature + docstring + body is embedded with sentence-transformers/all-MiniLM-L6-v2 (384-dim, CPU) and stored as a BLOB in SQLite. Search builds an in-memory FAISS index per query — fast for repos under ~10K symbols, no separate index file to keep in sync. Enabled with index --embed; the search_semantic tool is automatically dropped from the agent's tool list when the index has no embeddings, so Claude doesn't waste a call discovering it's unavailable.
  3. Agent layer — Claude Sonnet 4.6 with six tools (read_file, grep, find_definition, find_callers, view_symbol, search_semantic) decides which layer to query. Adaptive thinking for multi-step navigation, prompt caching for the tool list and system prompt. One more tool (git_log) ships in Week 5.

Tech stack

LayerChoiceWhy
LLMAnthropic Claude Sonnet 4.6Strong tool use, 200K context, balanced cost. Adaptive thinking + effort=medium by default.
Code parsingtree-sitter (Python today; JavaScript + Go upcoming)Battle-tested AST extraction, language-agnostic.
Symbol storeSQLiteZero infra, fast joins for call-graph queries, fits in a single file you can scp around.
Vector storeFAISS (local, in-memory IndexFlatIP)No external service, no second file to keep in sync. Fits in RAM for repos under 100k LOC.
Embeddingssentence-transformers/all-MiniLM-L6-v2Free, CPU-only, 384-dim. Vectors stored as float32 BLOBs in SQLite.
UICLI today; Gradio + HF Spaces in Week 6One-file chat UI, zero-cost public demo.

Quick start

git clone https://github.com/Kasho323/codebase-explainer-agent
cd codebase-explainer-agent
pip install -r requirements.txt

# 1. Index a Python repo on disk. The DB is a single SQLite file.
#    Add --embed to also embed every symbol for the semantic search tool
#    (first run downloads ~80MB of model weights).
python -m codebase_explainer index /path/to/some/repo --db /tmp/idx.sqlite3 [--embed]

# 2. Point chat at the indexed DB and the repo root.
export ANTHROPIC_API_KEY=sk-ant-...           # Linux/macOS
# $env:ANTHROPIC_API_KEY = "sk-ant-..."       # Windows PowerShell
python -m codebase_explainer chat \
    --db /tmp/idx.sqlite3 \
    --repo-root /path/to/some/repo

The chat REPL opens with a banner showing the index size, then accepts free-form questions. As the agent works, every tool call prints to the screen so you can see exactly what's being read:

You> who calls build_graph in this repo?

  -> find_callers(name='build_graph')
  -> read_file(path='basket_graph/main.py', start_line=60, end_line=70)

[agent's grounded answer with path:line citations]

You> /exit

Commands inside the REPL: /exit, /reset (clear conversation), /help.

Try it on a small target

The smaller Kasho323/basket-graph-analytics repo (~500 LOC, classic graph-mining problem) is a quick way to see the agent in action without indexing something huge:

git clone https://github.com/Kasho323/basket-graph-analytics
python -m codebase_explainer index ./basket-graph-analytics --db /tmp/basket.sqlite3
python -m codebase_explainer chat --db /tmp/basket.sqlite3 --repo-root ./basket-graph-analytics

Good first questions to try:

  • "Who calls build_graph and what does it return?"
  • "Explain what dfs._visit does and where it's defined."
  • "Why does benchmark.py exist? What is it measuring?"

Local web demo

Same agent, in a browser. Requires an API key.

pip install -r requirements.txt
python -m codebase_explainer index ./some-repo --db /tmp/x.sqlite3

# Anthropic (default)
ANTHROPIC_API_KEY=sk-ant-... \
    python -m codebase_explainer demo --db /tmp/x.sqlite3 --repo-root ./some-repo

# Open http://localhost:7860

DeepSeek's Anthropic-compatible endpoint also works — set ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic, plus ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) and ANTHROPIC_MODEL.

Demo screenshot

Gradio demo interface Gradio local demo interface, here running against a DeepSeek-compatible endpoint.


Evaluation

Quality is tracked against an initial golden case set under eval/golden_cases/ — currently 3 cases on the basket-graph-analytics repo, growing as the case set fills out.

Each case has a question, an expected path:line citation that any correct answer must include, and a free-form "expected gist". Three scorers run per case: citation match (regex), faithfulness (LLM judge), gist match (LLM judge). The judge model is pluggable via --judge-model / EVAL_JUDGE_MODEL so the same harness runs against Anthropic or any Anthropic-compatible endpoint.


Roadmap

6 weeks, May 5 → June 15, 2026

  • Week 1 (4/28–5/4) — Repo scaffolding, README, CI, FastAPI hello-world endpoint.
  • Week 2 (5/5–5/11) — Tree-sitter Python indexer; SQLite schema for symbols/imports/calls; python -m codebase_explainer index <path> walks a real repo, persists into SQLite, and runs a callee-resolution pass that fills calls.callee_id for in-repo references via self/cls scoping, import aliases, and same-file lookup.
  • Week 3 (5/12–5/18) — Manual tool-use loop on Claude Sonnet 4.6 with four tools (read_file, grep, find_definition, find_callers). Adaptive thinking + prompt caching wired in. Interactive REPL via python -m codebase_explainer chat --db <file> --repo-root <path> with /reset / /exit, surfaces every tool call as the agent makes it, cites results as path:line. 115 tests passing.
  • Week 4 (5/19–5/25) — partially shipped:
    • view_symbol tool: one-shot deep lookup returning location, signature, docstring, source body, parent, callers, and callees.
    • Embedding layer: every symbol embedded with sentence-transformers/all-MiniLM-L6-v2, vectors stored as float32 BLOBs in SQLite, FAISS IndexFlatIP built in-memory per query. New search_semantic tool wired into the agent. The tool is auto-dropped from the active tool list if no embeddings exist, so prompt-cache stays stable across sessions. 115 tests passing.
    • JavaScript and Go grammars (Go may slip to Week 5 depending on indexer dispatch refactor).
  • Week 5 (5/26–6/1) — partially shipped:
    • Initial golden-case eval harness with three scorers (citation match, LLM-judge faithfulness, LLM-judge gist match). Case set grows per release.
    • git_log tool; deeper prompt-caching tuning across long sessions.
  • Week 6 (6/2–6/15) — partially shipped:
    • Local Gradio demo (python -m codebase_explainer demo) with optional DeepSeek-compatible endpoint.
    • Hugging Face Spaces deploy; demo gif; companion blog post.

Project layout

codebase-explainer-agent/
├── src/codebase_explainer/
│   ├── __init__.py
│   ├── __main__.py          # CLI: python -m codebase_explainer {index,chat}
│   ├── agent.py             # Manual tool-use loop with prompt caching
│   ├── chat.py              # Interactive REPL with /reset and /exit
│   ├── tools/
│   │   ├── __init__.py      # TOOL_HANDLERS registry + EMBEDDING_DEPENDENT_TOOLS
│   │   ├── definitions.py   # Tool JSON schemas (byte-stable for caching)
│   │   ├── read_file.py
│   │   ├── grep.py
│   │   ├── find_definition.py
│   │   ├── find_callers.py
│   │   ├── view_symbol.py
│   │   └── search_semantic.py
│   ├── embeddings/
│   │   ├── __init__.py
│   │   ├── embedder.py      # Embedder protocol + Fake + SentenceTransformer impls
│   │   ├── chunker.py       # Symbol → embeddable text
│   │   └── store.py         # SQLite BLOBs + in-memory FAISS search
│   ├── indexer.py           # Tree-sitter → Symbol / Call / Import dataclasses
│   ├── repo_walker.py       # File-tree walker with VCS/cache skip-list
│   ├── persistence.py       # Idempotent FileIndex → SQLite
│   ├── resolver.py          # Resolve textual callees → symbol_id
│   ├── index_repo.py        # Orchestrator: walk + parse + persist + resolve + (optional) embed
│   └── schema.py            # SQLite DDL (v3: + embeddings table)
├── tests/                   # 115 tests across 12 files
├── eval/golden_cases/       # Frozen eval set (Week 5)
├── .github/workflows/ci.yml
└── pyproject.toml

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados