# Superpose

Everyone gave coding agents parallel files. Superpose gives them parallel machines.

Superpose is an MCP server that Codex and Claude Code call. When a task has more than one
reasonable way to do it, or when you have several tasks queued against one repo, the agent
calls Superpose instead of guessing. Superpose snapshots your machine as it is right now
(the repo, your uncommitted edits, installed dependencies, the seeded database), spins up
one isolated copy per option on Daytona, runs a real agent in each one to completion, and
returns the finished result of every option: the diff, whether the tests passed, how long it
took, and how much it cost. You pick from real outcomes, not from plans.

The point is the environment. Git worktrees give each agent its own files and stop there. The
agents still share one database, one set of ports, one dev server. So two agents that pass on
their own can fail together, for reasons their logs never show. Superpose gives each agent a
whole machine, so parallel work on one repo actually stays parallel.

## The tools an agent can call

`try_all(task, approaches, repo_path, test_cmd, benchmark_cmd?)`
Run several strategies for one task, each in its own machine, all at once. Returns one finished
outcome per strategy. If you pass a benchmark that prints `SUPERPOSE_METRIC=<number>`, the winner
is chosen by that measured number (lower is better), so you get the option that is actually
fastest, not just one that happens to pass.

`try_many(tasks, repo_path)`
Run several different tasks on the same repo at once. Each task becomes its own parallel session.

`apply_winner(session_id, fork_id, repo_path)`
Land a chosen diff on your local tree. It re-runs the tests locally first, so what lands is proven
to pass somewhere other than where it was written.

## How Daytona is used

Daytona is the part that makes the isolated machines real. Without it there is no product; you
would be back to worktrees sharing one environment.

The flow for one call:

1. Create a base sandbox from the current repo. Superpose uploads the working tree, installs
   dependencies and the test runner, initialises git so diffs can be captured, and runs an
   optional per-repo setup script (for the demo it seeds a SQLite database). This happens once.
2. Snapshot that prepared sandbox with `create_snapshot`. The snapshot carries the whole prepared
   state, including the seeded database.
3. For each strategy or task, create a fresh sandbox from that snapshot. Every one starts from the
   identical prepared state and then runs independently: its own filesystem, its own database copy,
   its own ports.
4. In each sandbox, run the agent with `process.exec` (real `codex exec`), then run the tests and
   the benchmark. Capture the diff against the base, the test result, the timing and the cost.
5. Delete every sandbox and the snapshot when the run is done. Daytona counts stopped sandboxes and
   snapshots against a hard disk quota, so each run cleans up after itself.

One honest note about fork. Daytona has a copy-on-write `sandbox.fork()` that clones a running VM
in well under a second. That is the ideal primitive for this. On the account tier we had at the
event, fork is only available for VM-class sandboxes, and VM sandboxes were not provisioned in the
regions our organisation could reach (containers only). So the shipped path is snapshot plus
parallel create-from-snapshot on container sandboxes. The isolation and the result are the same;
the difference is that each machine is spun up in a couple of seconds rather than forked instantly.
The code tries `fork()` first and falls back automatically, so on a VM-capable account it uses real
fork with no change above the provider layer.

Daytona SDK calls the project relies on: `Daytona.create`, `sandbox.create_snapshot`,
`create` from a snapshot, `sandbox.process.exec`, `sandbox.fs.upload_file`, `sandbox.delete`,
`snapshot.delete`.

## Architecture

```
Codex        --stdio-->  superpose-mcp  --\
Claude Code  --stdio-->  superpose-mcp  ---+--HTTP-->  superposed (one daemon)  -->  Daytona sandboxes
                                           |             state, cost, ranking
                                           \--SSE----->  dashboard (live fleet view)
```

One shared daemon, so both agents show up on the same dashboard. Two views:

- Monitor (`/`): a live fleet view. Every session across your agents, the sandboxes each one
  spawned, and how they branch from your base, with running spend.
- Console (`/console`): one run in detail. The parallel versus sequential clocks and the winner,
  ranked by the benchmark.

## Quickstart

```bash
uv sync
uv run pytest -q                 # runs with a local provider, no credentials needed

echo "DAYTONA_API_KEY=..." > .env
scripts/serve.sh                 # starts the daemon on Daytona + Codex, opens the dashboard
```

Register the MCP server once, then use it from a fresh agent session:

```bash
# Claude Code
claude mcp add superpose --scope user -e SUPERPOSE_PROVIDER=daytona -e SUPERPOSE_RUNNER=codex -- $(pwd)/.venv/bin/superpose-mcp
# Codex: add the block in docs/codex-config-snippet.toml to ~/.codex/config.toml
```

Then, in the agent, ask it to fork a task:

```
/superpose speed up orders_report in demo/orders
```

Three real agents run in three Daytona sandboxes, each on its own copy of the seeded database,
and the fastest fix is returned. Full walkthrough in `docs/live-session.md`.

## What is in the repo

```
src/superpose/providers/   the machine abstraction: local (for tests) and daytona
src/superpose/daemon/      superposed: HTTP and SSE, the try_all and try_many orchestrator, ranking
src/superpose/mcp/         superpose-mcp: the per-agent stdio server
dashboard/                 the Monitor, the Console, and the supporting animations
demo/orders/               the seeded N+1 demo repo used in the video
docs/                      build log, the Daytona findings from the day, the recording brief
scripts/                   serve, cleanup, and the spikes used to verify Daytona and Codex
```

Built at Daytona HackSprint London. The commit history is the event-day record.