manta

CLI for Manta. Core commands: cast, status, kill, abort, recover (plus inspect, tail, replay, promote, cost, charges, doctor, and more). Modes: recon-swarm, forking-realities, bug-hunt, refactor-wave, pair-programming, test-storm, and documentation-chase, plus the opt-in council and decoy modes.

Install

Manta is distributed as an npm CLI (published as the unscoped manta package):

npx manta@latest install      # installs the bin + registers the manta-bus MCP server
manta cast recon-swarm --task "…"

The Claude Code plugin is the primary v1 distribution mechanism (/plugin marketplace add tr00x/Manta → /plugin install manta@manta → /manta:* + skills + auto-bus). This npm CLI is the terminal / power-user path. See the repo-root README.md Install section.

Precondition: manta cast runs from inside a Manta-enabled git checkout — a repo/worktree that carries the skills/ directory (e.g. a clone of the Manta repo). Casting from an arbitrary empty directory is not supported — clones need the manta-as-clone skill on disk and a git repo for the worktree.

From a source checkout (working from the monorepo today), build once and run the bin directly:

pnpm --filter manta build
node /path/to/manta/packages/manta-cli/dist/bin/manta.cjs <command>

Commands

manta cast <mode>

Spawn N clones of the given mode and run the orchestrator until they all exit.

manta cast recon-swarm --clones 3 --task "map the codebase"

Options:

• --clones <n> — number of clones (1..5; default 2)
• --task <task> — task description (passed into each clone's task contract)
• --cycle-interval-ms <ms> — orchestrator cycle interval (default 5000)
• --tick-budget-ms <ms> — overall budget; the cast aborts after this (default 1_500_000 = 25 min)
• --max-parallel-clones <n> — max clones a single cast may spawn at once, a parallelism cap (default from config, or 5)
• --max-casts-per-hour <n> — max casts allowed to start in a rolling hour, a cast-rate cap that protects your subscription usage/rate limit (default from config, or 6)
• --max-tokens-estimate <n> — optional per-cast usage ceiling (a token-estimate proxy, not dollars); rejects the cast if its cumulative per-clone estimate exceeds this
• --max-files-changed <n> — per-clone hard cap on file writes (0 = read-only)

Manta runs on a Claude Code subscription, not pay-per-token, so the caps are usage-aware — parallelism, cast rate, and a token-estimate proxy — rather than dollar budgets.

An unknown mode throws invalid_input. The council and decoy modes are opt-in and must be enabled in config/env before they can be cast.

Pre-flight: before spawning, the cast verifies that manta-bus is registered as an MCP server with Claude Code (claude mcp list). Without that, claude --print clones cannot reach the bus and the cast would time out silently. The check is bypassed for tests via verifyMcp: false in the programmatic API.

manta status

Print the orchestrator's snapshot — registered clones, held locks, active claims. Pure read; never mutates state.

manta kill <cloneId>

Mark a single clone DEAD and write its post-mortem. Exits with not_found if the clone is unknown. Safe to call on already-DEAD clones (the post-mortem is idempotent and preserves the original death_reason).

manta abort

Mark every live clone DEAD and write a post-mortem each. Already-DEAD clones are left untouched.

manta recover

Run one orchestrator cycle. Detects stale heartbeats and orphan parents, reaps stale locks/claims, writes post-mortems for any newly-dead clones. Use after a crash or when cleaning up after a forced kill.

Errors

Every command throws CliError on failure. The bin maps errors to exit codes:

| Kind | Exit code | | --------------------- | --------- | | invalid_input | 1 | | not_found | 1 | | cast_failed | 1 | | spawn_failed | 1 | | orchestrator_failed | 1 | | recovery_failed | 1 | | Other (unwrapped) | 99 |

Use isCliError(err) to type-narrow when calling commands programmatically.

Programmatic use

Every command is exported as runXCommand(runtime, options) so a tester or daemon can call them without spawning the bin.

import {
  createRuntime,
  runCastCommand,
  runFakeCloneScript,
  createReporter,
  StderrSink,
} from 'manta';

const rt = await createRuntime({ repoRoot: '/path/to/repo' });
await runCastCommand(rt, {
  mode: 'recon-swarm',
  task: 'audit auth',
  cloneCount: 2,
  cycleIntervalMs: 5_000,
  tickBudgetMs: 1_500_000,
  castId: 'cast-1',
  maxFilesChanged: 0,     // 0 = read-only clones
  maxParallelClones: 5,   // parallelism cap
  maxCastsPerHour: 6,     // cast-rate cap (protects subscription usage)
  verifyMcp: false, // tests with fake runners
  runner: runFakeCloneScript({ scriptPath: '/path/to/fake-clone.mjs' }),
  reporter: createReporter({ sink: new StderrSink() }),
});