backpass
You don't write AGENTS.md. You train it with gradient descent.
What is it?
What it is
backpass is a local-first command-line tool that collects agent session transcripts from seven harnesses (Claude, Codex, pi, opencode, grok, cursor CLI, hermes), distills them, calculates loss, aggregates gradients, and proposes evidence-backed edits to the project's memory file and skills under a token budget, with a human gate before applying.
Why it exists
Agent sessions leave transcripts on disk that are never read, so the only way to improve the memory surface is for a human to manually remember failures and edit the file. backpass closes this loop by automatically analyzing transcripts and proposing evidence-backed edits.
Who should use it
Developers, AI engineers, and technical writers who use AI agent harnesses (Claude, Codex, Grok, OpenCode, Pi, Cursor, Hermes) and maintain memory files such as AGENTS.md or CLAUDE.md. Users who want evidence‑backed, human‑in‑the‑loop improvements to their agent instructions and skills, and who are comfortable installing Node >=22.5 and the `acpx` helper.
Who should avoid it
Users who do not work with AI agent transcripts, who lack the required Node version and `acpx`, or who prefer fully automated changes without human review. Also, those who do not maintain agent memory files or have no agent usage history.
How it works
A quick walkthrough in plain English
How backpass works
Step 1 of 3
You interact with it
Open backpass, send a request, or connect it to your stack.
Features
Advantages
- Local-first design ensures privacy - transcripts never leave the machine
- Strict evidence requirements reduce hallucination and improve reliability
- Two-session minimum requirement for new instructions strengthens quality
- Smart distillation reduces transcript size by 96-99%, making analysis efficient
- Budget system prevents unbounded memory growth and guides pruning
- Extraction mechanism allows converting procedures into reusable skills
- Comprehensive gap tracking helps identify systematic weaknesses in training
- Human gate ensures careful, deliberate updates rather than automated changes
- Multi-harness support accommodates various AI agents in the same workflow
Disadvantages
- High hardware requirements - needs Node >= 22.5 and acpx installed
- Steep learning curve due to complex configuration and conceptual overhead
- Limited to local machines - no cloud-based collaborative features
- Potential for false positives in causal attribution despite safeguards
- Undocumented transcript formats may break if adapters change unexpectedly
- Some harnesses (e.g., Cursor IDE) have version-specific limitations
- Memory file growth concerns, though mitigated by budget controls
- Dependency on specific harness configurations and golden fixtures
- Complex setup required for proper operation compared to simpler alternatives
Installation
native
npm install -g backpass # or run it without installing npx backpass Requires Node >= 22.5 and acpx on your PATH. cd your-repo backpass init # write .backpassrc.json, exclude .backpass/ via .git/info/exclude backpass # collect samples → calculate loss → aggregate gradients → gradient descent (never writes) backpass apply # review each edit, accept or reject, then write
FAQ
How do I install and run backpass?
Install it globally or run it directly: `npm install -g backpass` or `npx backpass`. It requires Node >= 22.5 and the `acpx` CLI on your PATH. After cloning a repo, run `backpass init` to create `.backpassrc.json` and exclude `.backpass/` from git, then `backpass` to collect samples, calculate loss, aggregate gradients, and propose edits (never writes), and finally `backpass apply` to review and write the accepted changes.
What files does backpass read and write?
It reads local transcript stores of seven agent harnesses directly from disk (e.g., `~/.claude/projects/...`, `~/.codex/sessions/...`, `~/.pi/agent/sessions/`, etc.) and never uploads data. It writes everything under `.backpass/` – scan cache, per‑transcript evidence, aggregated gradients, the latest proposal, rejections, a gap ledger, and a staging copy (`.backpass/synthesis/`) used for synthesis. The only files it can edit are the memory surface (`AGENTS.md`, `CLAUDE.md`) and any skill files defined in `skillsDir` (default `.agents/skills`).
How does backpass decide which agent sessions belong to the current repo?
It uses a four‑tier association model: 1) deterministic worktrees (or sessions whose cwd sits inside a worktree), 2) sibling clones that share a git remote with the repo, 3) a git‑remote match recorded in the transcript, and 4) best‑effort path/name matching (e.g., a dead path whose last segment matches the repo name). Use `backpass scan --strict` to see the transcript table with confidence columns and tier labels.
What is the budget and how is it enforced?
The budget limits the always‑loaded surface – the memory file plus every skill’s `description:` line – to a default of 5 000 estimated tokens (~20 KB). The estimator is bytes/4 (harness‑neutral, ±5%). When the surface is at or over budget, synthesis becomes zero‑sum (every addition must name a removal or extraction that pays for it) and `backpass apply` will shrink the surface if it’s over budget. The limit is configurable via `budgetTokens` in `.backpassrc.json` or the `--budget-tokens` flag.
How does the human‑in‑the‑loop apply work?
`backpass apply` is the only command that writes. It launches a deterministic web UI (via `lavish-axi`) showing each proposed edit with its diff, verbatim evidence quotes, source sessions, and a live budget gauge. You can accept or reject edits; rejections are remembered and won’t be re‑proposed unless new evidence arrives. You can also run `backpass apply --no-ui` for a terminal‑only decision, `--dry-run` to preview what would be written, or `--no-open` to get the URL without launching a browser. If any file changed since the proposal (e.g., manual edits, pulls), apply aborts and asks you to re‑run `backpass` to re‑propose against the current repo.
Featured in Videos
YouTube tutorials and walkthroughs for backpass
Alternatives
Similar projects ranked by category, topics, and text overlap.
