Spartito

Spartito runs Claude Code and Codex agents headless and in parallel, each in its own git worktree and branch. You steer them through one orchestrator agent (shown as Maestro) from a web dashboard or the command line, instead of managing many terminal sessions by hand. It is for developers who already use Claude Code or Codex and want several agents working on their repositories at once.

you ── orchestrator (Maestro)
        └─ project ── project lead (in the project's main checkout)
                        ├─ worker    (own git worktree, branch orch/<agent-id>)
                        ├─ reviewer  (reads the worker's worktree after it finishes)
                        └─ ...

The command is spartito; the Python package is orchestrator. The internal names stay as they were: the orch MCP server and its tools, the ORCH_* variables, orch.db and the agents' orch/ branches.

Features

• One conversation with an orchestrator agent that briefs a project lead per project; leads start and coordinate their own agents.
• Agents run headless (claude -p, codex exec) in parallel, each in its own git worktree and branch, or in a worktree shared with another agent (review, test, fix).
• Packaged roles: orchestrator, lead, planner, worker, reviewer, tester; custom roles are Markdown files.
• Results travel up automatically: a parent is woken with its agents' answers when they are done; tasks can depend on each other and embed another agent's answer.
• Web dashboard: conversations, tool calls, queued messages, model and effort per agent, context size, tokens and cost.
• Model and effort per tier (orchestrator, lead, worker), per provider, globally or per project; per-agent overrides.
• Persistent task board per project, and a list of decisions that wait for you.
• Automatic compaction of long conversations, automatic archiving of finished agents, keeping the machine awake while agents work, desktop notifications.
• The dashboard as a desktop application: a background service, an installable page, notifications whose click opens the agent or decision, and its own window (spartito app).
• No daemon: every turn is its own process; all state is in one SQLite database.

Requirements

• macOS or Linux (see Platform support).
• Python 3.14 and uv.
• git.
• The claude (Claude Code) CLI, installed and logged in, and optionally the codex CLI. The defaults use Claude Code: the orchestrator agent, spartito chat, and every project registered without --provider, so the quick start below needs claude. A Codex-only or mixed setup is configured per project and per agent: docs/configuration.md.

Installation

From PyPI, the recommended install:

uv tool install --python 3.14 'spartito[app,menubar]'    # puts `spartito` on the PATH
spartito --help

The extras bring the native window of spartito app (app) and the macOS menu-bar item (menubar; nothing on Linux). On Linux, app pulls in PyQt6, which is GPL-3.0-only: see docs/desktop.md. --python 3.14 picks the Python the package needs even when uv's default is older; uv downloads it if it is missing.

Alternatives: uv tool install --python 3.14 spartito without the extras (spartito app then opens a browser window, and on macOS notifications do not come from Spartito itself), or pipx install --python python3.14 'spartito[app,menubar]'. Remove a uv tool install with uv tool uninstall spartito. To run a checkout instead, see Development. Installed before the command was renamed? See Upgrading from orch. Installed from a checkout before the distribution was renamed to spartito? See Upgrading to the distribution name spartito.

Spartito keeps its state in ~/.orchestrator/. Set ORCH_HOME to use another directory.

Upgrading. spartito version shows the version and the kind of install, spartito version --check asks PyPI for a newer release (Spartito makes no network request on its own), and spartito upgrade prepares an upgrade: it backs the state up, prints the command for your install (for the install above uv tool upgrade spartito, which keeps the extras) and what to restart afterwards. The steps: docs/usage.md. What each release changed: CHANGELOG.md.

Quick start

Register a git repository as a project. Its currently checked-out branch becomes the project's base branch, from which agent branches start:

spartito project add ~/src/my-app
# added my-app  /home/dev/src/my-app  (base branch: main)

Through the orchestrator. The recommended way: the dashboard as a background service, and Spartito as an application:

spartito service install   # dashboard at http://127.0.0.1:8787, in the background and at login
spartito app install       # a launcher with Spartito's own name and icon
spartito app               # or open Spartito like any application

This is the beginning of the README. Read the rest at the original. Read the full README ↗