Brainfile

Markdown task boards for you and your AI agents. Tasks, epics, and decisions live as plain Markdown files in your repo — you manage them from a CLI or TUI, your agents manage them through an MCP server, and git is the audit trail. No database, no SaaS, no lock-in.

npm i -g brainfile
brainfile init          # scaffold a .brainfile/ board
brainfile tui           # interactive terminal UI
brainfile mcp           # MCP server for your coding agents
brainfile --help        # add, list, move, contract, search, …

How it works

A board is a .brainfile/ directory:

.brainfile/
├── brainfile.md        # board config: columns, agent instructions, your own types
├── board/              # active documents, one file each
│   ├── epic-1.md
│   ├── spec-1.md
│   ├── task-1.md
│   └── decision-1.md
└── logs/               # completion history
    ├── ledger.jsonl    # append-only completion log
    └── task-2.md       # archived documents

brainfile.md holds configuration only — columns, agent instructions, and any document types of your own. Five types are built in and form a graph: an epic holds specs, plans and tasks; a spec (what and why) holds plans and tasks; a plan (how) holds tasks; a task is the work; a decision is a standing choice that work names in decisions:. brainfile list --tree prints the outline. Every document is its own Markdown file with YAML frontmatter:

---
id: task-1
title: Implement feature X
column: in-progress
parentId: epic-1
assignee: codex
contract:
  status: ready
  deliverables:
    - path: src/main.ts
      description: Core implementation
  validation:
    commands: ["npm test"]
---

## Description
Detailed requirements...

One file per document means clean diffs, painless merges, and history for free. Completing a task appends a record to logs/ledger.jsonl and archives the file to logs/.

Where your board lives

Always in .brainfile/, as ordinary files you and your agents read directly. What changes is how it is kept:

Where you run brainfile init	How the board is kept	Who has it
A folder without git	Plain files	This machine
Inside a git repository	Every change is a commit on a separate brainfile branch, kept out of your code and pull requests	This machine, until you share it

Nothing leaves your machine until you choose a remote:

brainfile sync --set-remote origin    # or a private repo URL
brainfile where                       # where the board is, who has it, what is waiting to be sent

After that, changes are sent in the background and teammates who clone the repo get the board the first time they run brainfile. On the remote the board is stored as refs/brainfile/board, not a branch, so it never clutters the branch list or shows up as a pull request. Already have a board committed with your code? brainfile migrate --to-branch moves it, history included.

Working with agents

• MCP server — brainfile mcp exposes everything the CLI does to a board (list_tasks, task_add, task_move, note, columns, contract, search, …) to Claude, Cursor, or any MCP client, so agents read and update the same board you see in the TUI and never edit its files by hand.
• Contracts — a task can carry a contract: deliverables, validation commands, and constraints. Agents pick up (brainfile contract pickup), deliver, and you validate (brainfile contract validate) — which actually runs the validation commands. "Please do X" becomes verifiable.
• Agent instructions — project guidance lives in agent.instructions in the board config, one place agents are told to read before working.
• Decisions and a brief — brainfile decide records a standing choice under a claim key (a new one supersedes the old); brainfile check "<action>" says whether a decision still holds before an agent acts; every session starts with brainfile brief: the decisions that stand, the agent's tasks, what changed, and the docs that bear on them, from a local index of the board and the repo's Markdown.
• Hand-offs — brainfile dispatch task-12 --agent codex hands a task to a coding agent (Claude Code, Codex, Cursor, Antigravity, Grok, or any ACP server), which works in its own git worktree on dispatch/task-12, forked from where the task lands. The request is written on the task; a runner on the machine starts it: brainfile run in a terminal, or the desktop app. brainfile review, land, discard and pr take the work from there; brainfile dispatch epic-3 gives an epic a lead that hands its children off in order; brainfile discuss task-12 talks a task over with an agent first. Work lands on its own (--until done) only where brainfile dispatch policy bypass is set; otherwise it waits in Review for you. The same over MCP: dispatch, dispatch_status, dispatch_stop, dispatch_lead, review, pull_request, agents and discuss.
• Roles — an agent Brainfile starts carries its role in BRAINFILE_AGENT_ROLE (chat, lead, worker or discuss), and brainfile mcp and the CLI in its shell keep to it: a hand-off never hands off, a lead reaches only its own tree.
• The desktop is optional (decision-17) — everything the Mac app runs is in @brainfile/core, with a CLI command and an MCP tool for each. The app adds the window: the board's chat, Hand to… and Merge as one click, the review pane, and live runs, including those a terminal started.

This repository

Path	Package	What
cli/	brainfile	the CLI, TUI, and MCP server
core/	@brainfile/core	parser, schema, and operations library; hand-offs, the runner, worktrees and landing under @brainfile/core/dispatch and /repo
desktop/	—	the Mac app, a client of the same core; not published to npm, and optional
site/	—	the manual at brainfile.md, rendered from MANUAL.md

The board schema ships inside the CLI (cli/src/schemas/); the copies served at brainfile.md/v2/board.json exist so board frontmatter can reference a stable URL.

Docs

Everything is one page at brainfile.md — install, a quickstart, the board format, every command, contracts, the TUI and the MCP server. The same text is MANUAL.md here and brainfile.md/llms-full.txt for agents; the setup procedure for an agent is brainfile.md/llms-install.txt.

License

MIT © George Dikeakos