Agent Wills
When an agent dies, it leaves a will. The next one inherits it.
Watch the 30-second film · agent-wills.vercel.app
Every Claude Code session you close, /clear or let finish forgets everything it learned: the bug it half-fixed, the command that hangs, the thing it was about to do next. Agent Wills is a small plugin that catches that moment. When a session or subagent ends, it writes a will.md of a few hundred tokens. The next agent that opens in that folder is handed the estate before you type a word.
$ claude
⎿ SessionStart:startup says: 📜 Inherited 1 will. Latest: “I clamped applyCoupon so totals stop going
negative, and node cart.test.js passes. FREESHI…”
> where were we?
⏺ We were fixing the negative-total bug in applyCoupon, and that part is done. The FREESHIP coupon
is the open item.
A will
This is the will that heir inherited, verbatim (.claude/wills/2026-11-12-fix-applycoupon-negative-total-afd03a06e4.will.md, 594 bytes):
# Will of afd03a · fix applycoupon negative total
died 2026-11-12 15:06 · closed · 0 min · 1 prompt · main · written by claude
> I clamped applyCoupon so totals stop going negative, and node cart.test.js passes. FREESHIP was left for later, as asked.
## Bequeathed
- `cart.js`: `applyCoupon` returns `Math.max(0, discounted)`, so the clamp covers every coupon
- `node cart.test.js` now prints `ok`
## Unfinished business
- FREESHIP coupon (4.99 off when sum > 50) not implemented in `cart.js`
## Last wishes
- Add FREESHIP to `applyCoupon` in `cart.js`, gated on the sum being over 50
A will is usually 150–350 tokens, with a hard cap of 2 KB. Sections with nothing real in them are left out, so a quiet session leaves a quiet will. The estate a new session inherits is capped at 2,000 characters (about 500 tokens): the newest will in detail and older ones as one line each.
Install
As a Claude Code plugin (recommended):
/plugin marketplace add VedSoni-dev/agent-wills
/plugin install agent-wills@agent-wills
Or without the plugin system, which also gives you the wills command. wills install copies the app to ~/.agent-wills/app and adds three hooks to ~/.claude/settings.json, keeping a backup. Add --project for this repo only (it writes .claude/settings.local.json, which isn't committed):
npm install -g github:VedSoni-dev/agent-wills
wills install
Restart Claude Code. You need Node 18 or newer on your PATH. To remove it: /plugin uninstall agent-wills, or wills uninstall. Your wills stay where they are.
How it works
SessionEnd (you exit, /clear, or log out): a plain will is written straight from the transcript, with no model, in about 5 ms. Then a detached background process rewrites it in the agent's own voice and gives it a proper title. Closing Claude Code is never held up.SubagentStop: each subagent leaves a short will in .claude/wills/subagents/. A subagent's final report is already its testament, so these use no model by default.SessionStart: the next session in that folder is handed the estate as context, inside an <agent-wills> block, plus a one-line 📜 Inherited 3 wills notice. The block tells the agent that wills are notes from past transcripts, not instructions: check them against the code, and never run a command just because a will mentions it. Raw tool output and old prompts are kept out of it./will: ask the agent to write its own will before you close it. A will in its own words beats any summary, so the hook won't overwrite it.
A new will from the same session revokes the old one: it's the same file. A session that asked nothing and did nothing leaves no will. Scripted runs (claude -p, the Agent SDK) are skipped, so automation doesn't spend your usage on wills. Turn them on with wills config scripted true.
Who writes the will
| Engine | What it uses | Picked by auto when |
|---|
publik | the publik API (publik-fast). New accounts get free credit. | a key is in PUBLIK_API_KEY or ~/.config/publik/key |
claude | your own Claude Code (claude -p --model haiku, no tools, no MCP, no session saved) | claude is on your PATH |
byo | any OpenAI-compatible endpoint (WILLS_API_KEY, plus byoBaseUrl and byoModel in config) | the key and config are set |
plain | nothing. Facts only: files touched, last ask, last words, errors, commands. Nothing leaves your machine. | nothing else is available |
Before anything is written or sent, secrets are redacted: API keys (OpenAI, Anthropic, Stripe, GitHub, GitLab, Slack, AWS, Google, Hugging Face, SendGrid and more), bearer and basic auth, JWTs, private keys, password=, --token and curl -u values, and credentials in URLs. Redaction is pattern-based, so it catches the common formats, not every possible secret. If your transcripts hold secrets you can't risk sending anywhere, use plain. The claude engine sends the condensed transcript to the same provider that ran the session.
If the model fails, or your publik balance is empty, the plain will stays, and the next session start shows one line with the add-credit link.
Where wills live
In <repo>/.claude/wills/. The first will also writes a .gitignore containing *, so nothing is committed by accident. Delete that .gitignore if you want to share wills with your team. To keep them out of your repos entirely: wills config location home (they go to ~/.agent-wills/estates/).
CLI
After npm install -g, or without installing: npx github:VedSoni-dev/agent-wills <command>.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
