Metadata-Version: 2.4
Name: chera
Version: 0.1.0
Summary: 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.
Author-email: Mohammad Pooshesh <mohammad.pooshesh@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mohammadpooshesh/chera
Project-URL: Repository, https://github.com/mohammadpooshesh/chera
Project-URL: Issues, https://github.com/mohammadpooshesh/chera/issues
Project-URL: Changelog, https://github.com/mohammadpooshesh/chera/blob/main/CHANGELOG.md
Keywords: ai,claude-code,code-comprehension,decision-replay,developer-tools,digital-twin,git,knowledge,vibe-coding
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install chera
```

Requires Python 3.10+ and git. Nothing else.

## Quickstart

```bash
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…):

```bash
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

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

See [docs/architecture.md](docs/architecture.md), [docs/data-model.md](docs/data-model.md)
and [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT © Mohammad Pooshesh
