brainfile

An open protocol for agent-to-agent task coordination.

Human-in-the-loop compatible. 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

A contract has a 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 a protocol?

Tools change. Claude, Cursor, Copilot, the next thing. A protocol survives all of them.

Ecosystem

Integrations are optional adapters. The protocol comes first.

⌘stable

CLI & TUIThe reference implementation. 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.

πbeta

Pi ExtensionShowcase orchestrator integration for multi-agent runs with contract coordination.

Get started in 30 seconds.

terminal

$ npm install -g @brainfile/cli

$ 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 →