Spartito

Open source · MIT licence

Steer a fleet of coding agents through one conversation.

Spartito runs Claude Code and Codex agents headless and in parallel, each in its own git worktree and branch, across several projects. You talk to one orchestrator agent, Maestro, instead of managing many terminal sessions by hand.

Get started GitHub
  • macOS and Linux
  • Claude Code and Codex
  • No daemon, one SQLite database
An example with invented project names: each project has its own lead, each worker its own worktree and branch, and answers travel back up.

Features

Many agents, one place to steer them

Every agent is a headless Claude Code or Codex session with a role. The details are in the documentation.

  • Project leads and workers

    Maestro briefs one lead per project; each lead starts and coordinates its own agents. They run headless (claude -p, codex exec) in parallel, each in its own git worktree and branch.

    Concepts: leads, roles, worktrees →
    main orch/fix-login-3f2a orch/search-9c1e

  • Packaged roles

    • orchestrator
    • lead
    • planner
    • worker
    • reviewer
    • tester

    A role is a Markdown prompt with a few settings, so your own role is a Markdown file.

    Roles in the configuration docs →

  • Results travel up

    Leads hand out work and end their turn. When their agents are done, the parent is woken with their answers.

    Results and notifications for agents →

  • Decisions wait for you

    What needs your decision lands in one list across projects; the agent carries on with what does not depend on it.

    Decisions →

  • Notifications that lead somewhere

    When a decision starts waiting, or an agent you wrote to is done with all of its agents. A click opens it.

    Desktop notifications →

  • A task board per project

    • idea
    • ready
    • in_progress
    • done

    Kept up to date by you and the agents, with every project's board in one view.

    Task board →

  • You merge, not the agents

    A worker commits on its own branch, orch/<agent-id>. Agents do not merge: you review the branch and merge it yourself.

    Worktrees and branches → 
    cd ~/src/my-app
git log --oneline main..orch/fix-login-3f2a
git merge orch/fix-login-3f2a

  • Tokens and cost

    Every turn records its tokens and cost, shown per agent and as totals. (Codex reports no cost.)

    Tokens and cost →

  • Model and effort

    Per tier and per provider, globally or per project, with overrides for a single agent.

    Model and effort →

  • No daemon

    Every turn is its own process; all state is in one SQLite database. The command line, the dashboard and the desktop window are views on it.

    Architecture →

Also: automatic compaction of long conversations, automatic archiving of finished agents, and keeping the machine awake while agents work.

How it works

From one goal to reviewed branches

  1. You describe the goal

    to Maestro, the orchestrator agent, in the dashboard or the desktop window.

  2. Maestro briefs the lead

    One long-lived lead per project works in its main checkout, knows the codebase and splits the work into tasks.

  3. The lead starts agents

    Workers get their own worktree on a branch orch/<agent-id>; a reviewer or tester can work in a worker's worktree.

  4. Answers travel up; you merge

    The lead reports to Maestro, which reports to you. You review the branches and merge them yourself.

Prefer the terminal? spartito chat opens the orchestrator as an interactive Claude Code session: a separate conversation with the same tools and the same state.

Install

Install and start

Spartito runs on macOS and Linux and installs with uv, straight from its repository.

macOS

  1. Prerequisites

    Python 3.14, uv, git, and the claude (Claude Code) CLI, installed and logged in; optionally the codex CLI.

  2. Install

    uv tool install "spartito[app,menubar] @ git+https://github.com/foszto/spartito"

    The extras add the native window of spartito app and the menu-bar item. Or install from a checkout.

  3. Start

    spartito service install   # the dashboard, 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

    The dashboard is at http://127.0.0.1:8787. It has no login: keep it on the loopback address (the default).

  4. Register a project and talk to Maestro

    spartito project add ~/src/my-app, then select Maestro in the dashboard and describe the goal.

Linux

  1. Prerequisites

    Python 3.14, uv, git, and the claude (Claude Code) CLI, installed and logged in; optionally the codex CLI.

  2. Install

    uv tool install "spartito[app] @ git+https://github.com/foszto/spartito"

    The extra app adds the native window of spartito app; on Linux it pulls in PyQt6, which is GPL-3.0-only (optional dependencies). The menubar extra installs nothing on Linux. Or install from a checkout.

  3. Start

    spartito service install   # the dashboard, 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

    The dashboard is at http://127.0.0.1:8787. It has no login: keep it on the loopback address (the default).

    Notifications come from an open dashboard page, else from notify-send; a click opens the agent or decision with libnotify 0.7.10 or later.

  4. Register a project and talk to Maestro

    spartito project add ~/src/my-app, then select Maestro in the dashboard and describe the goal.

Windows

Windows is not supported yet

Spartito's process handling relies on POSIX process groups and sessions. Windows support is on the roadmap; native Windows or Linux under WSL is an open question there.

Would you use it? Ideas and comments are welcome in the issues.

Every command, the direct command-line workflow and the details per platform: the README and the usage guide.

Docs

Documentation

It all lives in the Spartito repository.

Developed and used on macOS; Linux is supported; Windows is not supported. Details in the architecture notes and, per desktop feature, in the desktop documentation.