volens (如意)

Name: funcpn/volens
Author: funcpn

English | 中文

volens is a plugin for coding agents. It maintains a structure that keeps a project's documentation in step with its decisions and permanently fresh — the design doc follows every decision you make, and you never have to think about it. And you only need to set it up once in a project: the spell stays cast, with no need to cast it again each time you change your mind.

Works with:

Claude Code
Codex CLI, the ChatGPT desktop app
DeepSeek Harness (DSH)

More agent support is planned.

Why you need volens

Thanks to how quickly models improve and how mature agent products have become, our ideas can go from thought to working code with an agent's help, without being shut out by technical know-how we don't have. But on the way from a rough idea to a finished piece of work, something else happens. As we flesh the idea out, pick apart each detail, and learn and choose between technologies while building, the blueprint in our head keeps changing — changes that can overturn earlier decisions, or leave us going back and forth on the same one. And over time, hand-maintained design docs drift quietly out of date: they mislead us, they leave the project messy, and they make the model more likely to hallucinate.

volens is a plugin built to solve exactly that:

It maintains an append-only decision log (docs/DECISION-LOG.md), recording every decision we make so that each one is traceable;
It derives the design doc from that log (docs/DESIGN.md) and can update it automatically, keeping the design doc in step with decisions and permanently fresh, without us having to care;
Whether you're landing a new idea or iterating on an existing project, volens can help — it keeps the design snapshot following your decisions.

volens keeps the design doc in step with your thinking. Let your agent implement code from the design doc, and the project comes out the way you want it.

How it works

Run volens once in a project (Claude Code: /volens:volens; Codex: $volens:volens; DSH: /volens). It first surveys what already exists in the project (it will not overwrite anything), then puts the following files in place:

The contract module in the project's instruction file — CLAUDE.md on Claude Code, AGENTS.md on Codex and DSH (DSH loads both files and deduplicates them only when their content is identical). If the file doesn't exist, it creates one containing only the contract module; if it does, it inserts or updates the module between the markers, holding the documentation model + working agreements. Nothing else in the file is touched.
docs/DECISION-LOG.md — an append-only decision log, seeded with one entry recording the adoption of this structure. Every later design decision is appended here; history only grows, never changes.
docs/DESIGN.md — a design snapshot derived from the log. An existing project gets one at scaffold time; a brand-new project skips it, and the sync mechanism generates it from the decision log on the first sync.
.volens/lang — the "project-level decision" of which language this project's docs are recorded in, written as a language tag (zh, en, pt-BR), asked once and committed. A value that is not a tag is ignored: the sync mechanism falls back to your preference and says so in the next sync notice. (Earlier versions wrote it to .claude/volens.lang; an older project's file still works, and volens moves it to the new location on the next refresh.)
docs/.volens-cursor — the sync mechanism's cursor: it records how far into the log the design doc has been reflected. Pure runtime state; written to .gitignore, never committed.

The sync mechanism itself ships with the plugin and is never written into your project — the files above are the only ones volens adds there.

With those in place, day-to-day freshness runs on an append → notice → incremental sync loop:

The decision lands — each time you make a design decision, append an entry to docs/DECISION-LOG.md (Context → Decision → Consequences). Append only; never rewrite history.
The sync notices — it runs automatically at every session moment (Claude Code: Stop (a reply ends) and SessionStart (a session begins); Codex: UserPromptSubmit, on every message you send; DSH: at the head of every turn, from the in-process plugin), comparing the log's line count against the docs/.volens-cursor cursor.
The delta is injected — if the log has lines beyond the cursor, exactly those lines are handed to the agent as additional context to sync from; if the design doc is already current, the cursor is silently fast-forwarded.
Only the affected parts are regenerated — the agent updates only the affected sections of the design doc, the "Design decisions in force" list, and the "Last regenerated" header. It doesn't re-read the whole log or rewrite the whole document. If the log was rewritten or rolled back (line count drops), the cursor is reset and a full rebuild of docs/DESIGN.md is requested.

So docs/DESIGN.md is always a snapshot of the design "as of now" — derived from the log, kept fresh automatically. You make the decisions; volens handles the rest.

What the sync mechanism does — and doesn't

The sync mechanism ships inside the plugin. On Claude Code it is registered by hooks/hooks.json and runs on Stop (a reply ends) and SessionStart (a session starts, is cleared, or is compacted); on Codex it is registered by hooks/hooks-codex.json and runs on UserPromptSubmit only — every message you send. Those two share one shell script. DSH does not go through a hook at all: the same logic runs as JavaScript inside its own process (index.js), triggered at the head of every turn.

What it reads — the line count of docs/DECISION-LOG.md, the number stored in docs/.volens-cursor, the modification time of docs/DESIGN.md, and your language preference (~/.config/volens/lang — or under XDG_CONFIG_HOME when that is set — or the project's .volens/lang).

That is the whole list. It never reads the contents of your log, your design doc, or your source code — it counts lines in one file and compares one timestamp.

What it writes — exactly one file, docs/.volens-cursor. It does not write docs/DESIGN.md itself: it emits a prompt asking the agent to, and the cursor advances only once that write has landed.

What it doesn't do:

No network. No HTTP, no sockets, no telemetry, no analytics. Nothing leaves your machine.
No writes outside docs/. It never touches your source or your instruction file, and it only ever reads .volens/lang.
No execution of anything from your project. The logic is fixed and ships with the plugin: on Claude Code and Codex it is a shell script, on DSH it is plugin code running inside the agent's own process.
No blocking. On Claude Code and Codex it always exits 0; on DSH it returns no decision. Either way it can only ever add context to the conversation — it cannot stop a turn or refuse a tool call.
No injection into subagent sessions (DSH). A subagent inherits its parent's working directory and could not act on the delta, so DSH skips it.

When there is nothing to sync it prints nothing. Silence means nothing was injected — not that something failed.

Install

Prerequisites:

git is on your PATH
git can reach GitHub
a bash to run the hook with

macOS and Linux ship one; on Windows, install Git for Windows — and if you have WSL, the bash.exe it puts in Windows\System32 does not count: it is a launcher into a Linux distro and cannot run the hook.

DSH is the exception on both counts: its half runs in-process, and its skill ships inside the same npm package, so it needs neither a bash nor a checkout of this repository.

Install in Claude Code

Add the marketplace:

/plugin marketplace add https://github.com/funcpn/volens.git

Install from the marketplace:
```
/plugin install volens@volens
```
Confirm it installed: run claude plugin list and look for volens@volens with status ✔ enabled.

Install in Codex

volens installs into Codex as a plugin too, through Codex's own marketplace mechanism:

Add the marketplace:

codex plugin marketplace add https://github.com/funcpn/volens

Install from the marketplace:
```
codex plugin add volens@volens
```
Confirm it installed: run codex plugin list and look for volens with status installed, enabled.

The marketplace and the plugin share the name volens, which is why the install line reads volens@volens — marketplace first, plugin second.

Install in the ChatGPT desktop app (Codex)

The same plugin, the same mechanism: in the app's plugin screen, add the marketplace https://github.com/funcpn/volens (leave Git ref empty) and install volens. From there the usage is identical to Codex — volens:volens shows up in the slash menu.

Only two things differ, and both are worth knowing before you rely on them:

Installing does not authorize the hook, and nothing asks. An untrusted hook is skipped in silence — no dialog, no badge, no injection — so the plugin looks healthy while docs/DESIGN.md quietly stops updating. To authorize it, open volens's plugin detail (manage) page and choose Trust all under "1 hook needs review before it can run". That page shows the command string it is asking about — which file will run — not the script's contents, and the trust is bound to that string: a later plugin update that leaves the command alone does not ask again.
The sync notice arrives as a tooltip, not as a line in the conversation. Hover the hook icon in the session to see it; the terminal CLI prints the same notice inline (↳ Hook · 📝 DECISION-LOG …).

Install in DSH

DSH does not read a plugin manifest the way the other two do. It loads cordis bundles — npm packages that ship a configuration layer — into its own process, and it discovers skills from registered providers rather than from a plugin's manifest. volens-dsh is both at once: the sync plugin and the skill travel in the same package, so there is nothing to place by hand.

Install it into a profile:
```
dsh plugin --profile web add volens-dsh
```
This is pnpm add run inside ~/.dsh/profiles/web; web is the shipped web template, so swap in your own profile name if it differs. The package declares a bundle, so installing it makes its layer available to that profile — and it registers its skill, which is why /volens is in the menu once DSH has restarted.
Restart DSH: the profile's patch and the plugin module are read at process start.

Two things worth knowing before you rely on it:

Updating means naming the version. The command runs pnpm add inside the profile, and pnpm leaves an installed package alone while the recorded range is satisfied — add volens-dsh on an installed copy reports "Lockfile is up to date" and changes nothing. Name the version instead (add volens-dsh@0.4.0); if that release is newer than the profile's supply-chain policy allows, the CLI says so and adds it to minimumReleaseAgeExclude in the profile's pnpm-workspace.yaml before installing. The skill ships in the same package, so it arrives with it.
The sync notice arrives as a collapsed context row, not as a line of its own. Look for a small context icon with volens and the notice text beside it — it sits where tool-call rows sit, and is easy to scroll past. The synchronization does not depend on seeing it.

Alternative: install from a ZIP

If git can't reach GitHub, Claude Code and Codex can install from a download instead. Downloading and unpacking are the same either way; putting the folder in place is where they diverge. (DSH does not need this: its package comes from npm, with the skill inside it.)

Get the folder first:

Open this repository's Releases page and, under the newest version, download Source code (zip) — or the packaged zip, if that version attaches one
Unpack it. The folder name carries a suffix (volens-0.4.0, volens-main, …) — rename it to volens

Claude Code — move the whole folder into your skills directory:

macOS / Linux: ~/.claude/skills/
Windows: %USERPROFILE%\.claude\skills\

Create that directory if it doesn't exist. You should end up with …/.claude/skills/volens/, containing .claude-plugin, skills and hooks. Restart Claude Code, then run claude plugin list and confirm you see volens@skills-dir with status ✔ loaded.

Codex — the folder can live anywhere (say ~/plugins/volens); add it as a local marketplace:

codex plugin marketplace add ~/plugins/volens
codex plugin add volens@volens

Run codex plugin list and confirm the status is installed, enabled. Your first session will likewise show Hooks need review — choose Trust all and continue.

How to use it

The plugin only loads after you restart your agent once. After that, in the project you want to bring under the structure, run:

On Claude Code:

/volens:volens

On Codex:

$volens:volens

On DSH:

/volens

Codex asks you to trust the hooks once, on the first run. Your first Codex session will show Hooks need review — choose Trust all and continue. Without it the plugin is installed, but the design snapshot never updates.

DSH has no namespace and no hook to trust. The skill is the bare /volens in the menu; the plugin loads with its profile, so a process restart is all it takes.

It surveys what already exists (it will not overwrite anything), sets the documentation language (once), ensures the contract module is in place, seeds docs/DECISION-LOG.md, and confirms the sync mechanism is live (a hook on Claude Code and Codex, the in-process plugin on DSH). From then on, whenever a design decision changes, append an entry to the log; the sync mechanism handles the rest.

License

This project is open source under the MIT license — see LICENSE.

volens (如意)

English | 中文

Works with:

Claude Code
Codex CLI, the ChatGPT desktop app
DeepSeek Harness (DSH)

More agent support is planned.

Why you need volens

volens is a plugin built to solve exactly that:

It maintains an append-only decision log (docs/DECISION-LOG.md), recording every decision we make so that each one is traceable;
It derives the design doc from that log (docs/DESIGN.md) and can update it automatically, keeping the design doc in step with decisions and permanently fresh, without us having to care;
Whether you're landing a new idea or iterating on an existing project, volens can help — it keeps the design snapshot following your decisions.

volens keeps the design doc in step with your thinking. Let your agent implement code from the design doc, and the project comes out the way you want it.

How it works

The contract module in the project's instruction file — CLAUDE.md on Claude Code, AGENTS.md on Codex and DSH (DSH loads both files and deduplicates them only when their content is identical). If the file doesn't exist, it creates one containing only the contract module; if it does, it inserts or updates the module between the markers, holding the documentation model + working agreements. Nothing else in the file is touched.
docs/DECISION-LOG.md — an append-only decision log, seeded with one entry recording the adoption of this structure. Every later design decision is appended here; history only grows, never changes.
docs/DESIGN.md — a design snapshot derived from the log. An existing project gets one at scaffold time; a brand-new project skips it, and the sync mechanism generates it from the decision log on the first sync.
.volens/lang — the "project-level decision" of which language this project's docs are recorded in, written as a language tag (zh, en, pt-BR), asked once and committed. A value that is not a tag is ignored: the sync mechanism falls back to your preference and says so in the next sync notice. (Earlier versions wrote it to .claude/volens.lang; an older project's file still works, and volens moves it to the new location on the next refresh.)
docs/.volens-cursor — the sync mechanism's cursor: it records how far into the log the design doc has been reflected. Pure runtime state; written to .gitignore, never committed.

The sync mechanism itself ships with the plugin and is never written into your project — the files above are the only ones volens adds there.

With those in place, day-to-day freshness runs on an append → notice → incremental sync loop:

The decision lands — each time you make a design decision, append an entry to docs/DECISION-LOG.md (Context → Decision → Consequences). Append only; never rewrite history.
The sync notices — it runs automatically at every session moment (Claude Code: Stop (a reply ends) and SessionStart (a session begins); Codex: UserPromptSubmit, on every message you send; DSH: at the head of every turn, from the in-process plugin), comparing the log's line count against the docs/.volens-cursor cursor.
The delta is injected — if the log has lines beyond the cursor, exactly those lines are handed to the agent as additional context to sync from; if the design doc is already current, the cursor is silently fast-forwarded.
Only the affected parts are regenerated — the agent updates only the affected sections of the design doc, the "Design decisions in force" list, and the "Last regenerated" header. It doesn't re-read the whole log or rewrite the whole document. If the log was rewritten or rolled back (line count drops), the cursor is reset and a full rebuild of docs/DESIGN.md is requested.

So docs/DESIGN.md is always a snapshot of the design "as of now" — derived from the log, kept fresh automatically. You make the decisions; volens handles the rest.

What the sync mechanism does — and doesn't

That is the whole list. It never reads the contents of your log, your design doc, or your source code — it counts lines in one file and compares one timestamp.

What it doesn't do:

No network. No HTTP, no sockets, no telemetry, no analytics. Nothing leaves your machine.
No writes outside docs/. It never touches your source or your instruction file, and it only ever reads .volens/lang.
No execution of anything from your project. The logic is fixed and ships with the plugin: on Claude Code and Codex it is a shell script, on DSH it is plugin code running inside the agent's own process.
No blocking. On Claude Code and Codex it always exits 0; on DSH it returns no decision. Either way it can only ever add context to the conversation — it cannot stop a turn or refuse a tool call.
No injection into subagent sessions (DSH). A subagent inherits its parent's working directory and could not act on the delta, so DSH skips it.

When there is nothing to sync it prints nothing. Silence means nothing was injected — not that something failed.

Install

Prerequisites:

git is on your PATH
git can reach GitHub
a bash to run the hook with

macOS and Linux ship one; on Windows, install Git for Windows — and if you have WSL, the bash.exe it puts in Windows\System32 does not count: it is a launcher into a Linux distro and cannot run the hook.

DSH is the exception on both counts: its half runs in-process, and its skill ships inside the same npm package, so it needs neither a bash nor a checkout of this repository.

Install in Claude Code

Add the marketplace:

/plugin marketplace add https://github.com/funcpn/volens.git

Install from the marketplace:
```
/plugin install volens@volens
```
Confirm it installed: run claude plugin list and look for volens@volens with status ✔ enabled.

Install in Codex

volens installs into Codex as a plugin too, through Codex's own marketplace mechanism:

Add the marketplace:

codex plugin marketplace add https://github.com/funcpn/volens

Install from the marketplace:
```
codex plugin add volens@volens
```
Confirm it installed: run codex plugin list and look for volens with status installed, enabled.

The marketplace and the plugin share the name volens, which is why the install line reads volens@volens — marketplace first, plugin second.

Install in the ChatGPT desktop app (Codex)

Only two things differ, and both are worth knowing before you rely on them:

Installing does not authorize the hook, and nothing asks. An untrusted hook is skipped in silence — no dialog, no badge, no injection — so the plugin looks healthy while docs/DESIGN.md quietly stops updating. To authorize it, open volens's plugin detail (manage) page and choose Trust all under "1 hook needs review before it can run". That page shows the command string it is asking about — which file will run — not the script's contents, and the trust is bound to that string: a later plugin update that leaves the command alone does not ask again.
The sync notice arrives as a tooltip, not as a line in the conversation. Hover the hook icon in the session to see it; the terminal CLI prints the same notice inline (↳ Hook · 📝 DECISION-LOG …).

Install in DSH

Install it into a profile:
```
dsh plugin --profile web add volens-dsh
```
This is pnpm add run inside ~/.dsh/profiles/web; web is the shipped web template, so swap in your own profile name if it differs. The package declares a bundle, so installing it makes its layer available to that profile — and it registers its skill, which is why /volens is in the menu once DSH has restarted.
Restart DSH: the profile's patch and the plugin module are read at process start.

Two things worth knowing before you rely on it:

Updating means naming the version. The command runs pnpm add inside the profile, and pnpm leaves an installed package alone while the recorded range is satisfied — add volens-dsh on an installed copy reports "Lockfile is up to date" and changes nothing. Name the version instead (add volens-dsh@0.4.0); if that release is newer than the profile's supply-chain policy allows, the CLI says so and adds it to minimumReleaseAgeExclude in the profile's pnpm-workspace.yaml before installing. The skill ships in the same package, so it arrives with it.
The sync notice arrives as a collapsed context row, not as a line of its own. Look for a small context icon with volens and the notice text beside it — it sits where tool-call rows sit, and is easy to scroll past. The synchronization does not depend on seeing it.

Alternative: install from a ZIP

Get the folder first:

Open this repository's Releases page and, under the newest version, download Source code (zip) — or the packaged zip, if that version attaches one
Unpack it. The folder name carries a suffix (volens-0.4.0, volens-main, …) — rename it to volens

Claude Code — move the whole folder into your skills directory:

macOS / Linux: ~/.claude/skills/
Windows: %USERPROFILE%\.claude\skills\

Codex — the folder can live anywhere (say ~/plugins/volens); add it as a local marketplace:

codex plugin marketplace add ~/plugins/volens
codex plugin add volens@volens

Run codex plugin list and confirm the status is installed, enabled. Your first session will likewise show Hooks need review — choose Trust all and continue.

How to use it

The plugin only loads after you restart your agent once. After that, in the project you want to bring under the structure, run:

On Claude Code:

/volens:volens

On Codex:

$volens:volens

On DSH:

/volens

Codex asks you to trust the hooks once, on the first run. Your first Codex session will show Hooks need review — choose Trust all and continue. Without it the plugin is installed, but the design snapshot never updates.

DSH has no namespace and no hook to trust. The skill is the bare /volens in the menu; the plugin loads with its profile, so a process restart is all it takes.

License

This project is open source under the MIT license — see LICENSE.

funcpn/volens

volens (如意)

Why you need volens

How it works

What the sync mechanism does — and doesn't

Install

Install in Claude Code

Install in Codex

Install in the ChatGPT desktop app (Codex)

Install in DSH

Alternative: install from a ZIP

How to use it

License

Community comments

funcpn/volens

volens (如意)

Why you need volens

How it works

What the sync mechanism does — and doesn't

Install

Install in Claude Code

Install in Codex

Install in the ChatGPT desktop app (Codex)

Install in DSH

Alternative: install from a ZIP

How to use it

License

Community comments