@magic-ingredients/tiny-brain

CLI for the Tiny Brain AI assistant framework. Provides installation management, TDD workflow enforcement, progress tracking, configuration, and developer tooling.

Installation

npm install -g @magic-ingredients/tiny-brain

The CLI is available as the tiny-brain command. Running with no arguments starts the MCP server.

Commands

Platform Installation

tiny-brain install [platform]

Install the tiny-brain MCP server for an AI platform.

| Option | Description | Default | |--------|-------------|---------| | --all | Install for all supported platforms | - | | -s, --scope <scope> | Configuration scope: local, user, or project | local | | -n, --name <name> | Server name | tiny-brain | | --validate | Validate server startup during installation | - |

Supported platforms: claude-code, claude-desktop

tiny-brain install claude-code
tiny-brain install claude-desktop --scope user
tiny-brain install --all

tiny-brain uninstall [platform]

Remove the tiny-brain MCP server from an AI platform.

| Option | Description | Default | |--------|-------------|---------| | --all | Uninstall from all installed platforms | - | | -s, --scope <scope> | Configuration scope: local, user, or project | local | | -n, --name <name> | Server name | tiny-brain | | -f, --force | Skip confirmation prompt | - |

tiny-brain uninstall claude-code
tiny-brain uninstall --all --force

tiny-brain status

Check installation status for all platforms.

| Option | Description | Default | |--------|-------------|---------| | -n, --name <name> | Server name | tiny-brain | | -s, --scope <scope> | Configuration scope | local | | -p, --platform <platform> | Check a specific platform only | - | | -v, --verbose | Show detailed information | - |

tiny-brain status
tiny-brain status --platform claude-code --verbose

tiny-brain list (alias: ls)

List all supported platforms.

| Option | Description | |--------|-------------| | -d, --detected | Show which platforms are detected on the system |

tiny-brain list
tiny-brain list --detected

Configuration

tiny-brain config <operation> [key] [value]

Manage credentials and preferences.

Credential operations:

| Operation | Description | |-----------|-------------| | set <key> <value> | Store a credential (clientId, clientSecret, llmApiKey) | | show | Display stored credentials (masked) | | unset | Remove all stored credentials |

tiny-brain config set clientId YOUR_CLIENT_ID
tiny-brain config set clientSecret YOUR_SECRET
tiny-brain config set llmApiKey YOUR_API_KEY
tiny-brain config show
tiny-brain config unset

Preference operations (config preferences):

| Subcommand | Description | |------------|-------------| | list | Show all preference values | | get <key> | Get a single preference value | | set <key> <value> [--global\|--repo] | Set a preference (defaults to repo scope) | | reset | Reset all preferences to defaults | | show-sources | Show each preference with its source (Default/Global/Repository) |

Available preference keys:

| Key | Type | Description | |-----|------|-------------| | autoCommitProgress | boolean | Auto-commit progress.json after tracked commits | | autoArchive | boolean | Auto-archive completed work | | enableAgenticCoding | boolean | Enable agentic coding mode | | enableSDD | boolean | Enable Spec-Driven Development | | enableTDD | boolean | Enable Test-Driven Development | | combineRedGreenCommits | boolean | Combine RED/GREEN into single commits | | enableAdversarial | boolean | Enable adversarial review | | enableADR | boolean | Enable Architecture Decision Records | | enableQuality | boolean | Enable quality analysis | | manageAgentsMd | boolean | Auto-manage AGENTS.md files | | defaultPersona | string | Default persona ID | | docsDirectory | string | Documentation directory path | | adrDirectory | string | ADR directory path | | prdDirectory | string | PRD directory path | | testPatterns | JSON | Test file glob patterns |

tiny-brain config preferences list
tiny-brain config preferences get enableTDD
tiny-brain config preferences set enableTDD true
tiny-brain config preferences set autoCommitProgress true --global
tiny-brain config preferences show-sources
tiny-brain config preferences reset

Config file locations:

• Global: ~/.tiny-brain/config/preferences.json
• Repository: <repo>/.tiny-brain/config.json

Repository config takes precedence over global config.

Repository Analysis

tiny-brain analyse [path]

Analyse a repository's tech stack and output metadata to .tiny-brain/analysis.json.

tiny-brain analyse
tiny-brain analyse /path/to/repo

Git Hooks

tiny-brain hooks <subcommand>

Manage TDD git hooks (commit-msg, post-commit).

| Subcommand | Description | Options | |------------|-------------|---------| | install | Install TDD git hooks | -f, --force overwrite existing hooks | | uninstall | Remove TDD git hooks | -f, --force remove even non-tiny-brain hooks | | status | Show current git hooks status | - |

tiny-brain hooks install
tiny-brain hooks install --force
tiny-brain hooks uninstall
tiny-brain hooks status

Worktrees

tiny-brain go <name>

Create a git worktree from the remote default branch and launch Claude Code in it.

| Option | Description | |--------|-------------| | --skip-install | Skip dependency installation |

tiny-brain go my-feature
tiny-brain go bugfix --skip-install

tiny-brain go-local <name>

Same as go, but creates the worktree from local HEAD instead of remote.

| Option | Description | |--------|-------------| | --skip-install | Skip dependency installation |

tiny-brain go-local my-experiment

tiny-brain worktree <subcommand>

Manage existing worktrees.

| Subcommand | Description | |------------|-------------| | list | List all worktrees | | remove <name> | Remove a worktree |

tiny-brain worktree list
tiny-brain worktree remove my-feature

Dashboard

tiny-brain dashboard <subcommand>

Manage the dashboard web server.

| Subcommand | Description | Options | |------------|-------------|---------| | start | Start as a background daemon | -p, --port <port> (default: 8765), --if-not-running | | stop | Stop the daemon | - | | restart | Restart the daemon | -p, --port <port> (default: 8765) | | status | Check if the daemon is running | - | | dev | Start in foreground with live reload | -p, --port <port> (default: 8765) |

tiny-brain dashboard start
tiny-brain dashboard start --port 9000 --if-not-running
tiny-brain dashboard stop
tiny-brain dashboard restart
tiny-brain dashboard status
tiny-brain dashboard dev

Shell Integration

tiny-brain statusline

Output compact statusline text for embedding in shell prompts.

| Option | Description | Default | |--------|-------------|---------| | -p, --path <path> | Repository path | Current directory | | -s, --short | Truncate to ~69 characters | - |

tiny-brain statusline
tiny-brain statusline --short
tiny-brain statusline --path /path/to/repo

Personas

tiny-brain as <personaName>

Output formatted persona context to stdout. Used by the session-start hook to inject persona-specific instructions.

| Option | Description | |--------|-------------| | --context-file <path> | Context file path for confirmation block |

tiny-brain as developer
tiny-brain as reviewer --context-file CLAUDE.md

Capabilities

tiny-brain capability install <id>

Register a capability as installed. Adds the capability ID to .tiny-brain/capabilities/installed.json.

tiny-brain capability install adversarial-reviewer
tiny-brain capability install mutation-testing

TDD Workflow Commands

These commands are used by git hooks and AI agents to enforce the TDD workflow. They are hidden from --help output but documented here for reference.

tiny-brain pipeline

The single authority for pipeline state management. Advances the TDD pipeline: records steps, derives phase, and outputs next instructions.

| Option | Description | |--------|-------------| | --task-id <id> | (required) Task ID/description | | --fix <id> | Fix ID | | --prd <id> | PRD ID | | --feature <id> | Feature ID | | --agent <name> | Agent/step that just completed (red, green, or a review type) | | --sha <sha> | Commit SHA for red/green/refactor steps | | --decision <verdict> | Review verdict: clean or dirty | | -q, --quiet | Print only the phase string (for hooks) |

# Enter pipeline at RED phase (before writing tests):
npx tiny-brain pipeline --task-id 'Add user validation' --fix my-fix --agent red

# Enter at GREEN phase (skip tests for non-testable work):
npx tiny-brain pipeline --task-id 'Update config' --fix my-fix --agent green

tiny-brain task <subcommand>

Manage TDD task lifecycle.

| Subcommand | Description | |------------|-------------| | start | Start a task (sets status to in_progress) | | phase | Print the derived TDD phase for a task | | sync <filePath> | Sync PRD/feature/fix markdown to progress.json |

task start options:

| Option | Description | |--------|-------------| | --task <description> | (required) Task description | | --prd <id> | PRD ID | | --feature <id> | Feature ID | | --fix <id> | Fix ID | | --phase <phase> | Starting phase: red (default) or green (skips RED) |

task phase options:

| Option | Description | |--------|-------------| | --task <description> | (required) Task description | | --prd <id> | PRD ID | | --feature <id> | Feature ID | | --fix <id> | Fix ID |

task sync options:

| Option | Description | |--------|-------------| | --force | Force full re-sync (overwrite tracked tasks) |

npx tiny-brain task start --task 'Add email validation' --fix email-bug --phase red
npx tiny-brain task phase --task 'Add email validation' --fix email-bug
npx tiny-brain task sync .tiny-brain/fixes/email-bug.md
npx tiny-brain task sync docs/prd/my-feature/prd.md --force

tiny-brain commit <subcommand>

Manage TDD commit lifecycle.

| Subcommand | Description | |------------|-------------| | track <sha> <message> | Track a commit SHA for TDD workflow (called by git hooks) | | validate <messageFile> | Validate PRD/Feature/Task or Fix/Task references in a commit message | | progress | Stage and commit progress tracking files |

commit track options:

| Option | Description | |--------|-------------| | -v, --verbose | Show detailed output |

commit progress options:

| Option | Description | |--------|-------------| | -v, --verbose | Show detailed output |

npx tiny-brain commit track abc1234 "feat(auth): add login"
npx tiny-brain commit validate .git/COMMIT_EDITMSG
npx tiny-brain commit progress

tiny-brain persist <agentName>

Persist agent output (review JSON, reports) to the correct location.

| Option | Description | |--------|-------------| | --sha <sha> | Implementation commit SHA (required for pipeline mode) | | --quality | Write to the latest quality run directory instead | | --json <json> | (required) JSON string to persist |

npx tiny-brain persist adversarial-review --sha abc1234 --json '{"verdict":"clean"}'
npx tiny-brain persist code-quality --quality --json '{"score":85}'

tiny-brain review

Persist review JSON (read from stdin) and update the reviews map on progress tasks.

| Option | Description | |--------|-------------| | --type <type> | (required) Review type (e.g., adversarial, mutation) | | --sha <sha> | (required) Implementation commit SHA | | --prd <id> | PRD ID | | --feature <id> | Feature ID | | --fix <id> | Fix ID | | --task <description> | Task description |

Reads JSON from stdin and prints the verdict to stdout.

echo '{"findings":[]}' | npx tiny-brain review --type adversarial --sha abc1234

Legacy Commands

These commands are maintained for backwards compatibility. Prefer the grouped equivalents above.

| Legacy Command | Equivalent | |----------------|------------| | tiny-brain task-start | tiny-brain task start | | tiny-brain track-commit <sha> <msg> | tiny-brain commit track <sha> <msg> | | tiny-brain derive-phase | tiny-brain task phase | | tiny-brain validate-commit-message <file> | tiny-brain commit validate <file> | | tiny-brain validate-fix-message <file> | tiny-brain commit validate <file> | | tiny-brain sync-progress <file> (alias: sync-file) | tiny-brain task sync <file> | | tiny-brain commit-progress | tiny-brain commit progress | | tiny-brain record-review | tiny-brain review |

Environment Variables

| Variable | Description | |----------|-------------| | TINY_BRAIN_CONFIG_DIR | Override the base config directory (default: ~/.tiny-brain) |

License

MIT