UltiThink

Autonomous multi-agent kanban system built on Claude Code.

UltiThink spawns multiple Claude Code agents that autonomously pull tasks from a kanban backlog, execute them in isolated git worktrees, verify the results, and merge into main. You watch it work from a terminal-based kanban board. Requires a Claude Code Max or Pro subscription (no API tokens needed).

  Backlog       Planning      Executing     Verifying     Done
 +-----------+ +-----------+ +-----------+ +-----------+ +-----------+
 | #3 Add    | | #5 Auth   | | #1 Setup  | | #2 Config | | #4 Init   |
 | search    | | module    | | database  | | loader    | | project   |
 |           | |           | | [agent-1] | | [agent-2] | |           |
 +-----------+ +-----------+ +-----------+ +-----------+ +-----------+
 | #6 Add    |                                           | #7 Add    |
 | tests     |                                           | logging   |
 |           |                                           |           |
 +-----------+                                           +-----------+

Prerequisites

• Node.js 20+ -- check with node --version
• git -- for worktree isolation
• Claude Code CLI -- installed and authenticated (docs)
• Claude Code Max or Pro subscription -- UltiThink spawns Claude Code sessions; no separate API key or per-token cost

UltiThink uses the Claude Agent SDK to spawn headless Claude Code sessions. Your existing subscription covers all agent usage.

Quick Start

npm install -g ultithink
cd your-project
ultithink init
ultithink add --title "Add auth" --desc "JWT authentication middleware" --criteria "Login endpoint works" "Logout clears session"
ultithink run

The TUI board launches. Agents pull tasks, execute in worktrees, verify results, and merge to main.

You can use npx ultithink to try without installing, but global install is recommended -- UltiThink runs as a long-lived daemon process.

Walkthrough

Manual Task Flow

Initialize UltiThink in any git repository:

ultithink init

Add tasks to the backlog. Each task needs a title, description, and one or more success criteria:

ultithink add --title "Setup database" --desc "Configure PostgreSQL with connection pooling" --criteria "Database connects" "Migrations run"
ultithink add --title "Add auth" --desc "JWT authentication with login and logout" --criteria "Login returns token" "Logout clears session" --priority high
ultithink add --title "Add search" --desc "Full-text search endpoint" --criteria "Search returns results" "Empty query returns 400"

Start the autonomous agent loop:

ultithink run

The TUI board appears. Agents pull tasks from the backlog, execute each one in an isolated git worktree, then hand off to a verification agent that checks the work against your success criteria. Verified tasks are merged into main automatically.

Check the board state without launching the live TUI:

ultithink board

List tasks with their current status:

ultithink list

If a task fails, inspect it and retry:

ultithink status 2
ultithink status 2 --retry

Planning Flow

For larger features, let UltiThink decompose the work. Submit a feature description:

ultithink plan --title "User auth" --desc "Add JWT authentication with login, logout, and session management"

Start the daemon to kick off planning:

ultithink run

A planner agent researches your codebase, generates requirements, and decomposes the feature into atomic tasks with dependencies. When planning completes, review the result:

ultithink plan show 1

If the plan looks good, approve it to create tasks on the backlog:

ultithink plan approve 1

Run the agents again to execute the plan:

ultithink run

Tasks execute in waves -- independent tasks run in parallel, dependent tasks wait for their prerequisites to complete. The planner computes a dependency DAG so work proceeds in the right order.

To re-plan with additional context:

ultithink plan redo 1 --feedback "Split the auth module into smaller tasks"

List all plans:

ultithink plan list

Command Reference

ultithink init

ultithink init [--git-track | --no-git-track]

Initialize UltiThink in the current project. Creates the .ultithink/ directory with config and task storage. By default, .ultithink/ is tracked in git. Use --no-git-track to add it to .gitignore.

ultithink add

ultithink add --title <title> --desc <description> --criteria <items...> [--priority <high|medium|low>]

Create a new task on the backlog. All three flags are required. --criteria accepts multiple space-separated values. Priority defaults to medium.

ultithink add --title "Add auth" --desc "JWT auth middleware" --criteria "Login works" "Logout works"
ultithink add --title "Fix bug" --desc "Fix crash on empty input" --criteria "No crash" --priority high

ultithink list

ultithink list [--plan <id>]

List all tasks in a table showing ID, title, status, and priority. Use --plan to filter tasks belonging to a specific plan.

ultithink status

ultithink status <id> [--retry]

Show detailed information for a single task: title, status, priority, description, criteria, timestamps. Use --retry to re-queue a failed task back to the backlog.

ultithink status 3
ultithink status 3 --retry

ultithink run

ultithink run [--once]

Start the autonomous agent loop with a live TUI kanban board. Agents pull tasks from the backlog, execute in worktrees, verify results, and merge to main. The daemon runs until you press Ctrl+C (graceful shutdown) or q after completion.

Use --once to process the current backlog and exit when all tasks are done -- no continuous polling.

ultithink run
ultithink run --once

ultithink board

ultithink board

Show a static snapshot of the kanban board. Prints the current state of all tasks across columns and exits. No live updates -- use ultithink run for the live TUI.

ultithink plan

ultithink plan --title <title> --desc <description>

Submit a feature for structured planning. A planner agent will research your codebase, generate requirements, and decompose the feature into tasks with dependencies. Both --title and --desc are required.

ultithink plan --title "User auth" --desc "Add JWT authentication with login and logout"

ultithink plan approve

ultithink plan approve <id>

Approve a completed plan and create its tasks on the backlog. The plan must be in ready status. Tasks are created with dependency relationships preserved from the plan.

ultithink plan show

ultithink plan show <id>

Display plan details including title, status, stage, and the generated research, requirements, and task breakdown.

ultithink plan list

ultithink plan list

List all plans in a table with ID, title, status, stage, and creation date.

ultithink plan redo

ultithink plan redo <id> --feedback <text>

Re-run planning for an existing plan with additional feedback. The plan resets to the research stage and the planner agent incorporates your feedback. --feedback is required.

ultithink merge

ultithink merge

Merge all verified task branches into main. Uses dry-run merge to detect conflicts before committing. Reports the count of merged, conflicted, and failed tasks. This runs automatically during ultithink run but can also be triggered manually.

ultithink resolve

ultithink resolve <taskId>

Mark a conflicted task as ready for re-merge. After manually resolving conflicts in the task's worktree (at .ultithink/worktrees/task-{id}/), use this command to clear the conflict state so the next merge batch picks it up.

ultithink cleanup

ultithink cleanup [--failed] [--task <id>]

Remove worktrees for completed and failed tasks. By default, targets both done and failed tasks. Use --failed to clean up only failed task worktrees. Use --task <id> to clean up a specific task's worktree.

Architecture Overview

Agent Spawning

UltiThink uses the Claude Agent SDK to spawn headless Claude Code sessions as autonomous workers. Each agent receives a task prompt with the title, description, and success criteria. Agents share pool slots with configurable concurrency (default: 2 concurrent agents).

Worktree Isolation

Each agent gets its own git worktree at .ultithink/worktrees/task-{id}/ with a dedicated branch ultithink/task-{id}. Agents work in parallel without file conflicts since each worktree is a fully independent working copy. Worktrees are cleaned up after merge.

Verification Pipeline

After an executor agent completes a task, a separate verification agent reviews the work against the task's success criteria. Verification agents are restricted to read-only tools (Read, Glob, Grep, Bash) so they cannot modify the code they're reviewing. Failed verification returns the task for re-execution.

Wave-Based Scheduling

When plans decompose features into tasks with dependencies, UltiThink computes a dependency DAG and executes tasks in waves. Independent tasks within a wave run in parallel. Dependent tasks wait for their prerequisites to reach verified status before starting.

Merge Pipeline

Verified tasks accumulate and are batch-merged into main when the agent pool is idle. The system uses dry-run merge (git merge --no-commit --no-ff) to detect conflicts before committing. Failed merges are surfaced for manual resolution via ultithink resolve.

Planning Pipeline

The ultithink plan command spawns a planner agent that follows a three-stage pipeline: research the codebase, generate requirements, then decompose into atomic tasks with dependencies and wave assignments. Plans can be reviewed with ultithink plan show and approved with ultithink plan approve before tasks are created.

License

MIT -- see LICENSE for details.