The task orchestrator for AI coding agents.
Run Claude Code, Codex, and your own CLIs across local folders, Git repositories, and isolated worktrees, with claims, retries, live activity, and optional review. Local by default — no account required.
| Surface | Install | Use case |
|---|---|---|
CLI (backlog) |
npm i -g backlog |
Headless, scriptable, the binary you put in CI |
| Desktop | backlog.so/desktop | Native kanban + run inspector + agent fleet (macOS · Linux · Windows) |
SDK (@osmove/backlog-sdk) |
npm i @osmove/backlog-sdk |
Embed the orchestrator in your own tool, TypeScript-first |
CLI, Desktop, and SDK are all Apache-2.0, free forever. Backlog Cloud (managed hosted backend) is in private development and only adds features that genuinely need infrastructure we run — SMTP, hosted auth & SSO, multi-tenant collaboration, hosted run executors, retention beyond local disk, audit log export. See backlog.so/cloud.
Backlog is the engine that sits between your backlog and your agents.
It ingests work from sources you already use (Markdown, CSV, Jira, GitHub Issues — more on the roadmap), keeps ideas separate from executable tasks, optionally decomposes larger tasks into scoped subtasks, and runs each task with the selected agent/model.
Git-backed work can run in an isolated worktree under a file-scope claim so multiple agents can work in parallel without stepping on each other. Normal folders work too: Backlog edits them directly and hides Git-only commit, stash, discard, hook, and sync controls.
When a run finishes, Backlog either completes it automatically or moves it to review, depending on the project's review setting.
Backlog runs end-to-end on your machine by default. Remote sources, remote repositories, remote sandboxes, remote executors, and deploy targets are part of the multi-target roadmap.
| Layer | What it does |
|---|---|
| Sources | Ingest tasks from Markdown, CSV, Jira (and more — see roadmap) |
| Projects | Group one or many repositories under a single banner; tasks can be filtered per-project |
| Backlog | Early ideas and pending requests before they are ready to become tasks |
| Workspaces | Local folders, local Git repositories, or remote Git repositories where agents work |
| Git | Changes, History, Branches, Worktrees, Hooks, and Sync when a workspace has Git metadata |
| Tasks | High-level units of intent imported from sources or created on the board |
| Subtasks | Executable units scoped to one workspace and split out from tasks |
| Claims | Lock file/path scopes so concurrent runs cannot conflict |
| Worktrees | Git runs can execute in isolated worktrees; normal folders run directly |
| Scheduler | Picks eligible tasks, assigns agents, respects claim conflicts |
| Orchestrator | Persistent dispatcher controlled by Play/Stop in the UI and start/pause/stop in the CLI |
| Runs | Track agent execution with owner, activity, token usage, summary, changed files, ETA, and live progress |
| Review | Optional In Review flow for approving, requesting changes, or discarding a run |
| Agents | Per-agent permissions, sandbox mode, risk level, repository restrictions |
npm install -g backlog
# Single-folder or single-repository project: drop a .backlog/ inside it.
cd ~/Dev/my-repository
backlog init --name my-project
# Multi-workspace project: keep project state at ~/.backlog/<slug>/ instead so it
# is not tied to any one folder or repository.
cd ~/Dev/my-multi-repository-parent
backlog init --user-level --name my-project
backlog doctorCreate a task, split it into subtasks, and run the scheduler:
backlog task add --title "Build the scheduler"
backlog task split task_001 --repository backlog \
--scope backlog=packages/core/src/**
backlog subtask add \
--task task_001 \
--title "Implement scheduler" \
--repository backlog \
--preferred-agent manual-default \
--require-capability edit_code
backlog schedule simulate
backlog schedule explain --task task_001
backlog schedule run --approveAdd a source and sync tasks in:
backlog sources add markdown --id notes --path backlog.md
backlog sources sync
backlog task import
backlog sources conflicts
backlog sources resolve --task task_001 --use localYou have two options for the same kanban experience — same engine, same
Svelte UI, same @backlog/server:
# Option A — CLI: smart shortcut that opens the kanban in your browser.
# - If a server is already running, just opens the URL.
# - Otherwise spawns `backlog serve` and blocks until Ctrl+C.
# - `backlog` with no subcommand is the same shortcut.
# - From inside a folder, it opens that folder as the selected workspace.
# Git is optional; normal folders can run agents directly.
backlog board# Same engine, longer form — keeps the foreground process attached so
# you can read agent stdout. Use this when scripting / running under a
# process supervisor.
backlog serve# Option B — Desktop: native window, no browser tab. macOS, Linux,
# and Windows all ship today via electron-builder. macOS is signed +
# notarised; Linux AppImage / .deb / .rpm runs unsigned (normal);
# Windows installer is unsigned for now (SmartScreen warns once,
# install completes — EV cert in flight).
# Download: https://backlog.so/desktopBoth open at http://127.0.0.1:7878 (Desktop picks a random port).
The topbar and sidebars carry:
- Project selector + project settings
- Selected model/agent next to the project name
- Play / Stop run controls: grey when configuration is incomplete, white when ready but no task is available, blue when a task can start
- Backlog list for ideas and pending requests that are not tasks yet
- Git view with Changes, History, branch/worktree controls, hooks status, and sync
- Workspaces management for local folders, local Git repositories, and cloned Git URLs
- Agents view with per-agent permissions and runtime restrictions
- Runs view for execution history, ownership, protected paths, activity, and token usage
- Instructions view for
AGENTS.md,CLAUDE.md, and similar coding guidance files - Hooks view for installed/available hook versions and explicit install/update/uninstall actions
- Usage in the profile menu, with token/cost charts by period and model
- + Task / + Claim quick-create dialogs
- Total ETA pill showing remaining work across the visible columns
Cards drag between Backlog / À faire / En cours / In Review / Done when
those columns are enabled, and within movable columns to reorder by priority
(sparse priority_score rewrite). In Review is controlled by the run flow,
so review cards are not manually draggable. Each task shows a progress bar
(agent-reported > elapsed/estimate > status fallback) with an ETA that ticks
client-side while work is active. The + Claim modal creates a file-scope
claim with a per-tier retry-after hint on collision, and AI split can ask the
selected planner model to divide large work across up to 99 sub-agents.
The board is served from the same backlog binary — no extra install,
no docker. Kill with Ctrl+C.
backlog serve --port 8080 --project ~/Dev/myproject --no-open
backlog serve --host 0.0.0.0 # expose to LAN (no auth — be careful)Live updates use SSE, so the UI reflects YAML edits, claim creation, orchestrator state, project changes, and run status changes within ~200ms.
backlog init Initialize a project
backlog doctor [--repository <id>] [--json] Inspect project health
backlog status [--repository <id>] Project overview
backlog update Update the global CLI install
backlog Alias of `backlog board`
backlog board [--url <url>] Open the kanban (smart wrapper around serve)
backlog serve [--port 7878] [--host 127.0.0.1]
[--project <path>] [--no-open]
[--open-url <url>] Launch the kanban board
backlog project add|list|remove|path|migrate
|migrate-rollback|export|import Manage projects (groups of repositories)
backlog repositories
list|show|add|update|remove Manage tracked repositories
[--url <git-url>] [--clone-into] ...or clone from GitHub / GitLab / etc.
backlog task add|list|show|move|update|remove
|plan|split|import|estimate Manage tasks
backlog subtask add|list|show|move|update|remove
|block|unblock|plan|estimate
|progress Manage subtasks
backlog claim start|check|finish|list|gc Manage file-scope claims
[--duration <s>] [--agent <id>]
backlog hooks status|install|pause|resume|disable
|stop|enable|uninstall [--all|--repository <id>]
Manage git hooks
backlog orchestrator start|pause|stop|status|config Persistent run dispatcher
[--max-agents N] [--auto] [--project <slug>]
backlog schedule simulate|explain|run Schedule and run agents
backlog runs list|show|gc|interrupt|resume
|review|approve|request-changes
|complete|fail|handoff Manage runs
backlog agents list|show|enable|disable|update
|validate|health Manage agent providers
backlog sources add|list|enable|disable|update|remove
|validate|sync|push|conflicts|resolve
Manage source connectors
backlog release snapshot [--repository <id>] [--include-disabled] [--output <path>]
Export a release report
backlog worktree list|gc Inspect tracked worktrees
# Start a multi-repository project, then add repositories by local path or Git URL.
backlog init --name "Shipping" --user-level
backlog repositories add --path /Users/me/Dev/web # local
backlog repositories add --url https://github.com/me/api.git # remote git, cloned to <project>/repositories/api
# Create a task scoped to the project, split it, and let the orchestrator run.
backlog task add --title "Stripe integration" --priority P1
backlog task split task_001 --repository web --repository api
backlog orchestrator start --autoMost list commands support practical filters, for example:
backlog repositories list --enabled true
backlog worktree list --repository backlog
backlog task list --repository backlog --status blocked
backlog runs list --review --agent codex-default
backlog sources list --enabled trueBacklog stores project state in one of two layouts. backlog init defaults
to in_repo (the same directory you ran it in); pass --user-level to put
project state under your home folder instead. Both layouts hold the same set
of files; only the path on disk differs.
in_repo (default — best for a single-repository project)
<project root>/.backlog/
user_level (best for multi-repository projects so project state lives outside any one repository)
~/.backlog/<slug>/
<slug> is the lowercased, hyphenated form of the project name; pick a name
that doesn't collide with any other registered user-level project. The user
registry itself lives at ~/.backlog/projects.json on every platform.
Run into the hook crashing or the project not being found? docs/TROUBLESHOOTING.md covers the five that come up most often.
Either way, the layout inside the project state dir is the same:
config.toml # project + repositories + autonomy_mode + claims TTL
# (project_location = "in_repo" | "user_level")
tasks.yaml # tasks (incl. project_id, rank, estimate)
subtasks.yaml # executable units split out from tasks
orchestrator.json # persistent dispatcher state
sources.yaml
agents.yaml # provider, sandbox, allowed_repos, allowed_risk, ...
claims/ # active and archived
runs/ # active and archived (incl. events.ndjson per run)
bin/backlog # local shim invoked by the pre-commit hook
worktrees/ # tracked run worktrees
You can edit YAML by hand, but backlog repositories, backlog project,
backlog task, backlog orchestrator, backlog agents,
and backlog sources are designed to keep state consistent without manual
edits. Use backlog project migrate <id> --to user-level (or --to in-repo --into <repository-id>) to switch an existing project between layouts.
Backlog ships with three executor providers:
claude— runsclaude -pinside the run worktreecodex— runscodex execinside the run worktreecustom— runs an arbitrary shell command inside the run worktree
backlog init seeds disabled claude-default and codex-default agents.
Enable, retarget, or override their executable with:
backlog agents enable codex-default
backlog agents update codex-default --model gpt-5
backlog agents update codex-default --command /usr/local/bin/codexBy default, claude and codex runs complete tasks automatically when the
project does not use an In Review column. When manual review is enabled, a
successful run lands in awaiting_review; claims are released, but the run
and worktree stay available for inspection.
backlog runs list --review # see the review queue
backlog runs approve <run-id> # accept a reviewed run
backlog runs request-changes <run-id> --reason "..."
# archive run, return task to plannedBoth claude and codex runs attach summary, executor log, and the list of
changed files detected in the worktree.
backlog sources push --allpushes every source-linked task that supports outbound sync.backlog sources pushrefuses to push an item while it has pending conflicts, unless you pass--allow-conflicts.backlog sources resolve --task <id> --use local|externalresolves every pending conflict for that task in one step.
backlog claim gcarchives expired active claims.backlog runs gc --allpurges archived run directories.backlog worktree listshows worktrees Backlog knows about.backlog worktree gc --dry-runpreviews cleanup before deleting anything.
Hooks are opt-in: Backlog never installs or updates them without an explicit
user action. In multi-repository projects,
backlog hooks status|install|uninstall --all lets you audit or roll out the
managed pre-commit hook across every configured Git repository in one pass.
You can also target one configured repository explicitly with
--repository <id>.
backlog hooks status reports whether the hook and the local shim are up
to date. If not, it prints the exact backlog hooks install ... command to
run. backlog hooks disable (alias: stop) turns the hook gate off for the
project until backlog hooks resume (alias: enable).
backlog release snapshot reports dirty repositories and per-repository run counts. It
supports:
--repository <id>to focus on one repository--include-disabledto include disabled repositories in the snapshot--output <path>to write the snapshot to a file for export
| Package | Purpose | License |
|---|---|---|
backlog (packages/cli) |
The CLI binary published on npm | Apache-2.0 |
@backlog/core |
Scheduler, run launcher, task services | Apache-2.0 |
@backlog/claims |
Claim store + overlap detection | Apache-2.0 |
@backlog/schemas |
Zod schemas for the project state | Apache-2.0 |
@backlog/server |
Local Hono server + REST/SSE API behind backlog serve |
BUSL-1.1 |
@backlog/board-ui |
Svelte 5 kanban frontend | Apache-2.0 |
@backlog/git, @backlog/hooks, @backlog/config, @backlog/connectors |
Plumbing | Apache-2.0 |
End users only ever install backlog — every project package is
inlined into the published CLI tarball at build time. The split exists
for development clarity and per-package licensing.
See docs/ROADMAP.md for the multi-target plan covering remote sources, remote repositories, remote sandboxes, remote executors, and deploy targets.
Contributor and agent docs are split by purpose:
- CONTRIBUTING.md for the human contribution path.
- AGENTS.md for repository-specific instructions Codex and other agents must follow.
- docs/DEVELOPMENT.md for architecture, naming, local setup, UI conventions, Git behavior, and Cloud boundaries.
- RELEASING.md for version bumps, checks, tags, publishing, Desktop updates, and deployment verification.
pnpm install
pnpm typecheck
pnpm --filter @backlog/board-ui typecheck
pnpm test
pnpm --filter "backlog..." build
pnpm --filter @backlog/desktop build
pnpm --filter backlog pack:checkIssues, PRs, and design discussions welcome.
- Backlog Desktop — native kanban for the same orchestrator engine
@osmove/backlog-sdk— TypeScript client generated from the OpenAPI 3.0.3 spec- Backlog Cloud — managed hosted backend (private development, waitlist)
lint— universal linter CLI with AI-powered code review