Open source · Apache-2.0 · For Codex and Claude Code
Keep the thread.
Your coding agent can reverse last week's decision without ever learning why you made it.
Whyve keeps decisions and their reasons as Markdown in your repository, and brings them back when a later session is about to change course.
$ codex plugin marketplace add https://github.com/swimit-io/whyve.git
$ codex plugin add whyve@whyve$ claude plugin marketplace add https://github.com/swimit-io/whyve.git --scope user
$ claude plugin install whyve@whyve --scope userThe plugin, library, and CLI all require Node.js 20.20.0 or newer.
Not another memory plugin.
Memory tools answer "what happened?" Whyve answers "why did we decide this, and should it change?"
claude-mem and Claude Code's built-in auto memory capture what went on in your sessions, automatically. Whyve records something narrower: the choices that should not be quietly reversed, with the reason, the scope, and the history of what replaced what. You approve what gets recorded, or pick a mode that records for you.
They work side by side. Keep your memory tool. Add Whyve for the decisions.
claude-mem remembers what happened. Whyve remembers why.
One decision across two sessions.
This is the example from the README. Run it in your own project after installing. The dark blocks are the agent's unedited answers from the recording.
1. Session one: decide
I decided this trial will support CSV only and leave Excel for later. I want to validate the first-use flow quickly. Remember this decision.
$ claude -p "I decided this trial will support CSV only and leave Excel for later. I want to validate the first-use flow quickly. Remember this decision." I saved this as a project decision: the trial will support CSV only, and Excel is left for later. The reason is to validate the first-use flow quickly. There was no earlier decision on file formats, so nothing conflicts with it. - File: context/decision/Trial-supports-CSV-only-Excel-deferred.md - Scope: trial-importer, with the decision key trial-import-file-formats You didn't say when to come back to Excel support, so I didn't record a condition for that. If you want one, such as "once the first-use flow is validated," tell me and I'll add it. $ ls context/decision Trial-supports-CSV-only-Excel-deferred.md decision.index.mdWhyve confirms what it recorded: the decision and the reason.
2. Session two: ask why
Why did we postpone Excel support?
$ claude -p "Why did we postpone Excel support?" Excel support was postponed to validate the first-use flow quickly. The current decision for trial-importer (context/decision/Trial-supports-CSV-only-Excel-deferred.md) says: - Decision: This trial supports CSV only. Excel support is left for later. - Rationale: Validate the first-use flow quickly. - Rejected alternatives: Supporting Excel in this trial (deferred to later). The record doesn't set a condition for when to revisit Excel. It is deferred, not ruled out, so bringing it back is still an open choice for later.The new session has none of the earlier conversation. It answers from the stored reason.
3. Later in session two: propose a change
What about including Excel in this trial too? I haven't decided to change the decision yet.
$ claude -p --continue "What about including Excel in this trial too? I haven't decided to change the decision yet." This would conflict with the current decision for trial-importer (trial-import-file-formats): - Decision: "This trial supports CSV only. Excel support is left for later." - Rationale: "Validate the first-use flow quickly." - Rejected alternatives: "Supporting Excel in this trial (deferred to later)." The record has no condition for revisiting it, so nothing in it signals that now is the time. Since you haven't decided, I'm treating this as discussion only. I won't change any code or the decision record. Reasons to keep CSV only: - It still fits the stated goal. The first-use flow gets validated with fewer moving parts. - Excel adds work that isn't about the flow itself: sheets, merged cells, dates stored as numbers, formulas, encoding quirks, and a new parsing library. - If the trial goes badly, you'll know the cause is the flow, not the file parsing. Reasons to add Excel now: - If most target users keep their data in .xlsx, a CSV-only trial may measure people giving up at the export step, not the flow itself. - If the import pipeline is already format-neutral, adding Excel later may cost about the same as adding it now. A middle option: keep CSV only, but track how often users try to upload .xlsx or ask for it. That gives you evidence for when to revisit without changing scope. When you're ready to decide: keep CSV only for this trial, or supersede the decision and include Excel? If you choose supersede, I'll update the decision record and then start the implementation work.Whyve places the proposal alongside the existing decision and its reason. Nothing is replaced. A proposal stays a proposal until you decide.
Full run, including session IDs and versions: assets/demo/transcript.txt
Plain Markdown, recorded on your terms.
Records are Markdown files in context/. Git is optional. There is no hosted service, database, or API key.
Run $whyve:init in a project to choose which record types to use and how recording is approved. By default, only Decision records are on and the mode is explicit.
| Kind | What it holds |
|---|---|
| Decision | A choice you made, with its reason and what it replaced |
| Assumption | Something you are treating as true until checked |
| Term | A word with a specific meaning in this project |
| Intent | What the project is for and what done looks like |
| Document | A living explanation kept current |
| Observation · Snapshot · Archive | Always available: verified findings (Observation), where work left off (Snapshot), and the original text of adopted records (Archive) |
| Mode | When Whyve records |
|---|---|
explicit | A clear decision or "remember this" counts as approval. Whyve asks only when the meaning or scope is unclear. |
auto | Eligible context is recorded without asking each time. |
adaptive | The model records directly, or asks when confirmation matters. |
In every mode, the model cannot turn its own preference into your decision.
Two terminal commands for the agent you already use.
$ codex plugin marketplace add https://github.com/swimit-io/whyve.git
$ codex plugin add whyve@whyve$ claude plugin marketplace add https://github.com/swimit-io/whyve.git --scope user
$ claude plugin install whyve@whyve --scope userThe plugin, library, and CLI all require Node.js 20.20.0 or newer.
Then restart Codex or Claude Code, or start a new session, and run $whyve:init (Codex) or /whyve:init (Claude Code) in your project.
Using the TypeScript library or CLI directly? See the Node API guide.
Coming from context-* plugins? Disable them first. Don't run the old and new plugins side by side.
What we've checked. What we haven't.
Checked
The repository's Node tests exercise recording decisions and their reasons, keeping the earlier reason when a decision is replaced, and reading current and historical records.
See the tests tests/node
Not yet shown
We have not shown that Whyve is more accurate, or cheaper in tokens or money, than well-kept Markdown or ADRs. We have not measured long-term effects in real teams. The two-session example above is the fastest way to judge whether it helps your project.
Built with Whyve: Howse
Howse is a desktop app for macOS and Windows (Windows is in beta) that runs several coding agents as one team: Codex and Claude Code take roles, hand work to each other in threads, and stop for your approval. Whyve is built in, so a decision made in one agent's session is there for the next agent.
Whyve Cloud is coming soon.
The same context on every device you work from, kept in sync without Git. Whyve itself stays open source and local.
About the name
Whyve and Howse come from one belief: when you work with agents, the reasons behind your work and the way your team operates should live in files you own.
Whyve = why + weave
Whyve is why + weave. It weaves the reasons behind your choices into a thread that carries from one session to the next. Its sibling, Howse, is how + house: it houses how your agents work.
Whyve is the foundation. Howse is the first product built on it.
Made by Jinwuk Lee · @Jeis-Jw