brainfile

Markdown task boards for you and your AI agents.

One CLI, TUI, and MCP server. File-system native. MIT licensed.

---
title: My Project
columns:
  - id: todo
    title: To Do
  - id: in-progress
    title: In Progress
types:
  task: { idPrefix: task, completable: true }
  epic: { idPrefix: epic, completable: true }
  adr: { idPrefix: adr, completable: false }
---

---
id: task-12
title: Add rate limiting to API gateway
column: in-progress
assignee: codex
priority: high
parentId: epic-3
tags: [backend, performance]
relatedFiles:
  - src/api/gateway.ts
subtasks:
  - id: task-12-1
    title: Write unit tests
    completed: false
---

# added to task-12 frontmatter
contract:
  status: in_progress
  deliverables:
    - path: src/middleware/rateLimiter.ts
      description: Token bucket implementation
    - path: src/__tests__/rateLimiter.test.ts
      description: Unit tests
  validation:
    commands:
      - npm test -- rateLimiter
      - npm run build
  constraints:
    - Token bucket algorithm
    - Non-blocking async implementation

$ brainfile contract validate -t task-12
✓ Checking deliverables...
  ✓ src/middleware/rateLimiter.ts exists
  ✓ src/__tests__/rateLimiter.test.ts exists
✓ Running validation commands...
  ✓ npm test -- rateLimiter (exit 0)
  ✓ npm run build (exit 0)

✓ Contract validated. Status: done

Contract Lifecycle

How It Works

01define

Write a contract as a markdown file in your repo.

02delegate

An agent picks it up, implements, and delivers.

03validate

Automated commands verify the deliverables. Done.

Design Decisions

Why files?

Tasks live in your repo. Git history is your audit trail. No database, no API, no vendor lock-in.

Why contracts?

Informal "please do X" breaks down at scale. Structured deliverables and validation commands make agent output verifiable.

Why one format?

Agents change. Claude, Cursor, Codex, the next thing. Plain files and one schema outlive all of them.

Ecosystem

Integrations are optional adapters. Your board files come first.

⌘stable

CLI & TUIThe main tool. Manage boards, contracts, and validation from the terminal.

◈stable

MCP ServerExpose your board to any LLM. Model Context Protocol bridge for agent integration.

◻stable

Core LibraryBuild your own integrations. TypeScript SDK for parsing, validating, and manipulating boards.

Quick Start

terminal

$ npm install -g brainfile

$ brainfile init
✓ Created .brainfile/brainfile.md

$ brainfile add -c todo --title "My first task" --with-contract \
  --deliverable "file:src/feature.ts:Implementation" \
  --validation "npm test"
✓ Created task-1

$ brainfile contract pickup -t task-1
✓ Contract status: in_progress

$ brainfile contract deliver -t task-1
✓ Contract status: delivered

Full Quick Start guide →