Basin tracks, branches, and settles the context of a long AI collaboration across Claude Code and Codex — the decisions, constraints, rejected paths, and open questions an assistant should hold on to across sessions, compactions, and forked threads.
Turn it on once per host and Basin quietly does the context engineering for you: it captures the transcript at host-specific hook points, extracts durable context atoms, settles the agreed ones into a versioned Canon, and compiles a Context Pack so a new thread inherits everything that matters. Everything is stored as plain, append-only files committed to your repo — your context travels with your code and diffs in a pull request.
- 📌 Branch, fork, and settle context — not just code. Drafts and forked threads explore freely; what's agreed settles into the Canon.
- 🧬 Track semantic changes. Every decision/constraint/assumption is a first-class atom with status, provenance, confidence, and an authority tier.
- 🔀 Review and merge. See exactly what a branch would add to or supersede in the Canon, then settle it.
- 🕹️ Inspect the context graph.
basin tuishows branch lanes, checkpoint diffstats, atom badges, proposals, and detail panels without leaving the terminal. - 🧠 Compile Context Packs. A budgeted, inheritable artifact a new thread loads to continue where the last left off — with a built-in continuity test.
- 🪂 Capture at the right moments. Claude Code uses session/pre-compact/session-end hooks; Codex uses session/pre-compact/turn-end capture. Repeated hooks with no new transcript content are no-ops.
- 🌿 Recognize forks automatically. When a host preserves the inherited transcript prefix, Basin links side threads/forks to their parent session and records new raw events on the detected branch from the start.
- 📁 Files are the source of truth. Append-only JSONL + human-readable Markdown in
.basin/; SQLite is a rebuildable index you can delete anytime.
Status: alpha, under active development. The engine, the Claude Code/Codex capture integrations, automatic fork detection, and the terminal UI work today and are covered by 222 passing tests. The detached LLM refiner remains opt-in. See Status.
basin tui opens with a terminal cockpit for context history: branch lanes, checkpoints, semantic diffstats, and branch chips in one screen before you drill into proposals, Canon, or atom details.
In a long project with an AI assistant, the useful state is not the chat log — it's what the assistant should believe, avoid, and use as a basis for the next action. That state keeps getting lost: context windows compact, threads fork to try a new approach, and the same decisions get re-litigated three sessions later.
Today people manage this by hand — re-pasting summaries, re-explaining constraints, re-deciding things that were already settled. Basin treats that state as a first-class, versioned object, the way Git treats source code.
It is not "Git for chat logs." The transcript is raw input; the tracked thing is the distilled, governed context state. Git is the surface metaphor (branch, checkpoint, merge, release); underneath it is semantic event sourcing.
You're deep in a thread, you fork it to try a different approach, and now two lines of reasoning are diverging. Basin captures both branches, shows you the difference as a set of context changes, and lets you settle the winning ideas back into the Canon — without losing the road not taken.
Claude Code / Codex session ──hooks──▶ .basin/ (committed to your repo)
├─ events/*.jsonl ← truth: raw transcript events
├─ atoms/*.jsonl ← truth: context atom revisions
├─ checkpoints.jsonl ← commits (semantic state transitions)
├─ canon/CANON.md ← the human-readable source of truth
├─ branches/*.md ← branch cards
├─ packs/*.yaml ← Context Packs (handoff units)
└─ .index/basin.db ← rebuildable index (gitignored)
│
basin tui ▼ (gh-orbit-style terminal cockpit)
Threads · Branches · Changes · Canon · Proposals · Map
A checkpoint is not the raw chat turn — it's the captured context state after a host hook or an explicit basin save. Most messages change nothing; the ones that settle a decision or add a constraint do.
The cockpit is a reader for that state: Threads draws fork/merge lanes and diffstats, Branches switches workrooms, Changes and Proposals review unsettled atoms, Canon shows settled truth, and Map reads clusters generated by basin graph. Press Enter on a checkpoint or atom row to inspect provenance, authority/confidence, supersedes history, and related edges.
Requires Python 3.10+ and either Claude Code or Codex. No other dependencies.
git clone https://github.com/Oscar-V4/basin.git
cd basin
./plugin/install.sh # Claude Code: hooks + slash commands, merges ~/.claude/settings.json
./plugin/install-codex.sh # Codex: hooks, merges ~/.codex/hooks.json
cd /your/project
basin setup # scaffold .basin/ in your project (auto-fork on by default)
basin graph # optional: build clusters for the Map tab
basin tui # open the cockpitRun the installer for the host you use, or run both if you move between Claude Code and Codex. Then work as usual — Basin captures context automatically, especially around compaction when the host exposes that hook. Codex Stop is treated as turn-end capture, not final session closure, so frequent turn-end runs are safe and idempotent when no new transcript events exist. Or drive it directly:
basin status # current Canon + staged changes + open questions
basin save -m "lock storage decision" # promote staged Canon/main atoms; add --branch for a fork
basin fork --name spike # explore a new approach on a branch
basin auto # enable always-on capture + automatic fork detection for an existing project
basin reconcile --branch spike # preview what settling that branch would change
basin settle --branch spike # apply the branch's clean changes to Canon
basin pack --lod standard # compile a Context Pack to hand off to a new thread
basin inherit --branch main # load the pack into a new thread + take the continuity test
basin on | off # toggle capture for this projectUse basin settle --force --branch spike only when you intentionally want to override divergence or a rejected-path resurrection. In Claude Code, the same common actions are slash commands: /basin-save, /basin-pack, /basin-fork, /basin-status, /basin-inherit; pass --branch to /basin-save when saving an auto-detected fork, while branch reconcile/settle stays on the CLI. In Codex, use the basin CLI for the same actions; capture still runs automatically through hooks.
| Concept | What it is |
|---|---|
| Context atom | One durable unit of context — a decision, constraint, assumption, open_question, rejected_path, etc. — with status, provenance, confidence, and authority tier. |
| Canon | The settled source of truth for a project. Branches explore; the Canon is what has settled. |
| Branch / fork | A workroom for exploring an approach. A fork inherits the Canon, then diverges. |
| Checkpoint | A captured context transition: pre-compact, turn-end, session-end, save, merge, fork point, and release build. |
| Context Pack | The deployment unit of AI collaboration — a budgeted, inheritable artifact a new thread loads, with a continuity test to verify the inheritance took. |
More in docs/concepts.md and docs/comparison-to-git.md.
| Area | State |
|---|---|
| Engine — capture, extraction, fingerprint change-classification, save/promote, reindex, Context Pack | ✅ working |
| Storage — append-only JSONL truth + Markdown/YAML projections + rebuildable SQLite index | ✅ working |
Claude Code integration — hooks (session-start / pre-compact / session-end), slash commands, install.sh |
✅ working |
Codex integration — rollout transcript adapter + hooks (session-start / pre-compact / turn-end), install-codex.sh |
✅ working |
basin tui — cockpit with rail graph, checkpoint diffstats, branch chips, atom badges, aligned meta, Map tab, and detail panels |
✅ working |
| Context graph clustering (stable community ids) | ✅ working |
Detached LLM refiner (basin worker) |
🧪 opt-in — BASIN_LLM=codex (gpt-5.5) or =1 (legacy claude -p, now API-only) |
| Automatic fork detection | ✅ default-on (auto_fork); stores parent session links, LCP metadata, and prefix-only side-chat detection when transcripts preserve the inherited prefix |
| Tests | ✅ 222 passing (engine/tests/) |
This is research-grade software under active development. Interfaces will change.
engine/ Python 3 (stdlib only). The capture/extract/compile engine, the curses TUI, and the `basin` CLI.
plugin/ Host integrations: Claude Code hooks/commands, Codex hooks, install scripts, plugin manifests.
docs/ Concepts and comparison notes.
assets/ Logo.
cd engine
for t in tests/test_*.py; do python3 "$t"; doneMIT.
Basin is named for what it does: scattered context flows in, settles, and accumulates into something you can stand on.