Orchestrate Claude Code to process issues and create PRs. Includes a TUI for interactive management and CLI for scripting.
CO is designed to manage an army of Claude agents, turning your issue tracker into a PR factory.
- Create or import issues - Define work in your issue tracker (beads), or import from Linear
- Plan the implementation - Use Claude Code interactively to break down complex issues into actionable tasks
- Execute with a Work - Create a work unit that represents a git worktree and feature branch
- Automatic execution - CO orchestrates Claude to solve all issues, commit changes, and push continuously
- Code review - Claude automatically reviews its own work, creating fix issues for any problems found
- PR creation - Once implementation and review pass, Claude creates a comprehensive PR
- Handle feedback - CI failures and review comments automatically become new issues, which can be planned or added to the existing work
- Merge and cleanup - After approval, merge the PR and destroy the work
- Autonomous execution - Agents work independently, committing and pushing after each completed issue
- Continuous progress - Work is never lost; every bead completion is immediately saved
- Feedback loops - CI failures and review comments flow back as actionable issues
- Human oversight - You control when to create work, when to merge, and can intervene at any point
- Isolation - Each work unit has its own worktree, preventing conflicts between parallel efforts
CO currently supports Claude Code as its agent backend. The architecture is designed to be agent-agnostic, and other agentic coding tools could be supported in the future.
The following CLI tools are required but are automatically installed by mise when you run mise install:
| Tool | Purpose |
|---|---|
bd |
Beads issue tracking |
claude |
Claude Code CLI |
gh |
GitHub CLI |
zellij |
Terminal multiplexer |
You only need git (usually pre-installed) and mise itself:
curl https://mise.run | shAfter mise installs the tools, you must install the beads skill for Claude Code:
claude /plugin marketplace add steveyegge/beads
claude /plugin install beadsThis enables Claude to interact with the beads issue tracker.
Zellij uses a nerd font for icons. Install one and configure your terminal to use it:
macOS:
brew install font-hack-nerd-fontThen update your terminal preferences to use "Hack Nerd Font" or "Hack Nerd Font Mono".
Linux (Debian/Ubuntu):
mkdir -p ~/.local/share/fonts
cd ~/.local/share/fonts
curl -fLO https://github.com/ryanoasis/nerd-fonts/releases/latest/download/Hack.zip
unzip Hack.zip -d Hack
rm Hack.zip
fc-cache -fvThen configure your terminal emulator to use "Hack Nerd Font" or "Hack Nerd Font Mono".
Linux (Arch):
pacman -S ttf-hack-nerdcurl -fsSL https://raw.githubusercontent.com/newhook/co/main/scripts/install.sh | bashThis downloads the latest release for your platform. Alternatively:
# With Go 1.25+
go install github.com/newhook/co@latest# From a GitHub repository
co proj create ~/myproject https://github.com/user/repo
# From a local repository
co proj create ~/myproject ~/path/to/repo
cd ~/myprojectCO provides two ways to interact with your project:
The interactive terminal UI provides a lazygit-style interface:
co tuiFeatures:
- Three-panel drill-down: Beads → Works → Tasks
- Create/destroy works, run tasks
- Bead filtering, search, multi-select
- Press
?for keyboard shortcuts
Use individual commands for scripting or when you prefer the command line:
# Create a work unit from a bead
co work create bead-1
# Navigate to the work directory
cd w-abc
# Execute tasks
co run
# Or use full automation
co work create bead-1 --autoThese commands must be used via CLI (not available in TUI):
| Command | Description |
|---|---|
co proj create <dir> <repo> |
Create a new project (local path or GitHub URL) |
co proj destroy [--force] |
Remove project and all worktrees |
co proj status |
Show project info, worktrees, and task status |
<project-dir>/
├── .co/
│ ├── config.toml # Project configuration
│ └── tracking.db # SQLite coordination database
├── main/ # Symlink to local repo OR clone from GitHub
│ └── .beads/ # Beads issue tracker
├── w-8xa/ # Work unit directory
│ └── tree/ # Git worktree for feature branch
└── ...
CO uses Beads, a distributed git-backed issue tracker designed specifically for AI coding agents. Traditional markdown plans lack the sophistication needed for complex, multi-step workflows. Beads provides:
- Dependency tracking - Agents understand task relationships and what's ready to work on
- Git-native persistence - Tasks stored as JSONL in
.beads/, versioned alongside code - Collision-free IDs - Hash-based IDs eliminate merge conflicts in multi-branch scenarios
- Semantic compaction - Completed tasks are summarized to conserve AI context windows
You rarely need to use beads directly. Claude Code (with the beads skill) and the TUI handle all issue management. The bd CLI is available if you need it, but most users interact with beads through co tui or let Claude manage issues automatically.
- Work: A feature branch with its own worktree, groups related tasks (ID:
w-8xa) - Tasks: Units of Claude execution within a work (ID:
w-8xa.1,w-8xa.2) - Beads: Individual issues from the beads tracker (ID:
ac-pjw)
Use --auto for a fully automated workflow:
co work create bead-1 bead-2 --autoThis mode:
- Creates work unit and tasks from beads
- Executes all implementation tasks
- Runs review/fix loop until code is clean
- Creates PR automatically
- Returns PR URL when complete
- CLI Reference - Complete command documentation
- Configuration - Project configuration options
mise install && lefthook installgo test ./...go build -o co .All commands must be run from within a project:
co proj create ~/myproject ~/path/to/repo
cd ~/myprojectThese tools are installed by mise:
mise installIf mise isn't installed, see mise.jdx.dev.
Authenticate with GitHub:
gh auth loginCreate work items in your project's main repo:
cd ~/myproject/main
bd create --title "Your task" --type task
bd ready # View available beadsMIT
