Parallel Agent CLI

Parallel Agent CLI coordinates isolated Git worktrees and local development environments across coding agents such as Codex, Claude Code, and OpenClaw.

The repository owns the workflow. A committed project contract defines setup commands, checks, Git policy, runtime configuration, and production safeguards. Each task receives its own branch and worktree so concurrent agents do not overwrite one another's source code.

Important

This is an early functional preview intended for local testing. It does not push branches, open pull requests, merge changes, or deploy production releases yet.

Features

• Separate branch and Git worktree for every agent task
• Existing-worktree adoption without resets or file changes
• Recorded base commits and stale-work detection
• Repository-owned setup, check, Git, and deployment policy
• Isolated local ports, process metadata, logs, and clean shutdown
• Optional Vercel Development environment injection without persisted secret values
• Agent-aware launch context for Codex, Claude Code, and OpenClaw
• Portable instructions for app-based, remote, and unsupported agent clients
• Machine-readable project and workspace state

Install from source

Parallel Agent CLI requires Node.js 20 or newer, Git, and pnpm.

git clone https://github.com/svvayyy/parallel-agent-cli.git
cd parallel-agent-cli
pnpm install
pnpm build
npm link

The global executable is pagent.

Quick start

Run these commands from an existing Git repository with at least one commit:

pagent init
pagent doctor
pagent context
pagent enter dashboard-feature --agent openclaw
pagent enter dashboard-polish --agent codex
pagent launch dashboard-polish
pagent status

pagent launch starts the selected coding agent in the isolated worktree and supplies the committed project workflow as its initial context. It does not create, replace, or modify AGENTS.md, CLAUDE.md, or other repository instruction files.

Include the first task when launching an agent:

pagent launch dashboard-polish --prompt "Polish the dashboard navigation"

For ChatGPT, a remote OpenClaw agent, or another client that Parallel Agent CLI cannot launch directly, print a portable handoff and paste it into that client:

pagent instructions dashboard-polish --agent chatgpt

To register a worktree that already exists:

pagent adopt ../existing-worktree --agent claude

Remove a workspace when the task is finished:

pagent remove dashboard-polish

Managed worktrees must be clean before removal, and their Git branches are retained. Adopted worktrees are only unregistered; Parallel Agent CLI never deletes them.

Project contract

pagent init creates .parallel-agent/project.yaml. Commit this file so every developer and coding agent receives the same operational workflow after cloning the repository.

version: 1
project:
  name: example-app
repository:
  default_branch: main
runtime:
  install: pnpm install
  development: pnpm dev
  healthcheck: /
  port_env: PORT
  environment:
    provider: inherit
    target: development
  copy_into_workspaces: []
checks:
  - pnpm typecheck
  - pnpm test
  - pnpm build
git:
  branch_prefix: agent
  agents_may_commit: true
  agents_may_push_feature_branches: true
  direct_push_to_main: false
  force_push: false
production:
  requires_approval: true
  deploy_by_merging: true

The project contract contains commands and policy, not credentials. Machine-local state is stored inside the repository's shared Git directory. Managed worktrees and logs live under ~/.parallel-agent/ by default; set PARALLEL_AGENT_HOME to choose another location.

Development servers

Start, inspect, and stop the configured development server for a workspace:

pagent dev dashboard-feature
pagent status
pagent logs dashboard-feature
pagent stop dashboard-feature

Parallel Agent CLI allocates a local port, records the process and log path, and checks the configured health URL. Running pagent dev from inside a registered worktree infers its workspace name.

Agents started through pagent launch are explicitly instructed to use pagent bootstrap, pagent dev, pagent logs, and pagent stop rather than bypassing the managed runtime lifecycle. Codex and Claude Code run with the worktree as their current project. OpenClaw starts in local TUI mode with the worktree supplied through OPENCLAW_WORKSPACE_DIR and in the handoff instructions. An explicit OpenClaw workspace in the user's configuration can take precedence over that environment variable; use pagent instructions with an already configured OpenClaw agent in that case.

For a Vercel-backed development environment:

runtime:
  development: pnpm dev
  healthcheck: /
  port_env: PORT
  environment:
    provider: vercel
    target: development
providers:
  vercel:
    enabled: true
    project: example-app
    production_branch: main

The CLI copies only .vercel/project.json into the worktree, verifies the project link, and starts the configured command through vercel env run. Environment values are injected into the child process rather than written to an environment file.

Commands

pagent init
pagent context [--json]
pagent doctor
pagent bootstrap [--apply]
pagent enter <name> --agent <agent> [--base <git-ref>]
pagent adopt <path> --agent <agent> [--name <name>] [--base <git-ref>]
pagent launch [name] [--agent <agent>] [--prompt <task>] [--dry-run]
pagent instructions [name] [--agent <agent>] [--prompt <task>]
pagent remove <name>
pagent dev [name] [--port <port>] [--no-wait]
pagent logs <name> [--lines <count>]
pagent stop <name> [--force]
pagent status [--json] [--fetch]

bootstrap is non-mutating unless --apply is provided. Without it, the command only reports the configured installation step.

Safety model

• Workspaces are created outside the source repository by default.
• Existing worktrees are adopted without moving, resetting, or rewriting them.
• Workspace removal refuses to discard uncommitted changes and retains Git branches.
• The exact base commit is recorded when a workspace is created.
• Stale workspaces are reported before integration or deployment work.
• Production and force-push policy is explicit in the committed contract.
• Vercel authentication and environment retrieval remain delegated to the Vercel CLI.
• Parallel Agent CLI does not collect telemetry.

Project policy is descriptive in this preview. Future GitHub and deployment adapters will enforce remote operations independently of agent behavior.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

Integration tests create temporary Git repositories and real local development processes. Temporary resources are removed after each test.

Roadmap

• Checkpoint and recovery commands for work in progress
• File-overlap warnings between active workspaces
• Release-candidate composition from selected workspaces
• Guarded branch push and pull-request creation
• Preview deployment association and verification
• Approval-gated production promotion
• Cross-machine workspace discovery

License

MIT