Kodara Docs
Kodara builds architectural memory for your codebase — so your AI gets surgical context instead of re-reading everything every time.
Why Kodara — Token Savings
Every time you ask an AI about your code, it reads the entire codebase. That's expensive. Kodara fixes this by giving your AI only the 2–8 files that actually matter.
The problem: AI reads everything
On a typical 44-file Python project, a single query without Kodara reads 41,160 tokens. Multiply by your daily queries and team size — costs compound fast.
# Without Kodara — ChatGPT GPT-4o ($2.50/1M input tokens) 1 query = 41,160 tokens = $0.10 5 queries = 205,800 tokens = $0.52 20 queries/day = ~$2.06/day = ~$45/month per dev # With Kodara — same queries 1 query = 1,840 tokens = $0.005 5 queries = 9,200 tokens = $0.023 20 queries/day = ~$0.09/day = ~$2/month per dev # Savings: 94% — ~$43/month per dev on GPT-4o
Real numbers across AI tools
API pricing as of 2026. Applies to direct API usage, Cursor API mode, self-hosted setups, and any tool billed per token.
* 44-file Python project. Without Kodara: 41,160 tokens (full read). With Kodara: 1,840 tokens (3 relevant modules). 94.5% reduction.
Monthly savings per developer
# GPT-4o ($2.50/1M input), 44-file project Light (20 queries/day, ~440/month): save ~$43/month Medium (50 queries/day, ~1,100/month): save ~$108/month Heavy (100 queries/day, ~2,200/month): save ~$216/month # Claude Sonnet ($3.00/1M input) Light (20 queries/day): save ~$52/month Medium (50 queries/day): save ~$130/month Heavy (100 queries/day): save ~$260/month # Kodara Pro = $19/month. # Medium GPT-4o user saves $108/month. ROI: 5.7x. # Medium Claude user saves $130/month. ROI: 6.8x.
Works with free models too
Kodara's output is plain text — paste it into any AI tool, including free tiers. Kodara gives a free model (Gemini Free, Kimi K2, etc.) the same architectural awareness as a paid subscription.
Prerequisites
Kodara requires Python 3.10 or higher. If you don't have Python installed, download it from python.org — pip is included automatically.
python --version # Python 3.10.0 or higher required
Installation
Install Kodara via pip — no API keys, no configuration required.
pip install kodara
Verify the installation:
kodara --version # kodara, version 0.3.1
Quick Start
Three commands to get up and running in under 60 seconds.
Navigate to your project
cd your-project
Build project memory
Scans your codebase, builds a dependency graph, and stores memory in .kodara/.
kodara init
Output example:
Kodara — Initialising my-project
Files: 83
Languages: {'python': 83}
Edges: 208
Git: main - 522 commits
Done in: 0.8s
kodara ask "How does routing work?"
Ask anything about your codebase
Copy the output and paste it into Claude, ChatGPT, Cursor, or any AI tool.
kodara ask "How does authentication work?"
Output example:
# Context: How does authentication work? ## auth/middleware.py Defines AuthMiddleware. Exports: verify_token, require_auth. Depends on: jwt_service.py, models/user.py ## auth/jwt_service.py Defines JWTService. Exports: encode, decode, refresh. [3/83 modules · ~1,840 tokens · 94% reduction]
kodara init
Scans your project, builds a dependency graph, generates summaries, and stores everything in .kodara/. Run once per project, then re-run after major changes.
kodara init kodara init --full # Force full re-index (ignore cache) kodara init --no-summaries # Skip summary generation (faster)
kodara init only processes changed files. Cached summaries are reused.
kodara ask
Returns the most relevant modules for your query using IDF-weighted semantic search + dependency graph expansion. Paste the output into any AI tool as context.
kodara ask "How does routing work?" kodara ask "Where is payment handled?" kodara ask "What happens when a user logs in?"
The output is formatted as structured markdown — ready to paste directly into Claude, ChatGPT, Cursor, or any AI tool.
kodara impact
Shows what breaks if a file changes. Uses BFS traversal through the reverse dependency graph to surface all affected modules, ranked by depth and risk.
kodara impact auth/middleware.py kodara impact # Auto-selects the most critical file
Output example:
Impact Analysis — auth.middleware Risk: HIGH Affects 23 modules (28% of codebase) Direct dependents (8) — will break immediately: api/routes.py api/v2/routes.py ... Indirect dependents (15) — affected through the chain: services/user.py (depth 2) ...
kodara onboard
Generates a structured reading guide for a new developer. Based on dependency layers and git activity — no LLM needed.
kodara onboard
Output: an ordered reading list from entry points → core modules → foundation → utilities, with reasons why each file matters.
kodara history
Shows git history for a file — commit count, last author, top contributors.
kodara history auth/middleware.py kodara history # Auto-selects most committed file
kodara context
Generates an ARCHITECTURE.md file in your project root — a human-readable overview of your codebase structure.
kodara context
kodara review
Analyzes your uncommitted changes and shows what they impact across the codebase.
kodara review
kodara diff
Shows impact analysis compared to a branch or commit.
kodara diff main kodara diff HEAD~3
kodara note
Annotate files with the WHY — decisions, context, warnings that code alone can't explain.
kodara note auth/jwt.py "Using RS256 not HS256 — security audit requirement" kodara note auth/jwt.py # show notes for this file kodara note --list # list all notes across all files kodara note --search "security" # search notes by text kodara note auth/jwt.py --delete 0 # delete newest note
kodara snapshot
Save a snapshot of the current project memory state. Useful before major refactors.
kodara snapshot kodara snapshot list
kodara stats
Shows how many tokens and money you've saved using Kodara.
kodara stats
Output example:
Kodara Stats — my-project
Today
Queries: 12
Tokens saved: 487,320 (97% reduction)
Money saved: $7.31
All time
Tokens saved: 2,341,880
Money saved: $35.13
kodara status
Shows the current state of the index — file count, last updated, memory location.
kodara status
kodara install-hook
Installs a git post-commit hook that automatically updates the Kodara index after every commit. Keeps your memory always fresh.
kodara install-hook # Install kodara uninstall-hook # Remove
kodara why
Explains why a file was written the way it was — combining git history, developer annotations, and optional AI analysis. No other tool answers the WHY question.
kodara why auth/middleware.py
Output:
Why — auth/middleware.py
Git history: 42 commits · 8 authors
Last changed: 2 days ago by @alice
First commit: 2023-11-14 by @bob ("initial auth setup")
Hot spot: top 5% most-changed files
Notes:
"Using RS256 not HS256 — security audit requirement (2024-02)"
"Removed session cookies — switched to stateless JWT"
AI: This file was rewritten after a security audit required
RS256 signing. It intercepts all API requests and validates
tokens before they reach route handlers.
kodara login the AI layer adds a human-readable explanation on top.
kodara simulate-change
Before you touch a critical file — see the full cost. BFS graph traversal calculates affected modules, estimates downstream dev-hours, and surfaces the critical paths to fix first.
kodara simulate-change auth/session.py kodara simulate-change auth/session.py --hours 6 # override avg hours/module
Output:
Simulate Change — auth/session.py
Direct dependents: 12 modules (will break immediately)
Indirect dependents: 37 modules (affected through the chain)
Downstream cost: ~80 dev-hours
Formula: 49 modules x 1.8h avg per fix
Risk: CRITICAL
Critical paths (fix these first):
auth.session -> api.routes -> client_sdk
auth.session -> payment.processor -> billing
Top affected:
api/routes.py (8 direct deps)
services/user.py (depth 2)
payment/processor.py (depth 2)
kodara heatmap
Shows which files are the most dangerous to touch — ranked by change frequency × number of dependents. High change rate + many dependents = highest risk.
kodara heatmap
Output:
Heatmap — my-project (83 files)
CRITICAL — change often + many dependents:
auth/middleware.py commits: 42 deps: 23 ████████ HIGH
api/routes.py commits: 38 deps: 18 ███████ HIGH
services/user.py commits: 31 deps: 14 ██████ HIGH
WATCH — growing fast:
billing/processor.py commits: 12 deps: 7 ████ MED
utils/validators.py commits: 9 deps: 5 ███ MED
STABLE — low risk:
config/settings.py commits: 3 deps: 2 █ LOW
utils/helpers.py commits: 2 deps: 1 █ LOW
kodara dna
Generates an architectural fingerprint of your project — auth patterns, routing style, DB access pattern, and similarity to known frameworks. Useful for code review, onboarding, and M&A due diligence.
kodara dna
Output:
Project DNA — my-saas
Auth: JWT + middleware (Flask pattern)
Routing: Decorator-based
DB: Repository pattern (Django-inspired)
Cache: Redis via decorator
Testing: pytest + fixtures
Queue: Celery tasks detected
Similarity:
73% FastAPI
21% Flask
6% unique
Maturity: Production-ready
Patterns: 6 of 21 detected
Run kodara learn to save this DNA to your library.
Run kodara evolve to see how the DNA changed over time.
kodara scan
Scans any public GitHub repository without installing anything on the target. Clones temporarily, builds memory, then deletes the clone. Results saved to ~/.kodara/scans/.
kodara scan github.com/tiangolo/fastapi kodara scan github.com/pallets/flask
Output:
Scanning github.com/tiangolo/fastapi...
Cloning... done
Files: 142
Languages: python
Edges: 387
Cleaning up: done
Hub modules:
fastapi/applications.py (dependents: 34)
fastapi/routing.py (dependents: 28)
fastapi/params.py (dependents: 21)
Saved: ~/.kodara/scans/fastapi/
Run: kodara ask "How does routing work?" --repo fastapi
.kodara/ context to any free LLM. Ask it to build a project combining the best patterns from all three. No source code needed.
kodara learn
Save the current project DNA fingerprint to .kodara/dna.json. Run after kodara dna to persist the fingerprint for future comparisons with evolve and compare.
kodara learn
Output:
DNA saved: .kodara/dna.json Project: my-saas Patterns: 6 of 21 detected Hubs: api/routes.py, auth/middleware.py Score: 74 Run kodara evolve to track how the DNA changes over time.
kodara evolve
Show how the project architecture changed over time — compares the current state against saved snapshots. Requires at least one snapshot (kodara snapshot) and a saved DNA (kodara learn).
kodara evolve
Output:
DNA Evolution — my-saas
snapshot-2024-01-15
Added: Queue pattern (Celery tasks detected)
Removed: —
Files: +12 Complexity: +8
snapshot-2024-03-01
Added: Cache pattern (Redis detected)
Removed: —
Files: +5 Complexity: +3
2 snapshots tracked. Architecture is growing steadily.
kodara compare
Compare the architectural DNA of two projects side by side. Both must be initialized with kodara init. Useful for auditing consistency across microservices or evaluating an acquired codebase.
kodara compare ./my-api ./my-frontend kodara compare /path/to/service-a /path/to/service-b
Output:
DNA Comparison
Project A: my-api (84 files, complexity: 74)
Project B: my-frontend (61 files, complexity: 41)
Common patterns: JWT auth, Repository pattern
Only in my-api: Queue (Celery), Cache (Redis)
Only in my-frontend: Component pattern, State management
Layer structure:
my-api: api -> service -> repository
my-frontend: components -> hooks -> store
kodara drift
Detect architectural drift since the last snapshot — new hub modules that appeared, files that gained unexpected dependencies, or layers that shifted. Catches gradual decay before it becomes a problem.
kodara drift
Output:
Drift Report — my-saas
[HIGH] New hub detected: utils/helpers.py (14 new dependents)
Utility file is becoming a god module — consider splitting
[MED] api/routes.py gained 8 new direct imports since last snapshot
Review for layer violations
[INFO] 12 new files added since last snapshot
No drift? Run: kodara snapshot to save current state as baseline.
kodara clone-pattern
Clone the architectural structure of any GitHub repository into a new directory — folders, file layout, and naming conventions, without any source code. Start a new project with a battle-tested structure.
kodara clone-pattern https://github.com/tiangolo/fastapi --into ./my-new-api
Output:
Cloning pattern from github.com/tiangolo/fastapi...
Scanned: 142 files
Patterns applied: routing, dependency-injection, middleware
Created: ./my-new-api/
app/
app/api/
app/core/
app/models/
app/schemas/
app/services/
tests/
Structure ready. No source code included — only the architecture.
kodara login / logout / whoami
Authenticate with Kodara Cloud to enable cloud backup, team memory sync, and AI features. Uses email magic link (OTP) — no password required.
kodara login # prompts for email, sends OTP kodara login --email you@co.com # skip the prompt kodara whoami # show logged-in account kodara logout # clear local session
Login flow:
$ kodara login Email: you@company.com Check your inbox for a 6-digit code. Code: 483920 Logged in as you@company.com
kodara why and kodara simulate-change.
kodara backup / restore / backups
Back up the current project index to Kodara Cloud. Restore it on any machine. Never lose your architectural memory after a git clean or a fresh clone.
kodara backup # upload .kodara/ to cloud kodara backups # list all cloud backups kodara restore my-project # download latest backup kodara restore my-project --path /dir # restore to custom path
Output examples:
# backup Backed up: my-project (84 files) -> cloud Backup ID: bkp_20240315_143022 # backups Cloud Backups my-project 84 files 2024-03-15 14:30 my-api 61 files 2024-03-10 09:15 old-monolith 203 files 2024-02-28 18:44 # restore Restored: 84 files -> .kodara/
kodara login first.
kodara bus-factor
Finds files where knowledge is dangerously concentrated — one person leaves and the knowledge is gone. Based on git authorship analysis across the entire codebase.
kodara bus-factor
Output:
Bus Factor Report — my-project
CRITICAL — sole author (bus factor: 1):
auth/session.py only known by: @alice commits: 42
payment/processor.py only known by: @bob commits: 31
infra/deploy.sh only known by: @carol commits: 18
WARNING — known by 2 people:
api/gateway.py authors: @alice, @carol
services/billing.py authors: @bob, @dave
HEALTHY:
utils/helpers.py authors: 4 people
models/user.py authors: 6 people
Overall bus factor: 3 (3 critical files, 3 sole authors)
kodara debt
Technical debt heatmap — files that change most often AND have the most dependents are your highest-risk debt. These are the places that are hardest to change and most likely to cause incidents.
kodara debt
Output:
Technical Debt — my-project
HIGH RISK — change often + many dependents:
auth/middleware.py changes: 42 deps: 23 debt: ████████
api/routes.py changes: 38 deps: 18 debt: ███████
services/user.py changes: 31 deps: 14 debt: ██████
ACCUMULATING — growing fast:
billing/processor.py changes: 12 deps: 7 debt: ████
utils/validators.py changes: 9 deps: 5 debt: ███
LOW — manageable:
config/settings.py changes: 3 deps: 2 debt: █
Total debt score: 847
Recommendation: refactor auth/middleware.py first — highest ROI
kodara arch-init + check-architecture
Define architectural rules once. Kodara enforces them on every commit — or in CI/CD. Prevents the slow drift where api/ starts importing repository/ directly, bypassing the service layer.
kodara arch-init # Auto-detect layers and generate config kodara check-architecture # Validate current state against rules
arch-init output:
Created .kodara/architecture.yml
Detected layers:
api: api/, routes/
service: services/
repository: models/, db/
utils: utils/, helpers/
Edit .kodara/architecture.yml to define allowed imports.
Then run: kodara check-architecture
After editing .kodara/architecture.yml, run check-architecture:
kodara check-architecture
Architecture Violations Detected (2)
api/user_routes.py
imports: db/session.py (repository layer)
violation: api layer cannot import repository directly
expected: api -> service -> repository
fix: add services/user_service.py as wrapper
api/payment.py
imports: models/transaction.py (repository layer)
violation: same as above
Run: kodara init-ci to add this check to your CI/CD pipeline
kodara init-ci to generate a GitHub Actions workflow. Architecture violations block PRs automatically — no manual review needed.
MCP — Model Context Protocol
Kodara includes a built-in MCP server. Instead of copy-pasting context manually, your AI tool fetches it automatically on every query. Works with Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible tool.
kodara mcp --setup to configure — no login required to use MCP locally. Login is only needed for cloud backup features.
Setup in one command
kodara mcp --setup
Auto-configures Claude Desktop, Cursor, and VS Code simultaneously. No manual JSON editing required. Restart your AI tool after running this.
Manual setup
Add to your AI tool's MCP config file:
{
"mcpServers": {
"kodara": {
"command": "kodara",
"args": ["mcp", "--path", "/absolute/path/to/your/project"]
}
}
}
Config file locations:
# Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json # Cursor ~/.cursor/mcp.json # VS Code / Windsurf / Trae (same format) ~/.vscode/mcp.json
--path. Run kodara init in that project first.
Available MCP Tools
Once connected, your AI gains 5 tools it calls automatically when it needs codebase context:
AI context workflow
The core workflow — use Kodara to get surgical context, then paste it into your AI tool.
# 1. Get context for your question kodara ask "How does the payment flow work?" # 2. Copy the output # 3. Paste into Claude / ChatGPT / Cursor as context # 4. Ask your question # Result: AI answers with full architectural awareness # instead of guessing from scratch
This works with any AI tool — Claude, ChatGPT, Cursor, Copilot, Gemini, or any local model.
Before a refactor
Always run impact analysis before changing a critical file.
# Before touching auth/middleware.py kodara impact auth/middleware.py # See exactly what breaks, at what depth # Make an informed decision before writing a single line
New team member
Generate a reading guide for anyone joining the project.
kodara onboard # Output: ordered reading list # 01 → main.py (entry point) # 02 → api/server.py (core hub) # 03 → auth/middleware.py (foundation) # ... # New developer is productive in hours, not days
Build from patterns
Scan real-world repositories to extract architectural patterns, then use a free LLM to build production-ready code based on those patterns.
# Scan 3 repos cd flask-repo && kodara init cd starlette-repo && kodara init cd bottle-repo && kodara init # Feed .kodara/ context to any free LLM (Gemini, Kimi, etc.) # Prompt: "Based on these architectural patterns, build a web app" # Result: production-ready code combining the best patterns # from all three frameworks — no source code needed