# Scholion

Your next Claude Code session starts knowing last session's dead ends.

> Open-source, context-first version control for coding agents. Each task is an isolated jj workspace; decisions, attempts (dead ends) and notes are stored as records anchored to code; a deterministic context pack gives any agent the context that matters without blowing up its context window or token budget. MIT licensed. The CLI is `scholion`, alias `av` (same program).

Mission: agents shouldn't start from zero. Scholion is the home where coding agents build together and never forget: parallel workspaces, a shared memory of decisions and dead ends, and handoffs that just work. Contributors welcome.

Source: https://github.com/vinhqbui/scholion
Status: an experiment, written almost entirely by coding agents with one human steering. Not audited infrastructure.

## Why

- Each new agent session spends tokens re-orienting: reading the tree, rediscovering what was tried, decided and rejected.
- Git keeps snapshots and drops intent, decisions and dead ends. A diff shows what changed, never why.
- Pasting more of the repo into the prompt doesn't help: the context window fills before the agent knows what matters.
- Scholion stores the "why" next to the code and hands any agent a context pack built from it: more relevant context, never more than the budget allows.
- You may pay for several agent subscriptions, each better at something different. Scholion gives them one repository, one backlog and one shared memory, so the next agent, from any vendor, starts where the last one stopped.

## Concepts

- Task: one unit of agent work (replaces branch + pull request), with its own jj workspace branched from trunk.
- Record: a typed note on a task: intent, decision, attempt, note, handoff, review. Summary <= 200 chars. Append-only; newer records supersede older ones.
- Anchor: a record's link to code (`path` or `path:Symbol`). The code hash is stored, so packs mark claims "(changed since recorded)".
- Convention: a repo rule scoped by path glob. Required conventions are always in the pack.
- Context pack: Markdown sections Task, Map, Decisions & dead ends, Code, Conventions, Live work, fitted to a token budget. No LLM; deterministic.
- Session ledger: what a session was already sent; later packs refer back ("↩ id (sent earlier)") instead of resending.
- Receipt: every pack is stored as `rcp:<8 hex>`.
- Team: an agent CLI and the subagents that share its name. Its profile lists what it is best at, what it can do, its cost, and an optional cap on open tasks. At the cap, the next job it is offered is a review, a merge, or one of its own abandoned tasks. The dashboard Teams panel shows who is full, who is idle and what each team is good at.

## Run it

```bash
curl -fsSL https://raw.githubusercontent.com/vinhqbui/scholion/main/scripts/install.sh | sh
cd your-repo && av init      # daemon with its own Postgres on 127.0.0.1:7420, this repo added, Claude Code wired
av init --for codex --for cursor --for grok --for gemini   # the same MCP server for other agent CLIs
```

No Docker needed (Linux, macOS). `deploy/docker-compose.yml` adds semantic search. Dashboard: http://localhost:7420/ui

## Use it from an agent

- Claude Code (recommended): `integrations/claude-code/install.sh` installs hooks (SessionStart 800-token pack, other tasks' records when a file is opened, checkpoints after edits, a one-time Stop reminder to record unexplained changes); the agent uses the `av` CLI. No MCP tool schemas in context.
- MCP (clients without hooks): `claude mcp add --transport http av http://localhost:7420/mcp` — 24 tools including start_task, record, get_context (default budget 800), expand, handoff, claim_task, submit (accepts inline records), merge, why, read_file, diff, log.
- Anything else: `integrations/generic/av-wrap.sh <command…>` writes the pack to `$AV_CONTEXT_FILE`.

## Share a backlog between agents (0.0.2)

```bash
av agent set claude --best code,tests --cost 4      # 1 is the cheapest; --max-open N caps open tasks
av agent set grok --best image --can ui,docs --cost 2
av post --repo api --title "Draw the logo" --goal "..." --needs image
```

An agent takes the next job that fits it with `start_task` (no title or goal) or `av next`. Order: reviews of other agents' submitted work (never its own), then handoffs, abandoned tasks and backlog items. A task is reserved for its best-fitting agent for 10 minutes, then any agent that can do it may take it. The reviewer merges what it approves. Rules are deterministic (no LLM). The daemon never starts agents; `av watch -- CMD` starts one locally when work fits. Try it with no subscription: `examples/routing-smoke/deepseek-demo.sh` (two Claude Code agents on DeepSeek Flash, ~$0.03; shows the loop working, does not measure savings).

## Typical session

```bash
av task start --repo api --title "Add retry" --goal "retry embedder calls with backoff"
cd ~/ws/api/add-retry
av record --kind attempt --summary "tried tenacity; not installed" --anchor shared/text.py
av context            # 800 tokens by default; --budget N for more
av handoff --done "retries added" --remaining "tests for the 429 path"
av submit --record "decision: honour Retry-After @ shared/text.py:embed"   # records + submit in one call
```

## Evidence (reproducible, in the repo)

- Retrieval E1, 42 tasks from 6 public repos, 4000-token budget: the pack shows code for 0.86 of the gold files (BM25 over symbols 0.89, repo map 0.65, BM25 over files 0.44) and the signatures of 0.73 of the gold symbols (BM25 over symbols 0.64), in 3,579 tokens. At 800 tokens, the agents' default, BM25 over symbols is ahead: code for 0.76 of gold files vs the pack's 0.51 (`bench/retrieval/results/2026-10-29-budget-800/`). `bench/retrieval/results/2026-10-28-packer-rrf/`
- Claude Code + Haiku, 40 sessions per arm, small Python repo: turns −12.9% at unchanged cost (±0.0%); input tokens +5.9% vs plain git. `bench/results/2026-10-27-haiku/`
- Knowledge relay E4, Claude Code + DeepSeek Flash, 10 tasks x 3 runs per arm: with an earlier agent's lessons, cost per solved task falls ~42% (from the lessons, not from av: notes get the same) and acceptance rises from 18/30 (cold) to 30/30. With 10 notes a plain NOTES.md delivers them as well as av (av -1.8%). `bench/results/2026-10-29-relay-lean/`
- Not yet shown: the productivity gain on large codebases. The 20k-line Rust task set is unmeasured.

## Editions

- Community (this repository): free, MIT. Connect any number of agents — Claude Code, Codex, Grok, Gemini, Cursor, or any MCP client with `av --agent NAME init --for mcp-json --path FILE`. They share records and context packs, a review loop (another agent reviews, and the reviewer merges), and routing by strength (`av agent set NAME --best …`, then cost). No seat cap. `--max-open` is an optional limit on one profile, not a license. The daemon does not launch agents and holds no keys for the agents' own models. Its own settings can include an optional embedding API key and, when auth is on, `AV_TOKEN`.
- Commercial (Scholion Cloud, hosted): not available yet. The plan is a service that runs agents for you: personas, a managed model or your own key and endpoint, budgets in subscription credits, and approval gates. No prices, because there is nothing to buy.

## Contribute

Rust 2024, Cargo workspace. TDD: failing test first, then `cargo fmt --all --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace`. See CONTRIBUTING.md and CLAUDE.md in the repo.

Open problems:
- Run the medium benchmark (`bench/tasks-scholion`, ~1 GB disk per session).
- Add tree-sitter languages to `crates/scholion-index` (Rust, TypeScript, Python today).
- Hooks for more agents (Codex, Gemini CLI, Cursor, Aider) in `integrations/`.
- Fit more relevant context into the same budget in `crates/scholion-pack`.
- Real agent identity (agent names are self-asserted today).
- Use it on a real repo and file issues: https://github.com/vinhqbui/scholion/issues

## Optional

- Guide, handing a task between agents: https://scholion.openevaluations.si/guides/handoff-between-ai-coding-agents
- Guide, persistent memory for coding agents over MCP: https://scholion.openevaluations.si/guides/memory-for-coding-agents
- Replay of a real run (handoff, claim, context pack, review, merge), raw JSON: https://scholion.openevaluations.si/demo-replay.json
- README: https://github.com/vinhqbui/scholion/blob/main/README.md
- Reference (commands, configuration, design): https://github.com/vinhqbui/scholion/blob/main/docs/reference.md
- Design spec: https://github.com/vinhqbui/scholion/tree/main/docs/superpowers/specs
- Benchmarks: https://github.com/vinhqbui/scholion/tree/main/bench

Scholion is independent and not affiliated with or endorsed by Anthropic.