Local Brain

 ______     ______     ______     __     __   __
/\  == \   /\  == \   /\  __ \   /\ \   /\ "-.\ \
\ \  __<   \ \  __<   \ \  __ \  \ \ \  \ \ \-.  \
 \ \_____\  \ \_\ \_\  \ \_\ \_\  \ \_\  \ \_\\"\_\
  \/_____/   \/_/ /_/   \/_/\/_/   \/_/   \/_/ \/_/

A minimalist, local-first project management system for developers who live in the terminal.

Local Brain is a context manager for your workflow. It stitches together your notes, tasks, and code repositories into a cohesive, keyboard-driven environment.

---

Quick Start

Install

# macOS/Linux (Homebrew)
brew tap SanderMoon/tap
brew install brain

# Or via Go
go install github.com/SanderMoon/local-brain@latest

Initialize

brain init

Start Using

# Capture thoughts instantly
brain add "Fix authentication bug"
brain add "Review Sarah's PR"

# Process and organize later
brain refile

# Weekly planning
brain plan

# Optional: Launch the TUI for visual overview
brain tui

CLI-First Design: All features are accessible via CLI commands. The TUI is optional for visual project and task management.

📖 Full Documentation →

---

Core Philosophy: Capture Fast, Curate Later

Local Brain follows a two-phase workflow:

Phase 1: Capture (< 1 second)

• No metadata, no decisions, no interruptions
• Everything goes to your dump (00_dump.md)

Phase 2: Curate (dedicated time blocks)

• Batch process items with brain refile
• Enrich tasks with brain plan (priorities, due dates, tags)

This keeps you in flow while maintaining organized projects.

---

Features

• CLI-First Design - Fast, scriptable commands for all operations. Optional TUI for visual overview.
• Zero-Friction Capture - Add tasks in < 1 second without context switching
• Batch Curation - Process and organize during dedicated time blocks
• Local-First - Plain text Markdown files, grep-able, version-controllable
• Developer-Friendly - Integrates with git repos, supports JSON API for scripts
• AI Assistant Integration - MCP server for Claude Desktop and other AI tools (setup guide)
• Privacy-First - Everything lives locally in ~/brains/, syncable via Syncthing/Dropbox

---

Documentation

• 🚀 Quickstart Guide - Get started in 3 minutes
• 📦 Installation - All installation methods
• 📖 Command Reference - Complete command documentation
• 🤖 MCP Server Setup - AI assistant integration (Claude Desktop)
• 💻 Development Guide - Contributing and architecture

---

Daily Workflow Example

Morning (Capture):

brain add "Fix auth bug in login"
brain add "Review Sarah's PR"
brain add "Update deployment docs"

End of Day (Curate - Refile):

brain refile
# Interactive prompts move items to projects:
# - "Fix auth bug" → backend-api
# - "Review Sarah's PR" → frontend
# - "Update deployment docs" → backend-api

Friday (Curate - Plan):

brain plan
# Add priorities, due dates, tags, states

Throughout the Week:

brain todo ls --status in-progress --priority 1
brain todo ls --overdue
brain todo done <id>

---

Key Concepts

Brains: Top-level workspaces (e.g., "Work", "Personal"). Only one active at a time, symlinked to ~/brain.

Projects: Focus areas within a brain (e.g., "website-redesign"). Each has notes.md, todo.md, and optional code repo links.

Dump: Your inbox (00_dump.md) for rapid capture. Process it regularly with brain refile.

Learn more →

---

Contributing

Contributions are welcome! See the Development Guide for setup, architecture, and contributing guidelines.

# Quick setup for contributors
git clone https://github.com/SanderMoon/local-brain.git
cd local-brain
make build
make test

---

Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: https://sandermoon.github.io/local-brain/

---

License

MIT License - See LICENSE file for details.

---

📖 Read the Full Documentation