Give your AI agent a brain.
A local-first project management system designed for AI agents. One command creates a structured knowledge base with departments, execution plans, agent personas, and 8 slash commands. Your AI stops guessing and starts executing.
Quick Start · The Problem · How It Works · Commands · Workflow · Contributing
AI coding assistants are powerful, but they have no memory between sessions. Every time you start a new conversation, you lose context. Your AI doesn't know what was built yesterday, what's blocked, or what to work on next.
BrainTree OS solves this. It gives your AI agent an organizational structure (a "brain") that persists across sessions. The brain contains everything: project vision, technical architecture, marketing strategy, execution plan, session handoffs, and agent personas. Your AI reads this brain at the start of every session and knows exactly where things stand.
The result: Instead of "what should I work on?", your AI says "Last session you completed the auth system. The API layer is now unblocked. Here are your top 3 priorities."
- Not a template generator. BrainTree creates 25-40 files of real, actionable content tailored to YOUR project.
- Not a task tracker. It's a full organizational brain with departments, execution plans, and cross-linked knowledge.
- Not cloud-dependent. Everything runs locally. No accounts, no API keys, no data leaving your machine.
- Not just for code. Marketing, product strategy, business development, and operations are first-class citizens.
Requires Node.js 20+ and Claude Code
npx brain-tree-osThis starts a local web server and opens a brain viewer in your browser. A demo brain is included so you can explore immediately.
Open Claude Code in any project directory and run:
/init-braintree
An interactive wizard asks about your project and generates a complete brain structure: departments, execution plan, agent personas, templates, and more.
/resume-braintree
Claude reads your brain, shows you what was done last session, what's in progress, and recommends what to tackle next. When you're done:
/wrap-up-braintree
This updates your brain files, creates a handoff document, and logs your progress. Next session picks up exactly where you left off.
You run: npx brain-tree-os
|
v
+----------------------------+
| CLI |
| 1. Installs 8 commands |
| to ~/.claude/commands/ |
| 2. Starts Next.js server |
| 3. Opens browser |
+----------------------------+
|
v
+----------------------------+ +--------------------+
| Brain Viewer (localhost) |<--->| Your Project |
| - Graph visualization | | .braintree/ |
| - File tree browser | | BRAIN-INDEX.md |
| - Markdown viewer | | CLAUDE.md |
| - Execution plan pane | | 00_Company/ |
| - Session timeline | | 01_RnD/ |
+----------------------------+ | 02_Product/ |
| | Execution-Plan/ |
WebSocket | Handoffs/ |
| +--------------------+
+--- live updates via chokidar ---+
When you create or edit files through Claude Code, they appear in the browser instantly. The viewer watches your filesystem and updates the graph, file tree, and content in real time.
Every brain is a directory on your filesystem with this structure:
my-project/
├── .braintree/
│ └── brain.json # Brain metadata (id, name, description)
├── BRAIN-INDEX.md # Central hub linking to everything
├── CLAUDE.md # AI agent instructions ("brain DNA")
├── Execution-Plan.md # Build roadmap with phases and steps
│
├── 00_Company/ # Identity, vision, mission, values
│ ├── Company.md # Folder index
│ ├── Mission.md
│ └── Values.md
├── 01_RnD/ # Engineering, architecture, tech stack
│ ├── RnD.md
│ ├── Architecture.md
│ └── Tech-Stack.md
├── 02_Product/ # MVP scope, roadmap, features
│ ├── Product.md
│ ├── MVP-Scope.md
│ └── Feature-Priorities.md
├── 03_Marketing/ # Go-to-market, content, SEO
│ └── ...
│
├── Handoffs/ # Session continuity documents
│ ├── Handoffs.md
│ ├── handoff-001.md
│ └── handoff-002.md
├── Templates/ # Reusable note templates
├── Assets/ # Images, PDFs, reference files
└── .claude/agents/ # AI agent persona files
├── builder.md
├── strategist.md
└── researcher.md
BRAIN-INDEX.md is the central hub. It links to every top-level folder and file. When your AI agent reads this first, it instantly understands the full project structure.
CLAUDE.md contains the brain's "DNA": conventions, rules, and instructions that every AI agent follows. Think of it as the team handbook.
Wikilinks ([[like this]]) connect files into a knowledge graph. The viewer renders these as interactive nodes and edges. Every file links back to its parent via > Part of [[ParentIndex]], creating a clean hierarchy with no orphan nodes.
Execution Plan is a structured build roadmap with phases, steps, and task checklists. Each step has a status (not_started, in_progress, completed, blocked) and dependencies on other steps.
Handoffs are session continuity documents. Each one captures what was done, decisions made, blockers found, and what to do next. This is what makes /resume-braintree so powerful.
Agent Personas (in .claude/agents/) define specialized AI roles for your project. A builder focuses on code, a strategist on product decisions, a researcher on market analysis. Each has their own instructions and capabilities.
BrainTree installs 8 slash commands into Claude Code. These are the core of the workflow.
Create a new brain from scratch.
A multi-phase interactive wizard that:
- Asks about your project (what you're building, who it's for, what you have so far)
- Generates a custom brain structure tailored to your specific goals
- Creates 25-40+ files with real, actionable content (not empty templates)
- Sets up agent personas matched to your needs
- Builds an execution plan with phases and dependencies
The brain appears in the viewer in real time as files are created.
Resume work from where you left off.
The most important command. Every session starts here. It:
- Reads your full brain context (BRAIN-INDEX, CLAUDE.md, latest handoff, execution plan)
- Shows what was accomplished last session
- Displays progress bars for each phase
- Lists the top unblocked steps ranked by priority
- Identifies parallel execution opportunities
- Asks what you want to work on
Transforms a vague "what should I do?" into a clear action plan.
End your session with full continuity.
Creates a bridge to your next session by:
- Auditing everything done in the current session
- Updating all affected brain files (departments, indexes, execution plan)
- Marking execution plan steps as completed/in-progress/blocked
- Creating a detailed handoff document with:
- Session summary
- Files created/modified
- Decisions made and their rationale
- Open blockers
- Recommended next steps
- Updating brain indexes to prevent orphan nodes
This is what makes session continuity work. Without it, your next /resume-braintree wouldn't know what happened.
Full project health dashboard.
Shows:
- Execution plan progress bars for each phase
- Steps in progress, blocked, and ready to start
- File counts and health per department
- Knowledge graph stats (total files, wikilinks, orphans)
- Session timeline from recent handoffs
- Recommendations for what to fix or tackle next
Break a high-level step into concrete tasks.
Takes an execution plan step and creates a detailed implementation plan:
- Numbered tasks with effort estimates (S/M/L)
- Task dependencies and parallel opportunities
- Specific files to create or modify
- Acceptance criteria
- Saves the plan to your brain for reference
Plan a week of work.
Agile-style sprint planning:
- Analyzes unblocked and in-progress steps
- Groups work into parallel blocks by theme
- Creates a day-by-day plan with effort estimates
- Identifies dependencies and buffer time
Brain health check and auto-repair.
Audits your brain for:
- Orphan files (not connected to the graph)
- Broken wikilinks (pointing to files that don't exist)
- Empty folders with no content
- Stale content (TODO markers, outdated info)
- Execution plan drift
Fixes most issues automatically and asks about ambiguous cases.
Plan and implement a new feature.
End-to-end feature management:
- Creates a feature spec with user stories, requirements, and technical approach
- Links it to the execution plan
- Breaks it into implementation tasks
- Guides you through each task
- Updates the brain as you go
$ npx brain-tree-os # Start the viewer
$ claude # Open Claude Code
> /init-braintree # Create your brain
The wizard asks questions and builds your brain in real time. Watch it appear in the browser as files are created.
> /resume-braintree # Load context, see progress, pick a task
> ... work on your project ...
> /wrap-up-braintree # Save progress, create handoff
Every resume reads the last handoff. Every wrap-up creates the next one. Context is never lost.
Here's what a typical /resume-braintree output looks like after 10 sessions:
Session 10 | March 22, 2026
Last session: Built the authentication system (Google + GitHub OAuth),
deployed to Vercel, fixed DNS routing. See handoff-009.
Progress:
Phase 1: Foundation [==========] 100% (7/7)
Phase 2: Core Build [======----] 60% (6/10)
Phase 3: Polish [----------] 0% (0/5)
In Progress:
- Step 2.4: API routes (started yesterday, 3/7 tasks done)
Ready to Start:
- Step 2.5: Real-time updates (unblocked by Step 2.4)
- Step 2.7: Mobile responsiveness (no dependencies)
What would you like to work on?
Your AI agent has full context. It knows the architecture decisions from Session 3, the bug fix from Session 7, and the blocker identified in Session 9. No re-explaining needed.
The web viewer at localhost:3000 shows your brain visually:
Three-pane layout: file tree on the left, interactive D3.js graph in the center (nodes color-coded by department, click to open), and execution plan on the right showing phases, steps, and progress.
Files created or edited in Claude Code appear in the browser within seconds. The graph grows, the file tree updates, and content refreshes automatically via WebSocket.
BrainTree ships with a demo brain based on clsh.dev, a real project built from zero to launch in 6 days across 38 sessions. It demonstrates:
- Full brain structure with 43 interconnected files
- Complete execution plan with phases and completed steps
- Session handoffs showing how the project evolved
- Department organization (Company, RnD, Product, Marketing, etc.)
Explore it at http://localhost:3000/brains/demo after running npx brain-tree-os.
| Layer | Technology |
|---|---|
| Frontend | Next.js 15, React 19, Tailwind CSS v4, shadcn/ui |
| Graph | D3.js force simulation |
| Real-time | WebSocket (ws) + chokidar filesystem watcher |
| CLI | Node.js, TypeScript |
| Monorepo | Turborepo, npm workspaces |
- CLI starts Next.js server with custom HTTP + WebSocket handler
- Browser connects to WebSocket at
/ws - User selects a brain; server starts watching that brain's directory with chokidar
- When files change on disk, server sends
file-changedevents - Browser re-fetches data and updates graph/tree/viewer
All data comes from the filesystem. No database.
- Brain registry:
~/.braintree-os/brains.jsontracks all registered brains - File scanning: Recursively finds all
.mdfiles in a brain directory - Wikilink parsing: Extracts
[[links]]from file content to build the graph - Execution plan parsing: Structured extraction of phases, steps, and tasks from markdown
Want hosted brains, team collaboration, and a managed MCP server? Check out brain-tree.ai, the cloud version of BrainTree with:
- Brain generation wizard in the browser
- Shared brains with team members
- MCP server for remote AI agent access
- OAuth authentication (Google, GitHub)
- Subscription management
BrainTree OS and brain-tree.ai use the same brain format. You can start locally and move to the cloud, or use both.
Do I need Claude Code? The brain viewer works without it, but the 8 slash commands are designed for Claude Code. They're what make the AI-assisted workflow possible.
Can I use this with other AI tools? The brain itself is just markdown files and folders. Any AI tool that can read and write files can work with a brain. The slash commands are Claude Code specific, but the brain format is universal.
Where does my data go? Nowhere. Everything stays on your local filesystem. BrainTree OS makes zero network requests. No telemetry, no analytics, no cloud sync.
Can I use my own folder structure? Yes. The init wizard generates a suggested structure, but you can reorganize freely. As long as you maintain wikilinks and the BRAIN-INDEX hub, the graph will work.
How is this different from Obsidian? Obsidian is a general-purpose note-taking app. BrainTree is purpose-built for AI-assisted project execution. The brain structure, slash commands, execution plan tracking, session handoffs, and agent personas are all designed for a specific workflow: AI and human building a product together.
We welcome contributions! See CONTRIBUTING.md for development setup and guidelines.
Found a vulnerability? See SECURITY.md for our disclosure policy.
MIT. See LICENSE for details.
Your project brain should be yours. No cloud required.
brain-tree.ai · npm · Discord