backpass: gradient descent for your AGENTS.md

The loop backpass is trying to close

Your AGENTS.md is treated as a set of weights. Each agent session is a forward pass. The transcript that session leaves on disk is the loss signal, and the README's own framing is that today nothing reads it: the loop closes only when a human happens to remember a failure and edits the file by hand. That is the problem backpass addresses, and it is narrower than "better agent memory". It assumes you already have a memory surface (AGENTS.md, CLAUDE.md, project skills) and a history of sessions that ran against it. If either is missing there is nothing to train.

The intended user is someone running agents in a repository often enough that the same mistake recurs, and who would rather review proposed diffs than write memory text from scratch. The README describes the loop as: collect samples, distill, calculate loss, aggregate gradients, then gradient descent producing diffs and skill extractions, then a human gate, then back to the weights. One run is one bounded gradient step. That framing matters for expectations: backpass is not trying to rewrite your instructions, it is trying to make small edits that are each backed by quotes.

How the pipeline works, from transcript to proposed diff

The mechanism is a four-stage pipeline over transcripts that are already on disk. Collection reads the transcript stores of seven agent harnesses directly, locally or over SSH to your own machines. Distillation turns raw sessions into samples. Loss calculation and gradient aggregation compare what the sessions show against the current memory surface. The final stage emits diffs and skill extractions rather than writing them.

Two design choices carry most of the weight. First, every proposed edit carries verbatim quotes from real sessions, and every add, rewrite or remove edit needs evidence from at least two distinct sessions. That is a real constraint, not a slogan: a single noisy session cannot move the file. Second, analysis never writes. backpass apply is the only writing command, and it shows each edit with its evidence for you to accept or reject. The scope of a run is one target. The default is the checkout you are in; backpass --scope user trains the always-loaded user file and user-level skills from Claude Code and Codex sessions across projects, and writes only those files. A project-scoped run never writes a user-level file. In user scope, add, rewrite and remove edits additionally clear minGapProjects (default 1), meaning the distinct projects behind the edit's own quotes, counted from the gap clusters it cites and the session-to-project map behind the instruction evidence rows; extract and move edits stay exempt. That is the guard against promoting one project's quirk into a global instruction.

Installing backpass and running a first pass

backpass ships on npm with no runtime dependencies and requires Node >= 22.5, plus acpx on your PATH. The README is explicit that backpass has no API keys of its own: every model call goes through acpx to a harness you have already authenticated. Install it globally, or run it without installing.

npm install -g backpass
# or run it without installing
npx backpass

Then, from inside the repository you want to train, initialise the config. init writes .backpassrc.json and excludes .backpass/ via .git/info/exclude, so the working state does not show up in git status. A plain backpass run does collection, loss calculation, gradient aggregation and gradient descent, and writes nothing. Only the third command writes, and it prompts per edit.

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

After the second command you should see proposed diffs and skill extractions, each attached to quotes from sessions. If the quotes do not look like text from sessions you actually ran in that repo, stop and check the harness transcript path before applying anything. The user-scope variant is the same three commands with the flag added.

backpass init --scope user
backpass --scope user
backpass apply --scope user

State for that mode lives in $XDG_CONFIG_HOME/backpass/user/ (default ~/.config/backpass/user/) with mode 0700, isolated from every project's .backpass/.

SSH collection, and the personal-config rule that stops a shared file from pointing at your machines

Sessions you ran on your own other machines can join the same corpus over SSH. Hosts are named once in a personal config file at $XDG_CONFIG_HOME/backpass/config.json (default ~/.config/backpass/config.json). An entry can be a bare hostname string or an object that sets an absolute remote node path, an optional harnesses subset, a positive integer connectTimeoutSeconds (default 10), and store relocation variables under env. The allowed variables are CLAUDE_CONFIG_DIR, CODEX_HOME, HERMES_HOME, PI_CODING_AGENT_DIR, PI_CODING_AGENT_SESSION_DIR, BB_DATA_DIR and BB_PI_.

The rule worth noticing: discovery.hosts in a repo's .backpassrc.json is refused by name. The README's reasoning is that a checked-in file can never point someone else's backpass at a machine. That is a sensible boundary, and it also means you cannot commit a shared host list for a team; each person keeps their own. For a single run you can pass --host <dest>, repeatable, or --host none to collect locally only.

Where backpass gets it wrong, or is simply the wrong tool

The two-session evidence floor is the feature and the limitation at once. If your repository has only one or two recorded sessions, add, rewrite and remove edits will not clear the gate, and you will get little more than extract and move edits. That is correct behaviour, but it makes backpass useless as a first-day tool: it needs a corpus before it has opinions.

User scope has a sharper failure mode. The canonical user memory is the first existing file in this order: ~/.agents/AGENTS.md, $CLAUDE_CONFIG_DIR/CLAUDE.md (default ~/.claude/CLAUDE.md), and $CODEX_HOME/AGENTS.md (default ~/.codex/AGENTS.md). If you have more than one of those on disk, backpass trains whichever resolves first, which may not be the file your harness actually loads. The README does flag a related trap for skills: user-level skill extractions default to ~/.agents/skills, with a warning if Claude's active skills path is a real directory rather than the usual symlink. Read that warning rather than dismissing it.

The read-only case is handled explicitly. A target that resolves into a read-only store (nix, home-manager) is refused by name rather than written, and the whole path is resolved, so the link may be the file itself or a directory on the way to it. Both messages name the resolved location. Finally, backpass is not an autonomous memory writer and does not try to be. If you want a tool that edits AGENTS.md without asking, this is the wrong design for you. It is also macOS and Linux only, per the platform badge; Windows is not claimed.

What else reads your transcripts, and how it differs

The obvious comparison is hand-editing AGENTS.md after a bad session, which is what the project says happens today. The difference is not automation for its own sake: hand editing acts on the one failure you remember, while backpass requires two distinct sessions to agree before it proposes an add, rewrite or remove. The trade is latency and volume. A human can fix a real problem in thirty seconds; backpass waits for the corpus to justify it.

The second comparison is a general coding agent pointed at your transcript directory with instructions to summarise what went wrong. That approach has no evidence gate, no per-edit accept or reject, and no separation between analysis and writing, so a single hallucinated pattern can land in the memory file. backpass inverts the defaults: the analysis stage is read-only, the write stage is interactive, and every edit carries quotes you can check against sessions. What backpass gives up in flexibility it gains in auditability. Whether that trade is worth it depends on how much you trust a summary you cannot trace.

Maintenance, licensing and what a version bump costs you

backpass is MIT licensed, published as the npm package backpass, with the CLI entry at ./bin/backpass.js and the published files limited to bin, src, templates, LICENSE and README.md. MIT is permissive, so the usual obligations apply: keep the licence text when you redistribute. Nothing here is legal advice, and the repository's LICENSE file is the authoritative text.

The release history is dense, with 0.1.20, 0.1.21 and 0.1.22 landing on consecutive days through 2026-09-13, which is also the date of the last push. That cadence tells you the surface is still moving, and the package is still on 0.1.x. The practical upgrade cost is low for the tool itself (npm install -g backpass, or npx backpass) and higher for your configuration expectations: harness load paths, the canonical user-memory resolution order, and the allowed env variable list are the parts most likely to shift between minor versions. The repository keeps a CHANGELOG.md and RELEASING.md, so read the changelog entry rather than assuming a 0.1.x bump is inert. The project has no runtime dependencies, which keeps the upgrade surface small.

Editorial conclusion

Adopt backpass if you already run Claude Code or Codex in a repo and your AGENTS.md has drifted from what the sessions actually do; the evidence gate (two distinct sessions per add, rewrite or remove) is the part worth trusting, because it refuses to act on a single bad run. Skip it if you have no local transcripts to mine, if you cannot put acpx on PATH, or if you want an autonomous writer, since backpass apply is the only command that touches files and it stops for your accept or reject on every edit. Before your first real run, verify two things: that your harness's memory file is the one backpass resolves as canonical (for user scope, the first existing of ~/.agents/AGENTS.md, $CLAUDE_CONFIG_DIR/CLAUDE.md and $CODEX_HOME/AGENTS.md), and that a dry backpass run in a scratch repo produces quotes you recognise from sessions you actually ran. If the quotes look foreign, the transcript store path is wrong, not the model.

Frequently asked questions

Official sources

1. Issues
2. kunchenguid/backpass on GitHub
3. License: MIT
4. README
5. Releases