buckley

module

v0.0.0-...-cb3f5c8 Latest Latest Go to latest Published: Jan 6, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/odvcencio/buckley

Links

Open Source Insights

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 — /execute runs 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

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: anthropic/claude-sonnet-4-20250514
  execution: moonshotai/kimi-k2
  review: anthropic/claude-sonnet-4-20250514

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-thinking \
    -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

License

MIT. See LICENSE.

Named after a very good dog.

Directories ¶

Path	Synopsis
cmd
buckley command
pkg
acp Package acp implements the Agent Client Protocol (ACP) for editor integration.	Package acp implements the Agent Client Protocol (ACP) for editor integration.
acp/lsp
acp/observability
acp/proto
acp/server
agent Package agent provides the agent runtime for multi-agent orchestration.	Package agent provides the agent runtime for multi-agent orchestration.
agentserver
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.
artifact
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.
config
containerexec
containers
context
conversation
coordination/capabilities
coordination/coordinator Package coordinator provides Buckley-internal coordination primitives (not ACP).	Package coordinator provides Buckley-internal coordination primitives (not ACP).
coordination/discovery
coordination/events Package events provides Buckley-internal coordination event storage.	Package events provides Buckley-internal coordination event storage.
coordination/p2p
coordination/pubsub
coordination/reliability
coordination/security
cost
dependency
diff
docs
dream
embeddings
encoding/toon
envdetect
errors
experiment
github
giturl
gitwatcher
headless Package headless provides API-driven conversation sessions without a TUI.	Package headless provides API-driven conversation sessions without a TUI.
hunt
image Package image provides image input handling for AI assistants.	Package image provides image input handling for AI assistants.
index
ipc
ipc/command
ipc/proto
ipc/proto/ipcpbconnect
ipc/push Package push provides Web Push notification functionality for the Buckley PWA.	Package push provides Web Push notification functionality for the Buckley PWA.
logging
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.
memory
mission
model
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.
oneshot/pr
oneshot/review
oneshot/rlm
orchestrator
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.
paths
performance
personality
policy
prompts
push Package push implements Web Push notification delivery.	Package push implements Web Push notification delivery.
regression
rlm
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.
scaffold
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.
security
session
setup
skill
storage
telemetry
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.
tool
tool/builtin
tool/external
tool/runtime
tools Package tools provides structured tool definitions for LLM tool-use.	Package tools provides structured tool definitions for LLM tool-use.
touch
transparency Package transparency provides full visibility into LLM invocations.	Package transparency provides full visibility into LLM invocations.
ui/backend Package backend defines the terminal backend interface for the TUI.	Package backend defines the terminal backend interface for the TUI.
ui/backend/sim Package sim provides a simulation backend for testing.	Package sim provides a simulation backend for testing.
ui/backend/tcell Package tcell provides a Backend implementation using tcell.	Package tcell provides a Backend implementation using tcell.
ui/compositor Package compositor bridge provides integration with Bubbletea's rendering model.	Package compositor bridge provides integration with Bubbletea's rendering model.
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.
ui/markdown Package markdown provides markdown parsing and rendering for Buckley's TUI.	Package markdown provides markdown parsing and rendering for Buckley's TUI.
ui/runtime Package runtime provides the widget runtime for Buckley's TUI.	Package runtime provides the widget runtime for Buckley's TUI.
ui/scrollback Package scrollback provides app-owned conversation history with selection and search.	Package scrollback provides app-owned conversation history with selection and search.
ui/shellmode Package shellmode provides inline shell command execution with ! and $ prefixes.	Package shellmode provides inline shell command execution with ! and $ prefixes.
ui/terminal Package terminal provides terminal event types used throughout the UI.	Package terminal provides terminal event types used throughout the UI.
ui/theme Package theme provides a unified visual design system for Buckley's TUI.	Package theme provides a unified visual design system for Buckley's TUI.
ui/tui Package tui provides the integrated terminal user interface for Buckley.	Package tui provides the integrated terminal user interface for Buckley.
ui/viewmodel
ui/widgets Package widgets provides concrete widget implementations for Buckley's TUI.	Package widgets provides concrete widget implementations for Buckley's TUI.
utils
worktree

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL