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.8 or higher. If you don't have Python installed, download it from python.org — pip is included automatically.

python --version
# Python 3.8.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.2.2

Quick Start

Three commands to get up and running in under 60 seconds.

cd your-project

kodara init

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

kodara ask "How does authentication work?"

# 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 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 add auth/jwt.py "Using RS256 not HS256 — security audit requirement"
kodara note list
kodara note list auth/jwt.py

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

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