Parallm

Run multiple AI coding-agent attempts in parallel and compare their results from your terminal.

Parallm delegates work to coding-agent CLIs you already use (Codex and Claude Code). It keeps each agent's authentication, repository instructions, model access, and configuration while providing one command for bounded parallel execution and comparison.

[!NOTE] Parallm is an experimental MVP. Version 0.1 supports Codex and Claude Code targets. Codex runs use a read-only sandbox; Claude Code runs use non-interactive dontAsk permissions so unapproved tool calls are denied instead of prompting.

Install

Requirements:

• Node.js 22 or newer
• At least one supported agent CLI, authenticated for your account:
  • Codex CLI
  • Claude Code CLI

Install agents as needed, sign in, and then install Parallm:

npm install --global @openai/codex
codex login

# optional: Claude Code (see Anthropic's install docs)
claude auth login

npm install --global parallm

Verify the commands you plan to use:

codex --version
claude --version
parallm --version

Quick start

Use codex:default or claude:default to let the agent select its configured default model. Reasoning effort makes target IDs distinct:

parallm run "Review this repository and identify the most serious bug" \
  --target codex:default@low \
  --target claude:default@high

Each target is a separate agent run. Parallm starts them concurrently, shows their progress, and prints their responses in target order.

Choose targets

Target syntax is agent:model or agent:model@effort.

Codex

parallm run "Explain the authentication flow" \
  --target codex:MODEL_ID_A \
  --target codex:MODEL_ID_B

Model availability depends on your Codex version, authentication method, account, and workspace. In an interactive codex session, use /model to see models available to you. codex:default avoids hard-coding a model identifier that may not be available to every account.

Claude Code

parallm run "Explain the authentication flow" \
  --target claude:sonnet \
  --target claude:opus

Use model aliases or full IDs accepted by your Claude Code installation (sonnet, opus, haiku, or a full model name). claude:default inherits Claude's configured default model.

Cross-agent comparison

parallm run "Review this architecture" \
  --target codex:default@high \
  --target claude:sonnet@high

Reasoning effort

Append @minimal, @low, @medium, @high, @xhigh, or @max to override effort for one target:

parallm run "Review this architecture" \
  --target codex:default@low \
  --target codex:default@high

Reasoning-effort support varies by agent and model. Without @effort, each agent uses its configured default. Claude Code maps minimal → low (Claude has no minimal level). Codex may not accept max.

Control execution

Set a per-target timeout or limit simultaneous attempts:

parallm run "Find correctness risks in this repository" \
  --target codex:default@low \
  --target claude:default@high \
  --timeout 5m \
  --concurrency 2

Every target consumes a full agent run and counts toward the usage limits of that agent's account or API credentials. Higher reasoning effort, more targets, and higher concurrency can consume more tokens and encounter rate limits sooner.

Use Ctrl+C once to cancel active attempts gracefully. A second Ctrl+C forces Parallm to exit.

Output formats

Interactive terminals display a live dashboard and render response Markdown. Redirected output remains raw Markdown.

Request raw Markdown explicitly:

parallm run "Review this repository" \
  --target codex:default@low \
  --target codex:default@high \
  --format markdown > comparison.md

Produce machine-readable JSON:

parallm run "Review this repository" \
  --target codex:default@low \
  --target codex:default@high \
  --format json > comparison.json

JSON includes each target's complete stdout, stderr, exit code, signal, timing, and status. Text and Markdown output show filtered diagnostics when a successful attempt emits warning or error lines. Review JSON before sharing it because agent stderr can contain local paths, integration names, endpoints, and other environment details.

Run parallm --help for every option.

Safety boundary

Codex

Parallm invokes Codex with --sandbox read-only and --ephemeral and sends prompts through stdin instead of assembling shell command strings. This prevents model-generated local commands from modifying the workspace under Codex's sandbox and avoids persisting the Codex session.

Claude Code

Parallm invokes Claude Code with -p (print / non-interactive), --permission-mode dontAsk, and --output-format text. In dontAsk mode, tools that would require interactive approval are denied rather than prompting, so headless runs do not hang on permission dialogs. Pre-approved allow rules and Claude's built-in read-only command set still run. Parallm does not pass --dangerously-skip-permissions.

Shared caveats

These boundaries are agent-specific permission modes; they are not general process or integration isolation:

• User and project configuration for each agent remains active.
• Trusted lifecycle hooks can run.
• Configured MCP servers, apps, plugins, and other external tools retain their own permissions and approval policies.
• Non-interactive agent runs do not provide Parallm with an interactive approval loop.

Inspect your agent hooks and MCP configuration before running prompts against an untrusted repository. For a stronger integration boundary, use a dedicated config home (for example CODEX_HOME) with only the authentication and configuration you intend Parallm to inherit.

Each target receives the prompt and can read the selected working directory. Agents may send relevant prompt and repository content to their configured model providers. Parallm adds no telemetry or local run history of its own.

Troubleshooting

• spawn codex ENOENT / spawn claude ENOENT: Install the agent CLI and make sure it is on PATH.
• Unsupported model: Use codex:default / claude:default, or select an identifier shown by the agent's model picker.
• MCP, hook, or authentication diagnostic: Fix or disable that integration in the agent configuration; Parallm deliberately preserves it in attempt diagnostics.
• Rate limiting: Reduce --concurrency, use fewer targets, or lower reasoning effort.
• One target fails: Parallm preserves and prints the other results, then exits with status 1.

What works today

• Run the same prompt against two or more Codex and/or Claude Code targets concurrently.
• Compare models, agents, or reasoning-effort levels.
• Apply a per-target timeout and global concurrency limit.
• Cancel active attempts while preserving partial output.
• Keep Codex model-generated local commands in a read-only sandbox; deny unapproved Claude tools in dontAsk mode.
• Preserve stdout, stderr, exit code, signal, duration, and status.
• Render an animated Ink dashboard, Markdown, or stable JSON.
• Install as both a CLI and an ESM library.

Architecture

The comparison engine owns validation, bounded parallel execution, cancellation, timeouts, event normalization, and partial-result handling behind one run() interface.

Agent adapters sit at the external-process seam. The Codex and Claude Code adapters translate a target into a non-interactive invocation; future Gemini CLI adapters can implement the same interface without adding agent-specific flags to the engine or CLI.

CLI -> Comparison engine -> Agent adapters -> Installed coding-agent CLIs
                     \-> Normalized events -> Ink, Markdown, or JSON output

Development

pnpm install
pnpm run test:all
pnpm run smoke:package
pnpm link --global

CI validates Node.js 22, 24, and 26 on Ubuntu, Node.js 24 on macOS, and Node.js 24 on Windows. Agent availability and sandbox behavior still depend on the locally installed agent CLIs and operating system.

See RELEASING.md for the public-release checklist and SECURITY.md for vulnerability reporting.

Roadmap

• Interactive target selection and saved target profiles
• Gemini CLI adapter
• Optional local run history
• Worktree-isolated write mode and patch comparison
• Richer terminal views

License

MIT