v0.14.0

capcom — v0.14.0 — 2026-11-01

This release lets the capcom block live in a file of your choosing instead of AGENTS.md, and makes capcom ready and capcom next explain an empty result.

Breaking changes

• New stores use store format 6 — capcom init now writes format: 6 into .capcom/config.yaml, and earlier capcom releases refuse to open a store that declares it. What to do: upgrade capcom on every machine and agent that works in the repository before creating a store with this release, or before raising an existing store to format: 6 to use agents.file.

New

• Put the capcom block in a file other than AGENTS.md — set agents.file in .capcom/config.yaml to a path inside the repository (such as docs/capcom.md) and capcom keeps its block there; it defaults to AGENTS.md, cannot also be listed under agents.guides, and needs format: 6, with a clear error telling you to set it when the store declares an older format.
• capcom agents and capcom check follow the chosen block file — capcom agents writes the block there, creating the file and any missing folders, and adds an import line such as @docs/capcom.md to an AGENTS.md that lacks one. When the block lives outside AGENTS.md, capcom check and capcom agents --check fail if AGENTS.md is missing, does not import the block file, or still holds capcom block markers, and capcom agents warns about a missing AGENTS.md without creating it.
• capcom ready and capcom next explain an empty list caused by ready.hide — when every Ready issue is hidden by a ready.hide label, both commands now warn how many are hidden and by which labels, and point to --show-hidden; the warning appears as a warning: line, in the --json warnings array and as a WARNING= line under next --kv, and capcom next still exits with code 4.

Improved

• Output names the file it actually wrote — capcom agents (including the path field of its --json output), the refreshed: line from know add, know update, know mv and know rm, the hint from capcom init, and capcom's errors about the block now name the block file in use rather than always saying AGENTS.md.

Docs & install

• Documentation for agents.file — the agent setup, Managed block and quickstart guides, the file-format reference, the glossary and the help for capcom agents, capcom know and capcom know add now explain how to keep the capcom block outside AGENTS.md and what capcom check reports about it.

v0.13.0

capcom — v0.13.0 — 2026-11-01

This release adds capcom apply, which files and updates a linked set of issues in one step that either fully lands or changes nothing.

New

• capcom apply runs a batch of issue writes, all or none — List create, update, dep add, close and log steps in a YAML file and run capcom apply <file> (or capcom apply - to read it from stdin): every step lands, or none does, and the first step that fails is reported with its line in the file. --dry-run checks the whole batch without writing anything, and the output (also as --json or --kv) shows each step and the issues the batch made ready.

Improved

• The AGENTS.md block now tells agents about capcom apply — capcom agents adds a line for it right after capcom create, and the capcom plugin skill mentions it in its work loop too. An existing block shows as out of date in capcom check and capcom agents --check until you run capcom agents again.

Docs & install

• Apply file reference — The user manual has a new page on the apply file: each step and the keys it takes, the all-or-none rule, dry runs, the output and the errors, with a worked example. The JSON output reference now describes what capcom apply --json returns, including a failed batch.

v0.12.1

capcom — v0.12.1 — 2026-10-27

The terminal UI now lets you pick between the side-by-side and the stacked layout, and remembers your choice.

New

• Choose your layout in capcom ui — on a terminal big enough for both (at least 90 columns by 25 rows), press v to switch between the side-by-side split layout and the stacked one. Your choice is remembered as ui.layout and applied again each time both layouts fit, and the help screen now lists v.
• A layout button in the status bar — the right end of the status bar shows a small button (─── while split, │ while stacked) that you can click to switch layouts, even with the filter line or the status picker open, which both stay open; it is hidden while help or a prompt is showing.
• A layout-button colour — you can recolour the new status-bar button under ui.colors in your user config (by default a dark grey on the dark scheme and a light grey on the light one); with NO_COLOR set, the button is drawn in reverse video.

Improved

• The stacked sidebar height follows the layout you choose — the sidebar height you set for the stacked layout (ui.stacked_ratio) now applies whenever the panes are stacked, including when you pick the stacked layout on a wide terminal, not only on a narrow one.
• A clearer message when settings can't be saved — if capcom ui cannot save your layout or divider position, it now says cannot save the layout: followed by the error, instead of cannot save the divider position:; the new layout or position still takes effect.

Docs & install

• Terminal UI guide covers choosing a layout — the guide has a new section on switching layouts with v or the status-bar button and on what is remembered, and the file format reference documents the ui.layout setting and the layout-button colour.

v0.12.0

capcom — v0.12.0 — 2026-10-27

This release makes Tree locks safer to share between sessions and worktrees, lets the issue outline be filtered, and turns index and lock failures into messages that say what to do next.

Breaking changes

• Lock records no longer hold the token in the clear — a lock record now stores only a fingerprint of the Lock token, so reading the lock directory tells you who holds the lock but not how to act as them. An older capcom in the same clone cannot match the new record and treats it as held by another session. What to do: upgrade every capcom that works in the clone; if an older one is stuck, clear the lock with capcom lock break. Records written by older versions still work and are converted the next time the lock is touched or resumed.
• --plan takes a plan name, not a path — capcom create --plan and capcom update --plan now refuse (exit 1) a value that is absolute, contains / or \, or is . or .., and the message lists your plans directories. What to do: pass the plan's file name alone, with or without .md; --plan "" still clears it, and a name found in no plans directory is still saved, now with a warning.
• --json on a bare command group is a usage error — running capcom, capcom know, capcom dep, capcom lock or capcom related with --json and no subcommand now fails with <command> does not support --json and exit 2, instead of printing help and exiting 0. What to do: name a subcommand, or use --help to see the help.
• The AGENTS.md block needs a refresh — the Tree lock paragraph that capcom agents writes now explains that the lock is a signal, not a barrier: writes are never refused, but they warn and name the holder. Until you refresh it, capcom check and capcom agents --check report your existing block as out of date. What to do: run capcom agents once after upgrading.

New

• list --tree now filters — capcom list --tree combines with --status, --category, --label, --no-label, --type, --priority, --plan, --planned and --unplanned, keeping each matching issue together with its parents; a parent shown only for context ends with [context] (and "context": true in --json). Only --limit still cannot be combined with --tree.
• Writes tell you when another session holds the worktree — create, update, log, close, reopen, moves, removals, dependency and Note edits, and fmt or agents without --check still succeed, but now warn locked by <holder> (<purpose>) …; if it is yours, carry on when the Tree lock is held for something else. Writing the issue you started yourself, and start, finish and the lock commands, stay quiet.
• finish --keep-lock hands you the next command — it now prints the Lock token and its next: line spells out capcom start <next> --token <token>, so you can carry the lock straight on to the next issue (TOKEN= in --kv, lock.token in --json). A plain capcom start refused as locked now suggests the same --token form.
• prime --json reports whether this worktree is free — its data gains a worktree entry with the worktree's key, its lock state (free, held, stale, invalid or unreadable) and the same advice as the text's this worktree: line.

Improved

• Large stores list faster — list, ready, next, search and the other commands that read many issues now fetch them from the index in a fixed handful of reads instead of several per issue, so a store with thousands of issues answers noticeably sooner; output is unchanged.
• "Planned" means the plan file exists — capcom prime and ready/next --planned/--unplanned count an issue as planned only when its plan names a file in one of your plans directories. list --planned/--unplanned still go by whether the plan field is set, and their help now says so.
• Checking a lock no longer writes to disk — capcom lock check, capcom lock status, capcom prime and the terminal UI no longer create .git/capcom/locks/ or a guard file just to read the lock. On a read-only lock directory, lock check now answers 0 or 3 from the record instead of failing with exit 1.
• A busy index explains itself — when another command such as capcom reindex holds the index past the five-second wait, commands now fail with the index is busy: … retry when it finishes instead of a raw database is locked (SQLITE_BUSY) error, and capcom prime no longer advises a reindex for it.
• A damaged lock record points to the fix — lock check, lock acquire, lock touch, lock release and start meeting a lock record that cannot be read now fail with the lock record cannot be read and the hint capcom lock status, then capcom lock break, in text and --json.
• Warning when frontmatter comments are dropped — editing, moving or removing an issue or Note whose frontmatter contains a YAML comment now warns frontmatter comments are not kept; capcom writes frontmatter in canonical form, instead of losing the comment silently.
• Tree and dependency JSON match the text — list --tree --json now includes each parent's children progress (total, closed) and the more count of a --depth cut, and dep list --json marks an issue shown as (see above) with repeat: true and carries more.

Fixed

• Removed worktrees no longer leave their lock behind — a lock left by a linked worktree that was removed, or removed and re-created at the same path, now counts as free: capcom lock check exits 0 and lock acquire or start takes it over with a new token. lock status and prime show such a lock as free (orphaned record of a removed worktree), with "orphaned": true in --json.
• Moving an issue or Note keeps Note Refs valid — capcom mv and capcom know mv now rewrite every Note Ref that pointed at the moved file or anything under it, keeping any #symbol, so capcom check no longer fails on stale Refs afterwards. Both commands list the Notes they changed as refs_rewritten (REFS_REWRITTEN= in --kv).
• capcom reindex repairs a corrupt index — it now deletes a damaged index.db with its -wal and -shm files and builds a fresh one, where it used to fail on the bad file; other commands meeting a corrupt index fail with the hint capcom reindex.
• Edits that keep a file's size and timestamp are no longer missed — the index now also notices a change that leaves a file's size and modification time as they were, so list, show and search show the new content. The index rebuilds itself once on the first command after upgrading.
• A lock from a fast clock no longer sticks — a Tree lock whose heartbeat is dated more than one TTL in the future now counts as stale, so capcom lock acquire --take-stale can take it over, and the locked error no longer shows negative ages.
• Resuming a lock under a new purpose retires the old one — capcom lock acquire --purpose <new> --token <token> or capcom start <id> --token <token> now moves the lock to the new purpose, so a session still using the old purpose is refused as locked (exit 3) instead of taking the lock back.

Docs & install

• Search help covers Chinese, Japanese and Korean text — capcom search --help and capcom know search --help now explain that a run of CJK characters without spaces counts as one word, so 登录超时问题 is found by the whole run and not by 登录.
• Corrected examples — the --ref example in the README and in capcom know add --help now points at a file that exists, and the terminal UI guide no longer shows a fixed capcom version in its sample screen.

v0.11.0

capcom — v0.11.0 — 2026-10-26

This release makes capcom quicker to recover from a mistake and quicker to get started on an issue: every error now names the command to run next, mistyped ids and values come with suggestions, and a new capcom context gathers what you need before you begin. The terminal UI gains a Closed tab.

Breaking changes

• capcom check now flags Note Refs a fresh clone would not have — a Ref into the .git/ folder or to a file git ignores is reported as unshared-ref even though it opens fine in your own checkout, so a capcom check (or capcom know verify) that passed before can now fail. What to do: point the Ref at a committed file, or drop it with capcom know update <id> --remove-ref <path>.
• capcom agents --check reports AGENTS.md blocks written by earlier versions as out of date — the block's work loop now tells agents to run capcom context <id> before starting an issue, so an older block fails the check. What to do: run capcom agents once to refresh the block, and commit the result.

New

• capcom context <id> — one call prints the issue, the issues it waits on and the ones waiting on it, its plan, and up to eight Knowledge Notes that apply to it, with the first few Notes in full; --brief keeps it to a short summary and --json gives everything uncut.
• capcom recap — lists what changed in your issues and Notes since a date, a number of days (--since 3d; a week by default) or a git commit: issues closed, filed, moved to a new status or given a log entry, and Notes added, changed or retired.
• Closed tab in capcom ui — a fourth tab, on key 4, lists your closed issues newest first with each one's full details beside the list; press R to reopen the selected issue after giving a reason, or / to filter the list.
• capcom ui closed [id] — opens the terminal UI straight on the Closed tab, with that issue selected when you name one.
• "Did you mean" for mistyped ids — an issue or Note id that matches nothing now suggests up to three close ones, so capcom show retry-bakoff answers "did you mean retry-backoff?"; --json carries them as suggestions and --kv as SUGGESTIONS=.
• Write an issue's body as you create it — capcom create takes --body <text>, --why <text> for a ## Why section and --acceptance <text> (repeatable) for the bullets of an ## Acceptance section, so no body file is needed.
• Search excerpts — capcom search --excerpt and capcom know search --excerpt show the lines of each hit that hold your words, and ignore accents just as the search does, so cafe finds a line reading café.
• Shell completion for ids and values — pressing Tab now offers issue and Note ids, each with its title and open issues first, the capcom ui tab names, and the statuses, categories and types each flag accepts.

Improved

• Every error tells you what to run next — errors end with a hint: line naming the command that fixes them (hint in --json, HINT= in --kv); that command no longer sits inside the message, so message wording has changed, while error codes and exit codes have not.
• Bad flag values are refused with the list of good ones — an unknown --status, --type or --category, or a --priority outside 0 to 4, is refused before anything is written, and the error names the flag and lists what it accepts (valid in --json, VALID= in --kv).
• Search no longer comes back empty on a partial match — when no issue or Note holds every word, capcom search and capcom know search list the ones holding some of them under a line saying so; --json reports which kind of match it was as match.
• --kv output carries the whole issue — capcom show, capcom next and capcom start with --kv now also print TYPE=, PRIORITY=, LABELS=, PARENT=, DEPS= and PLAN=, so a script can read an issue back without a second call.
• Tab counts in capcom ui — tab labels show how many items each holds, as in Issues [12], and [matched/total] while a filter is on; the counts on tabs you are not looking at are drawn in dim grey.
• capcom prime points out Note Refs a clone would lack — the briefing adds an unshared Note refs: N line when there are any (unshared_refs in --json).
• capcom know add refuses Refs inside .git/ — --ref, and --add-ref on capcom know update, refuse a path in the git folder before writing anything; a Ref that does not open here, or that git ignores, is still written, with a warning.
• Easier-to-read --help — every command's help now prints the summary, usage, subcommands, examples and flags first and the longer rules last, split into short paragraphs.

v0.10.0

capcom — v0.10.0 — 2026-10-23

Two commands now handle what agents do most: capcom start claims an Issue together with the Tree lock, and capcom finish closes it and frees the lock. capcom also keeps the Lock token for the session, so a lock survives a restart or compaction without anyone saving the token.

Breaking changes

• The AGENTS.md Managed block has new instructions — after upgrading, capcom check and capcom agents --check report an existing Managed block as out of date, because the block now tells agents to claim work with capcom start <id> and close it with capcom finish <id> --reason <text>, and no longer asks them to keep the Lock token. What to do: run capcom agents once to rewrite the block.

New

• capcom start <id> — claims a Ready Issue and this worktree's Tree lock in one step, printing the Issue in full and the Lock token; running it again on the same Issue resumes your lock without changing anything. It refuses an Issue that is Closed, standing, not Ready or already in doing without your lock, and a lock another session holds (exit code 3), writing nothing and naming the command that fixes each case.
• capcom finish <id> --reason <text> — closes an Issue, frees the Tree lock using the token capcom start kept (or a --token you give), and ends with the next Ready Issue to pick up (or "nothing is ready to work on"). Add --keep-lock to hold on to the lock; if no token holds the lock, the Issue is still closed and the output says why the lock was left alone and points to capcom lock status.
• Lock tokens are no longer lost — capcom lock acquire --purpose <text> keeps the Lock token for the session, so running the same command again, even after a restart, compaction or a stale lock, resumes your lock and prints the token again. A --token you pass is used instead, capcom lock release and capcom lock break clean up the kept tokens, and a lock held by another session still fails with exit code 3.

Improved

• capcom prime gives simpler lock advice — the this worktree: lines now suggest capcom start <id> for issue work and, for a held or stale lock, tell you to run the same acquire or start again to resume it, instead of asking you to keep a token.
• Renaming the doing status keeps the Managed block current — changing the name of your doing status in config.yaml no longer makes capcom check report the Managed block as out of date.

Fixed

• The Claude Code plugin's Briefing no longer goes silent by mistake — a settings file that only mentions capcom prime, for example in a permission rule, used to stop the plugin from printing the Briefing at session start. Now the plugin steps aside only when a hook runs exactly capcom prime, as capcom init --claude-hooks sets up.

Docs & install

• Guides teach the start-and-finish workflow — the README, the manual, llms.txt and the plugin's capcom skill now claim work with capcom start and close it with capcom finish, explain that running start or acquire again resumes the lock, and describe the Lock token as a shared signal between agents rather than a secret. The skill falls back to the older commands when the installed capcom has no start, and the tree-locks guide has a new section on the kept token.
• Output and plugin docs corrected — the README and capcom --help now say that every command except capcom ui takes --json, and that capcom help and capcom completion ignore it. The --kv reference points to each command's own page and notes that warnings come before every record, and the README and plugin skill now say the plugin also runs capcom prime before compaction.

v0.9.2

capcom — v0.9.2 — 2026-10-21

This release makes capcom quicker to drive: one command picks the next issue, mistakes at the prompt now point to what you meant, and capcom hooks into more agent tools.

New

• capcom next — prints the most urgent ready issue in full, the same view capcom show gives, so finding what to work on is one step. It accepts the filters capcom ready has (--label, --no-label, --planned, --unplanned, --show-hidden) plus --no-elsewhere, and when nothing is ready it says nothing is ready to work on and exits with the new code 4, so a script can tell "nothing to do" apart from a failure.
• apogee hooks — capcom init --apogee-hooks adds an entry to .apogee/config.yaml that runs capcom prime when an apogee session starts and after compaction, creating the file if needed and leaving the rest of it alone. It needs apogee v0.28.0 or later, apogee asks you once to adopt the entry, it works alongside --claude-hooks, --codex-hooks and --merge-driver, and if the file cannot be edited capcom stops with an error that names it and leaves it unchanged.
• Claude Code plugin — /plugin install capcom --marketplace airiclenz/capcom adds a capcom skill to Claude Code and runs capcom prime at session start and before compaction in repositories that use capcom. The hook stays quiet when capcom is not installed, the repository has no capcom store, or your settings already run capcom prime.

Improved

• "Did you mean" for mistyped commands — a misspelled command or subcommand, such as capcom know shwo, now fails and names the closest real one (did you mean know show?). A mistyped subcommand of know, dep, lock or related now exits with code 2 instead of printing that group's help and exiting 0; running the group on its own still shows its help.
• "Did you mean" for mistyped flags — an unknown flag such as --statsu now suggests the nearest flag that command accepts (did you mean --status?). With --json the hint appears as error.suggestion, and with --kv as a SUGGESTION= line; nothing is suggested when no flag is close.
• capcom ui shows which worktree you are in — the tab bar now reads like ~/repos/capcom · v<version> · capcom, with your home folder shortened to ~. On a narrow terminal the folder is dropped first and then the whole label, so the tabs are never cut off.
• Agent instructions point to capcom next first — the capcom section that capcom agents writes into AGENTS.md now opens with capcom next, ahead of capcom ready. After upgrading, an existing section counts as out of date: run capcom agents once to refresh it.

Docs & install

• FAQ and comparison pages — the manual gains a FAQ and a page comparing capcom with beads, GitHub Issues, Task Master and a plain TODO.md, and the README FAQ now covers which coding agents capcom works with, how to keep project knowledge across sessions, and that capcom makes no network calls. The README and manual also state that capcom is not affiliated with Capcom Co., Ltd., and a new llms.txt at the top of the repository indexes the docs for AI tools.
• Demo on the manual's start page — the manual's front page now opens with the same animated capcom ui demo as the README.

v0.9.1

capcom — v0.9.1 — 2026-10-19

This release makes capcom stricter and more predictable when a flag is given more than once: flags that take one value refuse a repeat, and body edits on updates now apply every repeat.

Breaking changes

• A flag that takes one value can no longer be repeated — giving --title, --status, --priority, --plan, --json, --standing or any other single-value flag twice to a capcom command now stops with a usage error (exit 2), --<name> given <n> times; give it once, before anything is read or written; before, the last value quietly won. What to do: give each such flag once in your scripts and agent prompts; flags that collect a list, such as --label and --dep, still take every repeat.

Fixed

• Repeated body edits in capcom update and capcom know update all apply — --body-append and the --body-replace-old/--body-replace-new pair can be given several times, and every replacement now runs in the order given, followed by every append, instead of only the last of each being used. If any replacement's old text does not appear exactly once, the whole update is refused with a message naming that pair (for example --body-replace-old #2 "<old>": …) and nothing is written; an unequal number of old and new texts is a usage error naming both counts.

v0.9.0

capcom — v0.9.0 — 2026-10-18

This release adds standing Parents, issues that exist only to group their children and never show up as work to pick up, and lets capcom ui show both panes at once on a narrow, tall terminal.

Breaking changes

• Marking an issue standing moves the store to format 5 — the first time any command leaves an issue marked standing, .capcom/config.yaml is raised to format: 5 with a warning, and older capcom releases can no longer read that repository; new repositories from capcom init start at format 5. What to do: upgrade capcom everywhere the repository is used, including teammates' machines and CI, before anyone marks an issue standing.
• The agent instructions in AGENTS.md read as out of date after upgrading — the capcom block now tells agents never to claim or close a standing issue, so capcom check and capcom agents --check report an existing block as stale. What to do: run capcom agents once to refresh the block.

New

• Standing issues — capcom create --standing or capcom update <id> --standing marks an issue as a parent that only groups its children, and capcom update <id> --no-standing removes the mark, even in the same call that claims the issue with --status. capcom show prints standing: true, --json output carries "standing": true, and a closed or in-progress issue cannot be marked.
• Standing issues never come up as ready work — capcom ready, capcom prime, the ready list in capcom ui and the now ready: line after capcom close all leave them out, while their open children stay ready as usual. capcom ready --all lists one with the reason standing: holds children, and capcom show prints ready: no (standing: holds children).
• Claiming or closing a standing issue is refused — capcom close <id> and capcom update <id> --status with an in-progress status fail with a message telling you to run capcom update <id> --no-standing first; closing several ids at once still closes the others.
• capcom check catches a standing issue that is closed or in progress — it reports it under the code standing, at the line holding the mark, and says how to fix it.
• capcom ui knows about standing issues — the detail pane shows standing: yes, and trying to claim, close or move one into an in-progress status shows a notice pointing to capcom update <id> --no-standing instead of changing anything.
• capcom ui shows both panes on a narrow, tall terminal — below 90 columns and at least 25 rows, the list sits on top and the details below, split by a rule you can drag or move with < and >; a double-click resets it to a third of the screen. The position is remembered between sessions as ui.stacked_ratio in state.yaml, and shorter terminals keep the one-pane view.

Docs & install

• Manual covers standing issues — the file format reference documents the standing key and store format 5, and the pages on issues, JSON output, the session briefing and the agent instructions explain how standing issues behave.
• Glossary defines Standing Parent — a new entry explains the term, and the entries for Ready, Parent and format version now account for it.
• Smoother demo in the README — the demo animation now zooms back out more slowly after the agent closes an issue.

v0.8.1

capcom — v0.8.1 — 2026-10-17

New

• capcom ui picks up where you left off — Run with no argument, capcom ui now reopens on the tab you last had open in this worktree, with the same Issue or Note selected on each tab, instead of always starting on Ready (the very first run still opens Ready). Naming a tab or an id on the command line, as in capcom ui <tab> <id>, still takes you straight there; the remembered place lives in <git-dir>/capcom/ui-state.yaml, which is never committed, while the sidebar width you set stays remembered across all your projects as before.

Docs & install

• An animated tour at the top of the README — The README now opens with a short recording of capcom ui: the Ready queue, claiming an issue, an agent closing another one live, the Issue tree, the Knowledge, and resizing the sidebar.
• apogee listed among supported agents — The README now names apogee alongside Claude Code, OpenAI Codex, Cursor and the other coding agents capcom works with.