ReddRadar
Agent skill
brain-expert
Personal knowledge management expert for the brain CLI. Use when users want to capture notes, search their knowledge base, or manage their second brain.
Install this agent skill to your Project
npx add-skill https://github.com/desplega-ai/ai-toolbox/tree/main/cc-plugin/brain/skills/brain-expert
SKILL.md
Brain CLI Expert
You are an expert on the brain CLI - a personal knowledge management tool with hierarchical Markdown files, SQLite storage, and semantic search.
Quick Reference
| Command | Description |
|---|---|
brain init [path] |
Initialize brain directory |
brain add "text" |
Add timestamped note to today's file |
brain add -f file.md "text" |
Add to specific file |
brain add --ref /path "text" |
Add note referencing external file |
brain new "path/name" |
Create new entry, opens in editor |
brain list |
Show recent entries |
brain list --tree |
Show directory structure |
brain show <path> |
Display entry content |
brain edit <path> |
Open entry in editor |
brain delete <path> |
Delete entry (file + database) |
brain rm <path> |
Alias for delete |
brain sync |
Sync files to database |
brain sync --force |
Re-embed everything |
brain search "query" |
Semantic search (default) |
brain search --exact "term" |
Full-text search (FTS5) |
brain config show |
Display configuration |
brain todo add "text" |
Create a new todo |
brain todo list |
List open todos |
brain todo done <id> |
Mark todo as complete |
brain todo cancel <id> |
Cancel a todo |
brain todo edit <id> |
Edit todo in editor |
brain todo rm <id> |
Delete todo permanently |
brain cron install |
Install auto-sync cron job |
brain cron status |
Check auto-sync status |
brain cron remove |
Remove auto-sync cron job |
File Structure
Brain organizes files hierarchically:
~/Documents/brain/
├── 2026/
│ └── 01/
│ ├── 22.md # Daily journal (timestamped entries)
│ └── 23.md
├── projects/
│ ├── acme.md # Named entries (by topic)
│ └── startup-ideas.md
├── notes/
│ └── meeting-notes.md
└── .brain.db # SQLite database (gitignored)
Entry Formats
Daily Files (YYYY/MM/DD.md)
Auto-created when using brain add:
[2026-01-23-143022]
First thought of the day
[2026-01-23-153045]
Another thought with more context
Named Files
Created with brain new:
# Project Title
Content organized however you like.
Can include todos: - [ ] Task here
Search
Semantic Search (default)
Uses OpenAI embeddings for meaning-based search:
brain search "database optimization strategies"
Returns results ranked by semantic similarity.
Full-Text Search (--exact)
Uses SQLite FTS5 for literal text matching:
brain search --exact "PostgreSQL"
Sync Required
Before searching, ensure database is synced:
brain sync
The sync process:
- Scans all
.mdfiles - Chunks content (by timestamp blocks or headers)
- Generates embeddings for new/changed chunks
- Updates FTS5 index
Use brain sync --force to re-embed everything.
Configuration
Config stored at ~/.brain.json:
{
"path": "/Users/taras/Documents/brain",
"editor": "code",
"embeddingModel": "text-embedding-3-small"
}
Manage with:
brain config show- view configbrain config set editor vim- update value
Common Workflows
Quick Capture
brain add "Idea: could use SQLite for local caching"
Reference External Code
brain add --ref ./src/api/auth.ts "Need to add rate limiting here"
Find Related Notes
brain search "authentication patterns"
Create Project Notes
brain new "projects/new-feature"
# Opens editor with # New Feature header
Delete Entries
brain delete 2026/01/22 # Delete with confirmation
brain rm notes/old-project # Alias, same behavior
brain rm --force notes/temp # Skip confirmation
brain rm --db-only notes/draft # Keep file, remove from database
Todo Management
# Add todos with options
brain todo add "Review PR"
brain todo add -p myproject "Ship feature"
brain todo add -d tomorrow "Deploy to prod"
brain todo add -p work -d "next week" "Plan sprint"
# List and filter
brain todo list # Open todos
brain todo list --all # Include done/cancelled
brain todo list -p myproject # Filter by project
# Complete and manage
brain todo done 1 2 3 # Mark multiple as done
brain todo cancel 1 # Cancel a todo
brain todo edit 1 # Edit in $EDITOR
brain todo rm 1 # Delete permanently
Automatic Sync
# Set up background sync (runs every N minutes)
brain cron install # Default: 5 minutes
brain cron install --interval 15 # Custom interval
# Check and manage
brain cron status # "Active (every 5 minutes)"
brain cron remove # Stop auto-sync
Environment
- OPENAI_API_KEY: Required for semantic search embeddings
- EDITOR: Fallback if config.editor not set
Troubleshooting
| Issue | Solution |
|---|---|
| Search returns nothing | Run brain sync first |
| Embedding errors | Check OPENAI_API_KEY is set |
| Command not found | Run bun link in brain directory |
| Wrong brain path | Check brain config show |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
desplega-ai/ai-toolbox
wts-expert
Git worktree management expert for @desplega.ai/wts. Use when the user asks about git worktrees, wts commands, worktree workflows, or wants help managing multiple branches simultaneously.
desplega-ai/ai-toolbox
oapi-expert
OpenAPI CLI expert for @desplega.ai/oapi. Use when users want to register OpenAPI specs, execute API requests, manage auth profiles, explore API endpoints, or work with REST APIs from the terminal.
desplega-ai/ai-toolbox
brainstorming
Interactive exploration of ideas through Socratic Q&A. Produces progressive documents that serve as lightweight pre-PRDs feeding into research.
desplega-ai/ai-toolbox
tdd-planning
TDD-focused implementation planning. Creates plans with strict Red-Green-Commit/Rollback cycles for each step.
desplega-ai/ai-toolbox
planning
Implementation planning skill. Creates detailed technical plans through interactive research and iteration.
desplega-ai/ai-toolbox
phase-running
Execute individual plan phases as background sub-agents for context-efficient implementation.
Didn't find tool you were looking for?