README
¶
Buckley
AI dev assistant that remembers what you're doing.
Sessions survive crashes. Four trust levels. Loop detection. Multi-model support.
Quick Start
go install github.com/odvcencio/buckley/cmd/buckley@latest
export OPENROUTER_API_KEY="your-key"
buckley
No Docker. No database setup. Just Go and an API key.
Three Ways to Use It
| Mode | Command | Use Case |
|---|---|---|
| TUI | buckley |
Interactive terminal with streaming and approvals |
| Web | buckley serve --browser |
Browser-based Mission Control |
| API | buckley api |
Headless for CI/CD integration |
The Workflow
- Plan —
/plan "add user auth"breaks work into tasks - Execute —
/executeruns tasks with self-healing retries - Review — AI reviews changes before you merge
The orchestrator coordinates builder, review, and research agents. Tasks persist to SQLite. Crash? Resume where you left off.
One-Shot Commands
buckley commit # AI-generated commit message from staged changes
buckley pr # AI-generated PR description
buckley review # Code review current changes
buckley hunt # Scan codebase for improvements
buckley dream # Architectural analysis
buckley image # Generate images via AI models
Skills
Skills are workflow playbooks. Buckley ships with 8:
- test-driven-development — Write tests before code
- systematic-debugging — Reproduce, isolate, fix, verify
- code-review — Review checklist
- planning — Break work into tasks
Skills activate by phase. Create your own in .buckley/skills/.
Tools
46+ built-in tools:
| Category | Tools |
|---|---|
| Files | read_file, edit_file, create_file |
| Search | search_text, semantic_search, find_files |
| Shell | run_shell (with timeout and output limits) |
| Git | git_status, git_diff, git_commit, etc. |
| Quality | run_tests, lint |
Add custom tools via YAML plugin manifests.
Trust Levels
Four modes from manual to full auto:
| Level | Behavior |
|---|---|
| Conservative | Approve everything |
| Balanced | Approve file changes and shell |
| Standard | Auto-approve safe operations |
| Autonomous | Full auto (careful) |
Configure per-project in .buckley/config.yaml.
Multi-Model
Different models for different jobs:
models:
planning: moonshotai/kimi-k2.5
execution: moonshotai/kimi-k2.5
review: moonshotai/kimi-k2.5
Supports OpenRouter (100+ models), Anthropic, OpenAI, Google, Ollama.
Experiments
Compare models on the same task:
buckley experiment run "add-dark-mode" \
-m moonshotai/kimi-k2.5 \
-m anthropic/claude-sonnet-4.5 \
-p "Add dark mode toggle"
Each model runs in an isolated git worktree. Results compared automatically.
Configuration
Hierarchical config:
~/.buckley/config.yaml (user defaults)
./.buckley/config.yaml (project overrides)
Environment variables (highest priority)
Minimal setup:
providers:
openrouter:
api_key: ${OPENROUTER_API_KEY}
Notifications
Get pinged when Buckley needs you:
notify:
telegram:
bot_token: ${TELEGRAM_BOT_TOKEN}
chat_id: ${TELEGRAM_CHAT_ID}
Supports Telegram, Slack, NATS.
Documentation
| Page | Description |
|---|---|
| CLI Reference | Commands and flags |
| Configuration | All config options |
| Skills | Workflow guidance system |
| Tools | Built-in tools reference |
| Orchestration | Multi-agent coordination |
Full docs at buckley.draco.quest
Requirements
- Go 1.25.1+
- API key (OpenRouter recommended)
- Git (for worktree features)
- Optional: Docker, Ollama
Development
./scripts/test.sh # Run tests
./scripts/test.sh -race # With race detector
go test ./pkg/orchestrator # Specific package
Self-Healing E2E Tests
Buckley includes an AI-powered E2E testing framework that adapts to UI changes:
# Terminal 1: Start Buckley with agent socket
./buckley --agent-socket unix:/tmp/buckley.sock
# Terminal 2: Run self-healing tests
make agent-test-smoke # Run smoke test
make agent-test-all # Run all scenarios
make agent-test-list # List available scenarios
Unlike traditional E2E tests that break when UI changes, these tests use semantic matching to find widgets by intent rather than brittle selectors. See scripts/agent-tests/ for implementation details.
License
MIT. See LICENSE.
Named after a very good dog.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
buckley
command
|
|
|
pkg
|
|
|
acp
Package acp implements the Zed Agent Communication Protocol (ACP) for editor integration.
|
Package acp implements the Zed Agent Communication Protocol (ACP) for editor integration. |
|
agent
Package agent provides the agent runtime for multi-agent orchestration.
|
Package agent provides the agent runtime for multi-agent orchestration. |
|
api
Package api provides a REST API server for headless Buckley access.
|
Package api provides a REST API server for headless Buckley access. |
|
approval
Package approval provides tiered permission control for agent operations.
|
Package approval provides tiered permission control for agent operations. |
|
buckley/console
Package console provides styled terminal output using the fur library.
|
Package console provides styled terminal output using the fur library. |
|
buckley/ui/filepicker
Package filepicker provides fuzzy file search with @ trigger for inline file selection.
|
Package filepicker provides fuzzy file search with @ trigger for inline file selection. |
|
buckley/ui/scrollback
Package scrollback provides app-owned conversation history with selection and search.
|
Package scrollback provides app-owned conversation history with selection and search. |
|
buckley/ui/shellmode
Package shellmode provides inline shell command execution with ! and $ prefixes.
|
Package shellmode provides inline shell command execution with ! and $ prefixes. |
|
buckley/ui/tui
Package tui provides the integrated terminal user interface for Buckley.
|
Package tui provides the integrated terminal user interface for Buckley. |
|
bus
Package bus provides a message bus abstraction for agent communication.
|
Package bus provides a message bus abstraction for agent communication. |
|
checkpoint
Package checkpoint provides session state saving and restoration.
|
Package checkpoint provides session state saving and restoration. |
|
coordination/coordinator
Package coordinator provides Buckley-internal coordination primitives (not ACP).
|
Package coordinator provides Buckley-internal coordination primitives (not ACP). |
|
coordination/events
Package events provides Buckley-internal coordination event storage.
|
Package events provides Buckley-internal coordination event storage. |
|
diagnostics
Package diagnostics collects backend telemetry for debugging.
|
Package diagnostics collects backend telemetry for debugging. |
|
execution
Package execution provides execution strategies for processing user requests.
|
Package execution provides execution strategies for processing user requests. |
|
headless
Package headless provides API-driven conversation sessions without a TUI.
|
Package headless provides API-driven conversation sessions without a TUI. |
|
image
Package image provides image input handling for AI assistants.
|
Package image provides image input handling for AI assistants. |
|
ipc/push
Package push provides Web Push notification functionality for the Buckley PWA.
|
Package push provides Web Push notification functionality for the Buckley PWA. |
|
mcp
Package mcp implements the Model Context Protocol client for connecting to external tool servers.
|
Package mcp implements the Model Context Protocol client for connecting to external tool servers. |
|
notify
Package notify provides async notifications for human-in-the-loop workflows.
|
Package notify provides async notifications for human-in-the-loop workflows. |
|
oneshot
Package oneshot provides the framework for one-shot CLI commands.
|
Package oneshot provides the framework for one-shot CLI commands. |
|
oneshot/commit
Package commit implements the generate_commit tool for buckley commit.
|
Package commit implements the generate_commit tool for buckley commit. |
|
oneshot/plugin
Package plugin provides YAML-based one-shot command definitions.
|
Package plugin provides YAML-based one-shot command definitions. |
|
orchestrator/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
parallel
Package parallel provides parallel agent execution using git worktrees.
|
Package parallel provides parallel agent execution using git worktrees. |
|
pool
Package pool provides memory pooling utilities to reduce GC pressure in high-throughput paths.
|
Package pool provides memory pooling utilities to reduce GC pressure in high-throughput paths. |
|
push
Package push implements Web Push notification delivery.
|
Package push implements Web Push notification delivery. |
|
ralph
pkg/ralph/backend.go
|
pkg/ralph/backend.go |
|
rlm/runner
Package runner provides plan execution using the RLM runtime.
|
Package runner provides plan execution using the RLM runtime. |
|
sandbox
Package sandbox provides sandboxed command execution for security.
|
Package sandbox provides sandboxed command execution for security. |
|
sdk
Package sdk exposes a stable, embeddable interface for driving Buckley's orchestrator programmatically.
|
Package sdk exposes a stable, embeddable interface for driving Buckley's orchestrator programmatically. |
|
sdk/grpc
Package grpcsdk hosts the lightweight gRPC bridge for Buckley's SDK.
|
Package grpcsdk hosts the lightweight gRPC bridge for Buckley's SDK. |
|
terminal
Package terminal provides Claude Code-style terminal output with rich markdown rendering, syntax highlighting, and styled output.
|
Package terminal provides Claude Code-style terminal output with rich markdown rendering, syntax highlighting, and styled output. |
|
thinking
Package thinking provides extended reasoning mode detection and configuration.
|
Package thinking provides extended reasoning mode detection and configuration. |
|
tools
Package tools provides structured tool definitions for LLM tool-use.
|
Package tools provides structured tool definitions for LLM tool-use. |
|
transparency
Package transparency provides full visibility into LLM invocations.
|
Package transparency provides full visibility into LLM invocations. |
Click to show internal directories.
Click to hide internal directories.