A protocol-first task management system designed for the AI era.

Brainfile is a simple, human-readable format for managing project tasks that both humans and AI coding assistants can read, write, and collaborate through. Think of it as a shared language for project management between you and your AI pair programmer.

At its core, Brainfile is just a brainfile.md file with YAML frontmatter:

---
schema: https://brainfile.md/v1
title: My Project
agent:
  instructions:
    - Update task status as you work (todo → in-progress → done)
    - Make minimal, atomic changes
columns:
  - id: todo
    title: To Do
    tasks:
      - id: task-1
        title: Implement user authentication
        priority: high
  - id: done
    title: Done
    tasks: []
---

That's it. No database, no backend, no complex setup. Just a markdown file that lives in your repository.

• Designed specifically for AI-assisted development
• Optional agent instructions guide AI behavior
• Protocol-based: tools are conveniences, the file is the source of truth

• Plain text YAML and Markdown
• Easy to edit directly or with tools
• Version control friendly (perfect for git)

• JSON Schema validation
• Multiple implementations (TypeScript, CLI, VSCode)
• Build your own tools on the protocol

• No dependencies required
• File-based (no database)
• Works offline
• Portable across projects

# Coming soon to VS Code Marketplace
# For now, download from releases

npm install -g @brainfile/cli

# Create a new brainfile
brainfile init

# List tasks
brainfile list

# Add a task
brainfile add "Implement feature" --priority high

npm install @brainfile/core

import { Brainfile } from '@brainfile/core';

const brain = new Brainfile();
const board = await brain.parse('./brainfile.md');

// Access tasks
const todoTasks = board.columns.find(c => c.id === 'todo')?.tasks;

// Modify and save
brain.serialize(board, './brainfile.md');

• 🤝 AI Pair Programming: Give your AI assistant context about your project's tasks
• 📋 Project Management: Simple, version-controlled task tracking
• 🚀 CI/CD Integration: Automate task updates in your pipelines
• 📝 Documentation: Tasks live alongside your code
• 🔄 Async Collaboration: AI and humans work on the same task board

Add this comment to your README to auto-load tasks for AI assistants:

<!-- load:brainfile.md -->

Now when AI coding assistants read your README, they automatically understand your project's task context.

For the simplest integration, add these instructions to your agent configuration file (AGENTS.md, CLAUDE.md, .cursorrules, etc.):

# Task Management Rules

- review and follow rules in @brainfile.md
- update task status in @brainfile.md as you work (todo → in-progress → done)
- reference `schema` in the file for how to create tasks
- your existing tools do not modify this file, you need to edit it directly

Recommended: Keep only these minimal instructions in your agent config file, and use brainfile.md for project-specific rules and context. This keeps agent instructions clean and portable across projects.

• Schema: https://brainfile.md/v1
• Protocol Spec: protocol/docs/protocol.md
• Agent Guide: protocol/docs/agents.md

We welcome contributions! Each repository has its own contributing guide:

• Protocol changes → brainfile/protocol
• Core library → brainfile/core
• CLI tool → brainfile/cli
• VSCode extension → brainfile/vscode

The protocol is the product.

Brainfile is protocol-first. The brainfile.md format is the core, and tools (CLI, VSCode, etc.) are conveniences. You don't need any tools—just the file and an AI assistant that understands it.

This means:

• ✅ No vendor lock-in
• ✅ Your data is portable
• ✅ Build your own tools
• ✅ Works with any editor
• ✅ Compatible with future AI models

MIT License - All repositories are open source.

Get Started: Check out the protocol repository or install the CLI!