brainfile

$ npx brainfile init
$ npx brainfile list

Every command works through npx. The MCP configuration above uses it so the server tracks whatever version npm resolves, and nothing has to be on the PATH.

$ brainfile migrate
$ brainfile migrate --logs-to-ledger   # also backfill logs/*.md into ledger.jsonl

Older boards kept every task inside one brainfile.md. migrate splits that into .brainfile/brainfile.md plus one file per task, keeps backups, and refuses to overwrite its own outputs unless you pass --force.

brainfile is one of the chain.sh tools. One command installs the set:

$ curl -fsSL https://chain.sh/bootstrap.sh | sh

A decision belongs to a claim family through its dotted claimKey (dependency.http-client). A family has one current decision: decide records a new one and supersedes the old, which gets status: superseded and supersededBy, moves to logs/, and is pointed at by the new one's supersedes. A current decision lives in board/; a superseded, rejected or stale one in logs/. The body is the decision and why.

---
id: decision-3
title: Use undici for HTTP, never axios
type: decision
status: current
claimKey: dependency.http-client
kind: constraint
stance: forbids
subject: axios
holdsWhile: we target Node 20 and later
recheck: when fetch gains retries
validUntil: 2027-06-30
packageVersion: undici>=6
supersedes: decision-1
---

Name your own under types: in the config, or with brainfile types add. A type can take a built-in's place with like:: it gets that type's parents, children, completion rule and glyph. One with no like behaves as a task.

types:
  bug: { like: task }
  rfc: { like: spec, idPrefix: rfc }

An entry under a built-in's own name overrides it (plan: { completable: false } stops a plan completing when it reaches a completion column). With strict: true, a document's type must be built in or listed. brainfile types prints every type with its place in the graph.

$ brainfile init
$ brainfile init --force    # overwrite an existing config
$ brainfile init --plain    # a plain directory, even inside a git repository
$ brainfile init --here     # inside a repository: this directory, not its root
$ brainfile init -g         # the home board at ~/.brainfile

Writes a short brainfile.md with two columns and the default agent instructions (no types:: the five built-in types need none), creates board/ and logs/, and adds a .gitignore that excludes state/, where per-agent brief state lives.

Inside a git repository the board is created at the repository root as a worktree on its own brainfile branch, hidden from the code branch through .git/info/exclude; outside one, --tracked makes it its own repository. Either way every change becomes a commit. --plain opts out. See Sharing a board.

$ brainfile list
$ brainfile list -c todo
$ brainfile list -t urgent             # by tag
$ brainfile list --parent epic-1
$ brainfile list --type spec           # aliases work: issue is task, adr is decision
$ brainfile list --tree                # the outline: epics, specs, plans, tasks
$ brainfile list --tree --parent epic-1
$ brainfile list --type decision       # decisions, current first
$ brainfile list --contract ready      # ready | in_progress | delivered | done | failed
$ brainfile list --related             # open tasks on related boards this board waits on
$ brainfile list --related all         # every open task on every related board

Prints every column with its tasks, priorities and tags. A task waiting on a related board says so on a Blocked by: line, and one resting on a superseded decision says that too. Decisions have no column, so list leaves them out and says how many; --type decision lists them with where each stands.

--tree prints open work as an outline, nested by parentId in column order:

$ brainfile list --tree

My Project — outline

▸ epic-1  Memory and the graph  · In Progress
  ◆ spec-1  Default types  · To Do
    ⎘ plan-1  Build order  · To Do
      · task-1  Registry  · To Do
  · task-3  Index work  · To Do  ⚠ rests on superseded decision-2

With a filter it shows the matches and keeps their ancestors, dimmed, for context; --parent shows one document and everything under it.

$ brainfile show -t task-2
$ brainfile show -t task-2 --json
$ brainfile show -t mobile:task-12     # a task on a related board

--json prints the document's frontmatter as one object, timestamps included. show names the document's type, its parent, its children (open or done), each dependency and whether it is done, and the decisions it rests on with where each stands; if one is superseded it says "Rests on a superseded decision". A decision shows its status and the work resting on it. --json adds the same as graph.

$ brainfile add -t "Fix login bug" -p high --tags bug,auth --files src/auth.ts
$ brainfile add -t "Auth epic" --type epic --child "OAuth flow" --child "Session hardening"
$ brainfile add -t "Token refresh" --type spec --parent epic-1
$ brainfile add -t "Use SQLite for the index" --type decision
$ brainfile add -t "Build the index" --parent spec-1 --decisions decision-1

$ brainfile move -t task-1 -c in-progress

Column names and ids both work.

$ brainfile patch -t task-1 -p critical --assignee codex
$ brainfile patch -t task-1 --tags perf,cache        # replaces the tag list
$ brainfile patch -t task-1 --clear-due-date
$ brainfile patch -t spec-3 --parent epic-2
$ brainfile patch -t task-7 --depends-on task-5,task-6 --decisions decision-2

Takes --title, -d, -p, --tags, --assignee, --due-date, --parent, --depends-on and --decisions, plus --clear-tags, --clear-assignee, --clear-due-date, --clear-priority, --clear-parent, --clear-depends-on and --clear-decisions. -p none also removes the priority. A new parent must fit the type, as for add, and neither link may loop.

$ brainfile complete -t task-1
$ brainfile complete -t epic-1 --force   # even if children are still active

Appends to logs/ledger.jsonl, moves the file to logs/, and records cycle time from createdAt. A parent with open children refuses, whatever its type, until they are done or you pass --force; a decision is never completed.

$ brainfile delete -t task-3 --force

--force is required; there is no prompt and no undo. Prefer complete.

$ brainfile subtask -t task-1 --add "Write tests"
$ brainfile subtask -t task-1 --toggle sub-1
$ brainfile subtask -t task-1 --update sub-1 --title "Write unit tests"
$ brainfile subtask -t task-1 --delete sub-1

$ brainfile search parser
$ brainfile search parser -c in-progress
$ brainfile search cache --type adr      # decisions, under either name
$ brainfile search "p:high #auth token"  # filter tokens: p: #tag @user type: due: contract:
$ brainfile search parser --no-history --json

Current results come first: open work, current decisions, plans/ and the project's own Markdown (README, AGENTS.md, docs/…). History comes after, in its own lane: completed work, the ledger, and decisions that were superseded, rejected or let go stale. Every hit has its path and line range; a board document also has its ID, a file hit's ID is path:start-end.

On Node 22.13 and later the local index answers (.brainfile/state/index.db, brought up to date before every search): words are matched all together first and any of them second, ranked with titles over bodies. On older Node, or with BRAINFILE_INDEX=off, the scan over board/ and logs/ answers in the same shape; nothing else changes. A query that is only filter tokens (p:high) always scans. --limit caps each lane (default 20), --json prints { mode, query, results, count } with each hit's lane, source, path, startLine and endLine.

$ brainfile note -t task-1 "Bounded by bytes, not entries"
$ brainfile note -t task-1 --agent codex "Tests pass on the new cache"

Each note is tagged with who wrote it: --agent when given, otherwise the agent running the command if brainfile can tell (see Who did what), otherwise your git user.name. Notes stay with the task and become the ledger summary when it completes.

$ brainfile log --recent
$ brainfile log -t task-1
$ brainfile log -s "cache"

$ brainfile tui

Columns, decisions, detail view, filters and every write operation from the keyboard. See The TUI.

$ brainfile brief --agent claude
$ brainfile brief --agent claude --max-chars 0  # no budget
$ brainfile brief --agent claude --peek         # read without marking seen
$ brainfile brief --agent claude --json
$ brainfile brief --agent claude --offline      # skip the sync a shared board does first

One block, about 1,600 characters (--max-chars), in lanes:

Brainfile brief for claude · My Project (since 3h ago)
! task-12 Build the index: rests on superseded decision-1 (now decision-3)
## Current decisions
- decision-3 dependency.http-client: Use undici for HTTP, never axios (constraint · forbids axios)
## Your tasks
- task-12 Build the index · In Progress · high
## Since your last brief
- task-12 note: [codex] wired the FTS table (2h ago)
- decision-3 decided: Use undici for HTTP, never axios (supersedes decision-1) (3h ago)
## Docs that bear on them
- docs/index.md:12-40 Search index › Design

Lines starting with ! come first: open work resting on a superseded decision, and current decisions whose validUntil, source file or package version no longer holds. Then the current decisions; the agent's tasks (or, when nothing is assigned to it, the work in flight); what changed since its last brief (notes, task changes, completions, decisions made or retired, config), or on a first brief the latest notes and completions; and, from the local index, the docs that share the tasks' most distinctive words. When the budget is tight every lane still gets its first line, shortened if need be, before any lane gets a second, and a last line says how many more there are.

The checkpoint is per agent, kept in .brainfile/state/ and ignored by git; --peek reads without moving it. --json carries the block as text, its lanes as sections, and the checkpoint's own lanes as before. A shared board syncs before the brief so it reflects other machines; a sync failure is one warning line, never an error. The SessionStart hook prints this block.

$ brainfile contract pickup -t task-2
$ brainfile contract deliver -t task-2
$ brainfile contract validate -t task-2
$ brainfile contract attach -t task-5 --ready --deliverable "file:src/x.ts" --validation "npm test"
$ brainfile contract activate --parent epic-1     # every draft under the epic → ready
$ brainfile contract graph --show

The whole lifecycle is in Contracts.

$ brainfile mcp

Speaks MCP over stdio; your agent launches it, you never run it by hand. It tells the agent to use its tools for every board change and never to edit .brainfile/ by hand. Tools and setup are in For agents.

$ brainfile hooks install claude-code
$ brainfile hooks install cursor --scope project
$ brainfile hooks list
$ brainfile hooks uninstall cline --scope all

Supports claude-code, cursor and cline, at user (default) or project scope. The hooks nudge the agent to update the board after it edits files, and when a session starts they hand it its brief: for Claude Code as hookSpecificOutput.additionalContext, for Cline as text. The session-start hook runs from a lean entry that loads the brief and nothing else, about 150ms warm; it names the agent from BRAINFILE_AGENT, else the tool (claude, cline), and moves that agent's brief checkpoint. BRAINFILE_BRIEF_MAX_CHARS changes its budget.

$ brainfile plan add -t "Thin-frontend refactor" --status draft
$ brainfile plan list --status active
$ brainfile plan show plan-1 --json
$ brainfile plan link plan-1 -t task-42

add takes -c, --description, --tags, --parent (an epic or a spec) and a free-form --status. link sets the task's parentId to the plan, so list --parent plan-1 finds a plan's tasks. plan is a built-in type, so a strict board needs no types: entry for it.

$ brainfile decide -k dependency.http-client "Use undici for HTTP. It ships with Node."
$ brainfile decide -k dependency.http-client --kind constraint \
    --stance forbids --subject axios "Never axios: one HTTP client"
$ brainfile decide -k release.window --valid-until 2026-12-31 \
    --recheck "Ask the release manager" "Release on Tuesdays"
$ brainfile decide -k storage.index --source docs/index.md "Index with SQLite FTS5"
$ brainfile decide -k runtime.node --package "engines.node>=20" --for task-12 "Support Node 20+"
$ brainfile supersede decision-3 "Use fetch: it retries now"
$ brainfile retire decision-4 --as rejected --note "Too costly to run"

decide needs -k/--claim-key and the text (- reads stdin; the first line is the title unless --title). When the family already has a current decision, that one is superseded and moved to logs/; when the family was empty, it lists related families (the same parent key, or the same words) in case the call already exists under another key. Saying again exactly what the family's current decision says changes nothing. --no-supersede leaves both current, and check will say review. --source records the file's sha256 relative to the project root; --package a version predicate; --for adds the decision to the listed work's decisions:.

supersede <id> replaces one decision by hand, keeping its claim key and kind unless you give others. retire <id> --as rejected|stale moves a decision to logs/ with that status and an optional --note. Each command is one board commit on a tracked board. list --type decision lists them all, current first; show prints one with its chain.

$ brainfile add -t "Use SQLite for the index" --type decision
$ brainfile adr promote -t adr-1

ADRs are decisions: --type adr writes a decision, and an existing type: adr file reads as one and keeps its ID. promote marks a legacy ADR accepted and moves it to logs/. Current decisions and accepted ADRs appear in every brief.

$ brainfile check "use axios for the retry client"
$ brainfile check decision-3
$ brainfile check --claim-key dependency.http-client
$ brainfile check --claim-key-prefix dependency "add axios"
$ brainfile check "add axios" --json

check finds the claim family an action touches (a decision ID, a claim key, or its words: the local index when there is one, a scan of the decisions when there is not) and answers in this order:

--claim-key-prefix checks every family under a prefix and gives the worst verdict. Errors (no board, bad arguments) exit 1. --json prints the verdict, recommendation, reason, the predicates as evaluated and the family.

$ brainfile columns                                   # list, with task counts
$ brainfile columns add "In Review" --after in-progress
$ brainfile columns add Shipped --completion
$ brainfile columns rename in-review Review
$ brainfile columns reorder backlog todo in-progress
$ brainfile columns remove review --move-to in-progress

Columns are named by ID or title. add makes the ID from the title (In Review is in-review) unless --id gives one, and puts the column last unless --after or --before says where; --completion marks a column whose tasks count as done. rename changes the title only: the ID stays, so the tasks in it stay. reorder puts the columns you name first, in that order, and the rest after them. remove refuses a column that still holds tasks unless --move-to names where they go; they move there first, without being completed. The last column is never removed. Every command takes --json, and each change is one board commit on a tracked board.

$ brainfile types
$ brainfile types list --json
$ brainfile types add bug --like task
$ brainfile types add rfc --like spec --id-prefix rfc --schema ./rfc.json

$ brainfile types
Strict mode: off

  TYPE      ID          GOES UNDER                 HOLDS
▸ epic      epic-N      top level                  spec · plan · task
◆ spec      spec-N      epic                       plan · task
⎘ plan      plan-N      epic · spec                task
  task      task-N      epic · spec · plan · task  task                alias issue
● decision  decision-N  never in the tree          —                   alias adr · no column, never completed

  bug       bug-N       epic · spec · plan · task  task                like task

--like takes a built-in's place; without it a type behaves as a task. An alias name (adr, issue) cannot be added as a type of its own.

$ brainfile template --list
$ brainfile template --use bug-report --title "Login times out" -c todo

Three templates ship: bug-report, feature-request and refactor, each with a default priority, tags and a subtask checklist.

$ brainfile lint
$ brainfile lint --fix
$ brainfile lint --check   # non-zero exit for CI

--fix also folds a legacy rules: block into agent.instructions. lint also checks the graph: a parent that is missing, loops or does not fit the type, decisions: that name nothing or something other than a decision, and a like: that names no type. Off-pattern links are warnings, and errors on a strict board. It also checks where the board lives: two boards that disagree are an error; the board branch checked out away from .brainfile/, a checkout whose folder is gone (--fix forgets it), and a code branch still tracking an old copy are warnings.

$ brainfile index            # bring it up to date and say what changed
$ brainfile index --rebuild  # drop it and index from scratch
$ brainfile index --status   # what is in it

Never required: every search, brief and check brings the index up to date first. Unchanged files (same size and modification time) are not read; a changed file replaces its chunks; a deleted one drops out. Inside git the project's files come from git ls-files, so .gitignore is honoured; root AGENTS.md and CLAUDE.md are read even when ignored. Markdown and text only, 256 KiB a file at most, never node_modules, dist and the like, never .brainfile/ (the board is indexed on its own terms), never your home folder. Where Node has no node:sqlite (below 22.13) it says so; search, brief and check scan instead.

$ brainfile schema               # list
$ brainfile schema board --json
$ brainfile schema update        # check brainfile.md for a newer version

Bundled with the CLI, so validation works offline. Update checks run at most once a day and never block.

$ brainfile migrate --dir ./old-project
$ brainfile migrate --to-branch            # move the board onto its own branch
$ brainfile migrate --to-plain             # back to a plain directory

Flags: --dir, --force, --logs-to-ledger, --to-branch, --to-plain. --to-branch keeps the board's history when it was committed on the code branch (git subtree split), imports a gitignored one as a fresh branch, and folds a standalone board repository into the surrounding repository. Board changes not yet committed come along as one more commit on the branch. If any step fails, the migration undoes itself and the repository is left as it was. When the code branch tracked the board, one commit on it drops .brainfile/ and adds it to .gitignore (anything else you had staged stays staged); push it like any commit. Run on a board already on its branch, it makes that commit if the code branch still tracks an old copy. If a board already lives on the brainfile branch, this folder and it are two boards, and --to-branch says so and points to merge-boards. --to-plain leaves the branch intact.

$ brainfile where
$ brainfile where --fetch          # ask the remote for its copy first
$ brainfile where --json

Prints the board's location, how it is stored (plain files, a branch of this repository, or its own repository), the remote it is shared through, when it last synced, how many changes are waiting to be sent and how many on the remote are not here yet. It also looks for every other copy of the board in the repository (see One board per repository) and says when one disagrees with this one. It touches the network only with --fetch, so it is always safe to run.

$ brainfile adopt refs/brainfile/remotes/origin/board   # take that board as it is
$ brainfile adopt .brainfile                            # keep this folder
$ brainfile merge-boards refs/heads/brainfile           # combine them by document ID
$ brainfile backups                                     # what was saved
$ brainfile backups restore 20261012T205217Z-folder     # put one back

When a repository has two boards (see One board per repository), these make it one. adopt <ref|path> takes the named board as it is. merge-boards <ref|path> combines this board with the named one by document ID, with the same rules sync uses: frontmatter fields by updatedAt, logs unioned in time order, completion over an edit. One ID on two different documents (created apart, with unrelated titles) keeps the older; the newer gets the next free ID, a log line saying so, and every reference to it on its board rewritten. When one board already has everything the other has, merge-boards says so and adopts it without asking.

Both end the same way: the board on the brainfile branch, checked out at .brainfile/, descending from what the branch and the remote's copy had (so the next sync is a plain push), with any other checkout of the branch removed once its changes are committed. If the code branch still tracked .brainfile/, one commit on it stops tracking the folder and adds it to .gitignore; push that like any commit. Every board that is replaced is saved first as refs/brainfile/backups/<UTC time>-folder or -branch; backups lists them and backups restore <name> puts one back, backing up what it replaces. Backups stay on this machine unless you push one by name.

$ brainfile sync                                  # fetch, merge, push
$ brainfile sync --pull                           # one direction
$ brainfile sync --set-remote origin              # the code remote
$ brainfile sync --set-remote git@host:me/boards.git --board-name myproject
$ brainfile sync --autosync full                  # off | push | full

Fetches the board, fast-forwards or merges with the board-aware merge driver, and pushes it to refs/brainfile/<name> on the remote. Runs entirely inside the board directory; the code tree is never touched. --set-remote in a repository that has no board yet checks the board out from that remote. Details in Sharing a board.

$ brainfile archive -t task-1                    # same as complete
$ brainfile archive -t task-1 --to github
$ brainfile archive --all --to linear --dry-run
$ brainfile restore -t task-1 -c todo

Exports create an issue in the configured GitHub repo or Linear team; set the destination with config set archive.github.owner, archive.github.repo or archive.linear.teamId, and archive.default for the default target.

$ brainfile auth github            # OAuth device flow
$ brainfile auth github --token ghp_…
$ brainfile auth linear --token lin_api_…
$ brainfile auth status
$ brainfile auth logout --all

$ brainfile config path            # ~/.config/brainfile/config.json
$ brainfile config list
$ brainfile config set archive.default github

Holds archive destinations, auth and the schema update timestamp. Nothing about a specific board lives here.

When an agent makes the change, the commit message ends with its name in brackets, and notes carry the same name. brainfile works out the agent in this order:

• --agent <name> or BRAINFILE_AGENT, when the agent says who it is.
• The nearest agent CLI above the command: claude, codex, cursor-agent, gemini, opencode, goose, droid, crush, aider, cline, amp, qwen or copilot.
• Variables agents set for the commands they run, for sandboxes that hide the process tree (Codex's CODEX_THREAD_ID, Claude Code's CLAUDECODE).

Commands you type yourself get no tag, and your notes carry your git user.name. Desktop apps and editors don't count as agents, because their built-in terminals are yours. BRAINFILE_DETECT_AGENT=off keeps only names given explicitly.

The branch is hidden, not secret. A plain git push sends only your code branch, but git push --all, --mirror and mirroring tools push every local branch, the board included. Once the board is on a remote, anyone who can read that remote can read it. The point is a clean main, not privacy; for private notes next to public code use a separate remote (below).

Two worktrees of the repository share the board directly. A clone gets it the first time you run brainfile there: brainfile asks the remote once for a shared board, checks it out into .brainfile/, says so (Checked out the shared board from origin into .brainfile/), and sends changes back to the remote it came from. If the remote has no board, brainfile does not ask again for ten minutes; sync --set-remote always asks. Someone who never runs brainfile never sees the folder.

Outside a repository, init --tracked makes the board its own small repository; the home board brainfile init -g is always one. Both take the same sync commands.