Introducing Ramune, a task graph for coding agents

Ramune is a task-graph runtime that assigns work to multiple coding agents and integrates only verified changes in sequence.

Instead of keeping a TODO list in conversation history, it persists tasks, dependencies, assignments, and results in .ramune/graph.json. A later agent can read the graph and continue after a session ends.

Ramune currently lives under tools/ramune/ in webapp-blueprint and exposes the same graph to Claude Code, Antigravity, and Codex CLI.

Starting Ramune

Start the shared MCP server first.

mise run mcp:ramune:serve

All sessions and Git worktrees connect to one server. A second server fails to bind the port, keeping one writer for the graph.

Starting the server does not activate Ramune mode. When an agent is asked to use Ramune for a task, the orchestrator activates the session. Explicit activation is a choice that keeps ordinary editing separate from Ramune’s role policy.

The task graph

A planner decomposes the request into a dependency-aware DAG.

        ┌─ Change API ───┐
start ─┤                 ├─ Update E2E ─ end
        └─ Change UI ────┘

Nodes without dependencies can be claimed in parallel. A read-only viewer shows pending, running, blocked, and integration-waiting nodes.

pnpm --filter @webapp-blueprint/ramune-viewer dev

Four roles

Role	Responsibility
Orchestrator	Sessions, claims, and recovery operations
Planner	Nodes and dependencies
Worker	Node execution and candidate submission
Integrator	Candidate merge, verification, and publication

A worker may implement its assigned node but cannot rewrite the graph structure. A planner may edit the graph but does not edit repository files. PreToolUse hooks enforce these boundaries, with adapters translating each client’s input into one policy.

Parallel workers, serialized integration

Workers that modify the repository receive isolated Git worktrees. They produce candidate commits and submit them for integration.

Worker A ─→ candidate A ┐
                        ├─→ Integrator ─→ mise run check ─→ canonical
Worker B ─→ candidate B ┘

Workers run concurrently, while the integrator handles one candidate at a time. Publication occurs only after verification succeeds and the expected canonical HEAD still matches.

Each claim carries a fence identifying its session and assignment. A late result from an old worker is rejected when it no longer matches the current assignment.

Blockage, conflicts, and recovery

A worker can call ramune_request_replan when missing requirements or a design contradiction blocks implementation. For merge conflicts, the server inserts a conflict-resolution node that follows the same worker and integration path.

When a worker or integrator terminates, the orchestrator confirms termination and Git state before calling ramune_abandon_assignment. Ramune does not automatically reassign work after a timeout.

ramune_resume serves a different case: continuing a session after the orchestrator or server terminates. Assignment recovery and session resumption are separate operations.

When it fits

Ramune fits work with independent tasks that eventually integrate into one repository, such as larger refactors, changes across several packages, or work that separates research from implementation.

For a small edit in one file, building a graph costs more than it saves. That is why Ramune is activated per session rather than imposed on every change.

Ramune does not make an agent smarter. It records who is doing what and which changes have passed verification.

The implementation is public under webapp-blueprint/tools/ramune.