Quick Start

Bootstrap with an Agent

Paste this URL into any agent chat and tell it to set up brainfile:

https://brainfile.md/llms-install.txt

The agent gets install commands, MCP config, CLI reference, and the contract workflow in one document.

Get a task board in your project in under a minute.

1. Install

npm install -g @brainfile/cli

2. Initialize

brainfile init

This creates the .brainfile/ directory with:

• .brainfile/brainfile.md — Board configuration (columns, types, rules)
• .brainfile/board/ — Active task files
• .brainfile/logs/ — Completed task archive

.brainfile/
├── brainfile.md    ← Board config (columns, types, rules)
├── board/          ← Active task files go here
└── logs/           ← Completed tasks archived here

Default columns are To Do and In Progress.

3. Use It

Interactive TUI

brainfile          # No arguments launches the TUI
brainfile tui      # Explicit subcommand also works

Navigate with keyboard: TAB for columns, j/k for tasks, Enter to expand, q to quit.

CLI Commands

brainfile list                              # See all tasks
brainfile add --title "My first task"       # Add a task
brainfile move --task task-1 --column in-progress  # Move columns
brainfile complete --task task-1            # Complete (moves to logs/)

---

Add AI Integration

Want your AI assistant to manage tasks directly? Add this to .mcp.json in your project:

{
  "mcpServers": {
    "brainfile": {
      "command": "npx",
      "args": ["@brainfile/cli", "mcp"]
    }
  }
}

Works with Claude Code, Cursor, Cline, and any MCP-compatible tool.

What can AI do with this?

Your assistant can now list tasks, create new ones, move them between columns, update priorities, and manage subtasks — all without you copy-pasting anything.

---

Agent Coordination (Optional)

Brainfile allows you to create Contracts for your AI assistants. A contract defines exactly what an agent needs to deliver.

1. Create a task with a contract

brainfile add --title "Create API docs" \
  --with-contract \
  --deliverable "docs/api.md" \
  --validation "npm run docs:build"

2. How agents use it

When an AI agent (like Claude or Cursor) picks up this task, it will see the structured deliverables and validation commands. This ensures the agent produces exactly what you need.

---

Next Steps

• Why Brainfile? — The philosophy behind file-based coordination
• Getting Started with Contracts — Define deliverables for AI agents
• CLI Commands — Full command reference and TUI guide
• MCP Integration — Connect your AI assistant directly
• Protocol Specification — File format and schema details