parallax-cli

WARNING: Parallax is currently in alpha. Expect rough edges, missing polish, and occasional breaking changes.

Parallax is a local AI orchestration runtime for software tasks. It pulls work from Linear or GitHub, creates isolated worktrees, runs an agent in two phases (plan then execute), and requires explicit approval before implementation.

First version scope

• Plan-first task lifecycle with explicit approval/rejection.
• Issue intake from Linear and GitHub.
• Global runtime state under ~/.parallax.
• CLI control plane plus dashboard UI.
• Codex, Gemini, and Claude Code adapters (configurable per project).

Requirements

• Node.js >= 23.7.0
• pnpm 10.x
• git
• gh
• at least one supported agent CLI (codex, gemini, or claude)
• Provider credentials in your shell environment (optional per-project .env via parallax register --env-file)

Local development setup

pnpm install
pnpm parallax preflight
pnpm test
pnpm build

Install global CLI

npm i -g parallax-cli
parallax preflight

Configuration (parallax.yml)

Repository config is stored per repo, then registered into the global Parallax runtime:

pnpm parallax start --server-api-port 3000 --server-ui-port 8080 --concurrency 2
pnpm parallax register ./parallax.yml --env-file ./.env

parallax.yml is a YAML array of project entries:

- id: example-repo
  workspaceDir: /absolute/path/to/your/repo
  pullFrom:
    provider: github
    filters:
      owner: your-github-org-or-user
      repo: your-repo
      state: open
      labels: [ai-ready]
  agent:
    provider: codex
    model: gpt-5.4

CLI

pnpm parallax --version
pnpm parallax start --server-api-port 3000 --server-ui-port 8080 --concurrency 2
pnpm parallax register ./parallax.yml --env-file ./.env
pnpm parallax unregister ./parallax.yml
pnpm parallax stop
pnpm parallax preflight
pnpm parallax status
pnpm parallax pending
pnpm parallax pr-review <task-id>
pnpm parallax retry <task-id>
pnpm parallax cancel <task-id>
pnpm parallax logs --task <task-id>

Commands:

• parallax start [--server-api-port <port>] [--server-ui-port <port>] [--concurrency <count>]
• parallax register <config-file> [--env-file <path>]
• parallax unregister <config-file>
• parallax stop
• parallax preflight
• parallax status
• parallax pending [--approve <id>] [--reject <id>]
• parallax pr-review <task-id> (experimental)
• parallax retry <task-id>
• parallax cancel <task-id>
• parallax logs [--task <id>]

Runtime behavior

1. Pull eligible tasks from provider filters.
2. Generate plan text and persist it.
3. Wait for explicit plan approval from UI or CLI.
4. Execute only approved plan steps.
5. Open/update PR and move task lifecycle state.

Dashboard behavior

• Pending plans are editable in a textarea and can be approved/rejected in-place.
• Task logs stream in real time.
• File changes are shown as clickable entries with side-panel diff view.

Development

See CONTRIBUTING.md.

Documentation

For full user guides, see docs/README.md.

Publish Global CLI (parallax-cli)

Parallax is published as a single global CLI package:

npm i -g parallax-cli

Releases are published through the manual GitHub Actions workflow:

• open the Release parallax-cli workflow in GitHub Actions
• trigger it with Run workflow
• the workflow publishes the exact version already set in packages/cli/package.json

Repository requirement:

• configure npm trusted publishing for this repository/package in npm

Before triggering the release, update the version in:

packages/cli/package.json

Then on Raspberry Pi / any machine:

npm i -g parallax-cli
parallax preflight
parallax start --server-api-port 3000 --server-ui-port 8080 --concurrency 2
parallax status
parallax register ./parallax.yml

Default runtime locations and ports:

• runtime state: ~/.parallax
• API: http://localhost:3000
• dashboard: http://localhost:8080

License

MIT. See LICENSE.