chera 0.1.0

chera (چرا) answers the WHY of your codebase: it rebuilds the story of an AI-built project from git history and coding-agent sessions, and serves it as a local web app.

chera · چرا

chera (چرا) means “why” in Persian. It answers the why of your codebase.

You built your project with AI agents (Claude Code, Cursor, Copilot…). It works — but months later nobody remembers why anything looks the way it does. Why redis? Why was the payment flow rewritten? What died along the way?

chera reconstructs the story of your project from evidence that already exists on your machine — git history and AI coding-agent sessions — and serves it as a local web app:

• Story — the project as a narrated timeline of eras and episodes, each with its evidence (commits, agent prompts) and an honest confidence label.
• Twin — a living map of the codebase: which decisions are still active, which are partial, which are dead.
• Time-travel — scrub through time and watch the project grow.
• Ask — free-form questions (“why do we use redis?”) answered only from evidence. When there is no evidence, chera says so instead of hallucinating.

100% local. Zero runtime dependencies. No API key required.

Install

pip install chera

Requires Python 3.10+ and git. Nothing else.

Quickstart

cd your-project
chera ui          # scan + open the web app at http://127.0.0.1:7345

That's it. Other entry points:

Command	What it does
chera scan	Build/refresh the project twin (.chera/twin.json)
chera ui	Scan and open the local web app
chera watch	Keep the twin updated as you keep committing
chera ask why redis	Grounded Q&A in the terminal
chera timeline --depth decision	The story as a terminal timeline
chera learn	Chaptered Markdown course about your own project
chera report	Single-file Markdown report

How it works

1. Ingest — reads git log (authors, dates, messages, file changes) and, when present, Claude Code session files (~/.claude/projects/…) that overlap your repo.
2. Episodes — commits are clustered into work episodes by time proximity; agent sessions are attached by time overlap.
3. Why classification — every episode gets an evidence class:
   • documented — a recorded reason exists (commit body / agent prompt), quoted verbatim
   • hypothesis — chera infers a likely reason and labels it as a guess
   • unknown — no evidence; chera admits it
   • anomaly — reverts and suspicious patterns, flagged
4. Decisions — each episode becomes a decision node with status_now (active / partial / dead) computed against today's tree, plus supersedes edges.
5. Serve — a stdlib HTTP server renders the story locally and keeps it fresh.

Optional: LLM narration (BYOK)

chera is fully useful offline. If you want richer narration, bring your own key — any OpenAI-compatible endpoint (OpenAI, Ollama, LM Studio, OpenRouter…):

export CHERA_LLM_BASE_URL=http://localhost:11434/v1   # e.g. Ollama
export CHERA_LLM_MODEL=llama3
export CHERA_API_KEY=...                              # if your endpoint needs one
chera scan --narrate

Narration is grounded: the model only sees stored evidence, never invents reasons, and already-narrated episodes are never re-billed (incremental scans carry narration over).

Honesty contract

• Every claim links to commits/sessions you can check.
• Missing evidence is reported as missing — that absence is itself information.
• Everything runs on your machine; nothing is uploaded anywhere.

Development

git clone https://github.com/mohammadpooshesh/chera
cd chera
pip install -e ".[dev]"
pytest
ruff check src tests

See docs/architecture.md, docs/data-model.md and CONTRIBUTING.md.

License

MIT © Mohammad Pooshesh