Skip to main content
Glama
aktasbatuhan

superpose-mcp

by aktasbatuhan
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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.

Related MCP server: coordinaut

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

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:

# 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.

Available Tools

4 tools
apply_winnerA

Land one fork's diff on the local tree. First re-verifies it on a fresh clean fork (the receipt), so what lands is proven to pass somewhere other than where it was written. Returns {ok, receipt_ok}.

ParametersJSON Schema
NameRequiredDescriptionDefault
fork_idYes
test_cmdNopytest -q
repo_pathYes
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must carry the transparency burden. It does well by explaining the re-verification on a fresh clean fork, the receipt concept, and the return value. It could be more explicit about failure behavior and exact side effects on the local tree, but core behavioral traits are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The purpose, verification step, and return shape are all covered in a tight, front-loaded structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and 0% parameter coverage, the description needs to do more heavy lifting. It explains the main flow and return value, but leaves session_id semantics, test_cmd usage, failure behavior, and sibling-tool routing unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so parameter meaning must come from the description. It implies fork_id via 'one fork's diff,' repo_path via 'local tree,' and test_cmd via 're-verifies,' but session_id is never explained and no parameter is explicitly mapped to its schema property.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Land one fork's diff on the local tree,' a concrete verb-object statement that clearly names the resource and target. It does not explicitly contrast with siblings like try_all or try_many, so it falls just short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: use this tool when a specific fork's diff should be landed on the local tree. It does not state when not to use it or mention alternatives like try_all/try_many, but the intended usage is apparent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sessionsA

List superpose sessions and their forks (status, timing, cost) for review.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states that the tool lists sessions and their forks, implying a read-only operation, but it does not explicitly declare the lack of side effects, authentication requirements, or any potential pagination. For a zero-parameter list tool, this is acceptable but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler. The action verb is front-loaded, and the content is directly informative. It achieves maximum clarity with minimal words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no parameters and a defined output schema, the description provides enough information for an agent to call it correctly. It names the core output fields, which is sufficient. Adding explicit read-only language or ordering/filtering notes would be a minor improvement but not necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description needs to add no parameter-specific semantics. The baseline for 0 parameters is 4, and the description adequately covers the tool's purpose without needing any parameter explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List'), a clear resource ('superpose sessions and their forks'), and the exact fields returned ('status, timing, cost'). This makes the tool's purpose unambiguous and differentiates it from the sibling tools, which likely focus on executing actions rather than reviewing existing sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for review' provides clear context that this tool is meant for inspecting or auditing sessions, which implies it should be used when the agent needs an overview rather than taking an action. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

try_allA

Run several genuinely different strategies for the same task, each in its own forked machine (real repo + uncommitted edits + seeded DB + running services), all at once, and return the finished outcome of each: diff, test result, wall-clock, cost.

Call this instead of picking one approach yourself whenever a task has more than one plausible strategy (e.g. a perf fix: add-index vs cache vs query-rewrite). Pass 2-8 approaches, each a short strategy label + one sentence of instruction.

If benchmark_cmd is given, it runs in each fork after the tests pass and should print a line SUPERPOSE_METRIC=<number> (lower is better, e.g. p95 latency in ms). The winner is then chosen by the best measured metric — so you pick the approach that is actually fastest, not just one that happens to pass. Land it with apply_winner.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
test_cmdNopytest -q
repo_pathYes
approachesYes
benchmark_cmdNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it delivers: it discloses fork isolation, execution in parallel, what each fork includes, the outputs (diff, test result, wall-clock, cost), the benchmark ordering after tests pass, the expected metric format, and winner selection. This is rich behavioral detail beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured in three short paragraphs, front-loading the core purpose and outputs. Every sentence adds meaningful guidance: the example clarifies strategy diversity, the benchmark paragraph adds precise operational detail, and the final pointer to apply_winner closes the workflow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core workflow, constraints, benchmark semantics, and follow-up action; an output schema exists so return-value details need not be spelled out. The only notable gap is that it does not state what happens when no 'benchmark_cmd' is supplied, i.e., whether there is still a winner or how the agent should decide.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clearly explains 'approaches' (2-8, short label + instruction) and 'benchmark_cmd' (runs after tests, prints SUPERPOSE_METRIC, lower is better). It does not explicitly map every parameter name like 'repo_path' or 'test_cmd' to its schema property, though their roles are implied strongly by context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description leads with a specific verb and resource: 'Run several genuinely different strategies... each in its own forked machine' and explicitly lists what is returned. It also separates itself from 'apply_winner' by framing that tool as the follow-up step, making the purpose and boundary clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use rule: 'Call this instead of picking one approach yourself whenever a task has more than one plausible strategy,' with a concrete example. It also specifies the 2-8 approach limit, how each approach should be phrased, and when to use the winner with 'apply_winner.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

try_manyA

Run several DIFFERENT tasks on the same repo AT ONCE — each becomes its own parallel Superpose session, all running together. Use this when you have multiple independent changes queued for one codebase and want them worked in parallel from a single call.

tasks is a list of objects, each: {task, approaches, test_cmd?, benchmark_cmd?} — the same fields as try_all. Returns every session's finished result. They appear live and concurrently on the Monitor at http://localhost:8787/ as separate branch trees.

ParametersJSON Schema
NameRequiredDescriptionDefault
tasksYes
repo_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden and handles it well: it discloses parallel execution, live concurrent Monitor display, separate branch trees, and that every session's result is returned. It does not discuss side effects, permissions, or cleanup, but the branch-tree model implies isolation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences with no fluff: purpose and usage are front-loaded, parameter shape comes second, and return/monitor behavior closes it out. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the parallel execution model, the task object shape, the monitor URL, and the return behavior; the presence of an output schema also covers detailed return structure. It relies on the sibling definition of try_all for full field semantics and omits explicit side-effect or prerequisite warnings, so it is not flawless.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description's breakdown of `tasks` as a list of `{task, approaches, test_cmd?, benchmark_cmd?}` objects is essential and useful. `repo_path` is only indirectly described via 'same repo', which is adequate given the parameter name but less explicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource: 'Run several DIFFERENT tasks on the same repo AT ONCE—each becomes its own parallel Superpose session.' This makes the tool's purpose unmistakable and differentiates it from siblings like try_all, which is referenced as the source of the task-field format rather than as the same behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use the tool: 'Use this when you have multiple independent changes queued for one codebase and want them worked in parallel from a single call.' It does not explicitly list counter-indications or name alternative tools, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation4/5

try_all and try_many are the only potentially confusable pair, but their descriptions clearly separate “multiple strategies for one task” from “multiple tasks in parallel.” apply_winner and list_sessions are distinct lifecycle steps, so overall boundaries are clear.

Naming Consistency4/5

All names are lowercase snake_case verbs, and try_all/try_many form a consistent parallel-execution pair. apply_winner and list_sessions follow a verb+noun pattern, which is slightly different from the try_+quantifier pattern but still predictable and readable.

Tool Count5/5

Four tools cleanly cover the core workflow: launch strategy comparisons, launch multiple tasks, land a result, and inspect sessions. This is well-scoped for a focused parallel-experiment runner, with no redundant tools.

Completeness4/5

The main lifecycle of running parallel sessions and landing a verified winner is fully covered, with no dead ends in the primary path. A cancel/abort or per-session detail tool would be a useful addition, but list_sessions provides enough visibility to work around that gap.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aktasbatuhan/superpose'

If you have feedback or need assistance with the MCP directory API, please join our Discord server