codenarrator-ai 0.1.1

Autonomous codebase understanding agent — clone a repo, get an architecture report.

CodeNarrator

Autonomous codebase understanding agent.

Give it a Git URL and it produces an interactive HTML dependency graph plus a natural-language architecture summary of the codebase. Everything runs locally via Ollama — no API keys, no cloud calls.

Prerequisites

• Python 3.10+
• Ollama installed and running
• A model pulled: ollama pull qwen2.5-coder:7b

Installation

pip install codenarrator-ai

Usage

from codenarrator import analyze

result = analyze("https://github.com/user/repo")

result.show()                  # opens the HTML report in your browser
result.to_html("report.html")  # save the HTML to a file
result.to_json("graph.json")   # export the dependency graph as JSON

Deeper exploration (30 steps instead of the default 20):

result = analyze("https://github.com/user/repo", depth="deep")

Private repositories:

result = analyze(
    "https://github.com/user/private-repo",
    api_key="your-github-token",
)

Result object

Property / Method	Description
result.show()	Open the HTML report in your browser
result.to_html(path)	Save the HTML report to a file
result.to_json(path)	Export dependency graph as JSON
result.dependency_graph	List of internal edges
result.explored_files	Files the agent explored
result.architecture_summary	AI-generated architecture summary

Configuration

Environment variables:

Variable	Purpose	Default
CODENARRATOR_DATA_DIR	Where clones, cache, and reports go	~/codenarrator/
OLLAMA_HOST	Ollama server URL	http://localhost:11434
OLLAMA_MODEL	Model to use	qwen2.5-coder:7b

Output

Reports and clones live under ~/codenarrator/ by default:

~/codenarrator/
├── repos/      ← cloned repositories
├── cache/      ← analysis cache (keyed by repo + git HEAD)
└── reports/    ← generated HTML reports

Supported languages

Language	Full dependency graph	Import extraction
Python	✓	✓
TypeScript	✓	✓
JavaScript	✓	✓
Java	—	✓
Go	—	✓
Rust	—	✓
C / C++	—	✓

How it works

Two layers:

Deterministic layer — file scanning, import extraction, internal-edge resolution, dependency graph computation. Pure Python, no LLM involved. Always produces a complete graph from static analysis alone.

Agentic layer — a local LLM (Qwen2.5-Coder 7B by default) explores the codebase via five tool calls:

• read_file — inspect a source file
• follow_import — jump to a file imported by something already read
• search_for_pattern — regex search across the repo
• mark_architecture_insight — record a finding
• stop_analysis — finish the run

The model produces a natural-language architecture summary alongside the deterministic graph. If the LLM times out or returns junk, the report still renders from the deterministic layer.

Local development

For contributors only. End users should use pip install codenarrator-ai above.

git clone https://github.com/sharwariakre/CodeNarrator
cd CodeNarrator
pip install -e .  # for local development

# Start Ollama (separate terminal)
ollama serve
ollama pull qwen2.5-coder:7b

Optional web UI (FastAPI backend + React frontend):

# Terminal 1
cd backend && uvicorn app.main:app --reload

# Terminal 2
cd frontend && npm install && npm run dev

Run the test suite:

cd backend && python -m pytest tests/