binnacle

A CLI tool for AI agents and humans to track project state. Think of it as a lightweight, JSON-first task tracker that lives outside your repo.

[!WARNING] Binnacle is very early in development, proceed with caution!

Quick Start

# Install (from source for now)
cargo install --path .

# Initialize in your project
cd your-project
bn system init      # Interactive setup with prompts

# Create a task
bn task create "Implement user authentication"

# See what's ready to work on
bn ready

# Update task status as you work
bn task update bn-xxxx --status in_progress
bn task close bn-xxxx --reason "Implemented JWT auth"

Features

• JSON-first output - Machine-readable by default, -H for human-readable
• No repo pollution - Data stored externally in ~/.local/share/binnacle/<repo-hash>/
• Task dependencies - Block tasks on other tasks, query what's ready
• Test tracking - Link tests to tasks, auto-reopen tasks on regression
• Action logging - Comprehensive audit log of all commands with timestamps and metadata
• MCP server - Expose all operations as MCP tools for AI agents
• Work queue - Prioritize tasks for agents with a global work queue

Queue (Agent Prioritization)

The queue feature allows operators to signal which tasks agents should work on first:

# Create a queue (one per repo)
bn queue create "Sprint 1"

# Add tasks to the queue
bn link add bn-xxxx bnq-yyyy --type queued

# View queue and its tasks
bn queue show

# bn ready now shows queued tasks first
bn ready -H
# Ready tasks (5):
#   [QUEUED]
#     [P1] bn-xxxx: Fix auth bug
#   [OTHER]
#     [P2] bn-yyyy: Refactor utils

# Tasks are automatically removed from queue when closed
bn task close bn-xxxx --reason "Fixed"

Commands

bn                    Status summary
bn orient             Onboarding for AI agents
bn system init        Initialize database (interactive, recommended)
bn task create/list/show/update/close/delete
bn link add/rm/list   Manage relationships (dependencies, etc.)
bn ready              Tasks with no blockers
bn blocked            Tasks waiting on dependencies
bn queue create/show/delete  Agent work prioritization
bn test create/run    Test node management
bn commit link/list   Associate commits with tasks
bn mcp serve          Start MCP server
bn gui                Start web GUI (requires gui feature)

Use bn --help or bn <command> --help for full details.

Web GUI

Binnacle includes an optional web-based GUI for visualizing tasks, dependencies, tests, and activity logs. The GUI provides a real-time, interactive view of your project state with a modern dark blue interface.

Features:

• Interactive task graph - Spring-physics based visualization of task dependencies
• Ready tasks view - Quick access to tasks ready to work on
• Test dashboard - Monitor test status and history
• Activity log - Track all changes and actions
• Live updates - WebSocket-based real-time synchronization

Building with GUI:

# Build with GUI feature
cargo build --release --features gui

# Or use just (includes GUI by default)
just install

# Or install with cargo
cargo install --path . --features gui

Running the GUI:

# Start on default port (3030)
bn gui

# Start on custom port
bn gui --port 8080

# Then open http://localhost:3030 in your browser

The GUI watches for changes to binnacle data and automatically updates all connected clients.

Configuration

Binnacle supports configuration via bn config set/get/list:

# Action logging (default: enabled)
bn config set action_log_enabled true
bn config set action_log_path ~/.local/share/binnacle/action.log
bn config set action_log_sanitize true

# View configuration
bn config get action_log_enabled
bn config list

Action Logging

All binnacle commands are automatically logged to a JSONL file with:

• Timestamp
• Command name and arguments
• Success/failure status
• Execution duration
• Current user

Config keys:

• action_log_enabled - Enable/disable logging (default: true)
• action_log_path - Log file path (default: ~/.local/share/binnacle/action.log)
• action_log_sanitize - Sanitize sensitive data and paths (default: true)

Sanitization automatically:

• Converts file paths to basenames
• Redacts passwords, tokens, and secrets
• Truncates long strings
• Summarizes large arrays

Require Commit for Closure

Enable enforcement that tasks must have at least one linked commit before being closed:

# Enable the requirement
bn config set require_commit_for_close true

# Now tasks require a linked commit to close
bn task close bn-xxxx  # Error: no commits linked
bn commit link abc1234 bn-xxxx
bn task close bn-xxxx  # Success

# Bypass with --force when needed (e.g., docs-only tasks)
bn task close bn-xxxx --force --reason "Documentation only"

Config key:

• require_commit_for_close - Require linked commits before closing tasks as done (default: false)

When enabled:

• bn task close and bn task update --status done check for linked commits
• Use --force to bypass the check for legitimate cases (config changes, documentation)
• cancelled status is exempt (no commit required)

Environment Variables

• BN_DATA_DIR - Override the base directory for binnacle data storage. By default, data is stored in ~/.local/share/binnacle/. When set, binnacle stores data in $BN_DATA_DIR/<repo-hash>/ instead. Useful for testing or isolating data between environments.

Status

Core functionality is complete (Phases 0-7). The project tracks its own development with binnacle.

What works:

• Task CRUD with priorities, tags, assignees
• Dependency graph with cycle detection
• Test nodes with regression detection
• Commit tracking
• Action logging with sanitization
• Work queue for agent task prioritization
• MCP server with 38+ tools
• Web GUI with live updates (behind gui feature flag)
• CI/CD via GitHub Actions

In progress:

• Alternative storage backends (orphan branch done, git notes planned)
• Sync for shared mode

Building

# Recommended: Install with GUI feature using just
just install

# Or build manually
cargo build --release --features gui

# Or without GUI
cargo build --release

The binary is bn (short for binnacle). The just install command builds with the GUI feature enabled and installs to ~/.local/bin.

Contributing

See CONTRIBUTING.md for development setup, code style guidelines, and how to submit pull requests.

License

MIT