https://github.com/maxigimenez/parallax-cli
Parallax is a local AI orchestration runtime for software tasks.
https://github.com/maxigimenez/parallax-cli
ai automation claude-code cli codex coding-agent developer-tools gemini github linear orchestrator parallax pull-request
Last synced: 13 days ago
JSON representation
Parallax is a local AI orchestration runtime for software tasks.
- Host: GitHub
- URL: https://github.com/maxigimenez/parallax-cli
- Owner: maxigimenez
- License: mit
- Created: 2026-03-02T16:22:17.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-18T19:01:10.000Z (27 days ago)
- Last Synced: 2026-03-19T08:08:13.709Z (26 days ago)
- Topics: ai, automation, claude-code, cli, codex, coding-agent, developer-tools, gemini, github, linear, orchestrator, parallax, pull-request
- Language: TypeScript
- Homepage: https://parallax.maxigimenez.xyz/
- Size: 693 KB
- Stars: 6
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 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
```bash
pnpm install
pnpm parallax preflight
pnpm test
pnpm build
```
## Install global CLI
```bash
npm i -g parallax-cli
parallax preflight
```
## Configuration (`parallax.yml`)
Repository config is stored per repo, then registered into the global Parallax runtime:
```bash
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:
```yaml
- 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
```bash
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
pnpm parallax retry
pnpm parallax cancel
pnpm parallax logs --task
```
Commands:
- `parallax start [--server-api-port ] [--server-ui-port ] [--concurrency ]`
- `parallax register [--env-file ]`
- `parallax unregister `
- `parallax stop`
- `parallax preflight`
- `parallax status`
- `parallax pending [--approve ] [--reject ]`
- `parallax pr-review ` (experimental)
- `parallax retry `
- `parallax cancel `
- `parallax logs [--task ]`
## 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](CONTRIBUTING.md).
## Documentation
For full user guides, see [docs/README.md](docs/README.md).
## Publish Global CLI (`parallax-cli`)
Parallax is published as a single global CLI package:
```bash
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`](packages/cli/package.json)
Repository requirement:
- configure npm trusted publishing for this repository/package in npm
Before triggering the release, update the version in:
```bash
packages/cli/package.json
```
Then on Raspberry Pi / any machine:
```bash
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](LICENSE).