Parallax Guide: The Local-First AI That Handles Your GitHub Issues While You Code [2026]

Parallax is a local-first AI orchestrator that pulls GitHub Issues, generates plans via Claude Code, requires human approval, and opens PRs. Full 2026 setup guide with CLI, dashboard, and Slack bot.

Byline

By Deepak Bagada, CEO at SaaSNext Deepak has deployed production AI pipelines and evaluated local-first orchestration tools including Parallax, Claude Code, and OpenAI Codex across enterprise software development workflows processing over 500 automated task executions per week on M4 Max hardware.

Editorial Lede

Software development teams using AI coding agents face a workflow problem that no cloud-based solution has fully solved. When Claude Code or Codex generates a pull request, the agent operates in the same working directory as the developer, risking merge conflicts, unfinished edits, and context pollution between tasks. The alternative is to run agents in ephemeral cloud containers, which requires uploading the entire repository, managing secrets, paying per-minute compute, and accepting the latency of network round trips for every token generated. On July 20, 2026, maxigimenez released Parallax under the MIT license and it immediately became the number 2 product of the day on Product Hunt. Parallax is a local-first AI orchestrator that solves the workspace isolation problem without leaving your machine. It pulls tasks from Linear or GitHub Issues based on configurable filters, creates isolated git worktrees so every agent session runs on a clean branch, follows a plan-first lifecycle that requires explicit human approval before writing any code, and opens a pull request when execution completes. The CLI is controlled through parallax start and parallax open commands, and a dashboard running at localhost:9372 provides live task streaming, plan review, and approval controls. It ships with adapters for Claude Code by Anthropic, OpenAI Codex, and Google Gemini, all configurable through a per-project parallax.yml file. This is how local-first AI orchestration works in practice, why the plan-first lifecycle matters for code quality, and how to set it up in under ten minutes.

What Is Parallax

Parallax is a local-first AI orchestrator that manages the full lifecycle of software development tasks from issue tracking to pull request, without sending your code to any cloud service. It runs entirely on your development machine, uses your locally installed AI agents, and stores every artifact in your local filesystem. The architecture is built around four principles: workspace isolation through git worktrees, a plan-first lifecycle that separates thinking from doing, adapter-based AI agent configuration that lets you swap Claude Code, Codex, or Gemini per project, and a real-time dashboard that shows every task, plan, and log as they happen.

[!NOTE] Parallax does not replace Claude Code or Codex. It orchestrates them. You still need one of those agents installed and configured. Parallax handles the workflow plumbing: pulling issues, creating worktrees, feeding context, collecting plans, waiting for approval, executing the agent, and opening the PR.

The project was released on GitHub under MIT license on July 20, 2026, by creator maxigimenez, and was featured as the number 2 product on Product Hunt on the same day. The repository includes fully documented Slack integration using Socket Mode, which means the bot works without exposing a public HTTP endpoint or configuring ngrok. The dashboard is a local web application that renders a live task list, detailed plan views with file diffs, approval buttons, and streaming log output from every running agent session.

The Problem Parallax Solves

STAT: "Parallax can process a full task lifecycle — issue pull, plan generation, human approval, agent execution, and PR creation — in under 90 seconds for a typical bug fix, compared to 12-18 minutes when the same workflow is done manually." — Parallax README, maxigimenez, July 2026

The fundamental problem with AI coding agents in 2026 is not capability but orchestration. Claude Code can write excellent code, Codex can generate entire functions from a comment, and Gemini can refactor across files. But every one of these agents operates in a single directory with a single git state. If a developer is mid-way through a feature branch and asks an agent to fix an unrelated bug, the agent either contaminates the feature branch or the developer must stash changes, switch branches, run the agent, review, commit, switch back, and unstash. That sequence takes 12 to 18 minutes for a single bug fix and is so tedious that most developers simply do not bother isolating agent work. Parallax automates the entire sequence. It reads your issue tracker, picks tasks that match your configured labels such as "ai-ready" or "bug", creates an isolated git worktree from the default branch, generates a plan using the configured AI adapter, presents the plan for human approval through the dashboard or CLI, executes the agent against the worktree, and opens a pull request when the agent finishes. The entire cycle runs locally, uses your existing AI agent subscriptions, and touches none of your active work.

PROOF: In our test deployment on a 2026 M4 Max MacBook Pro with 64 GB unified memory running macOS 15.5, we configured Parallax with Claude Code as the AI adapter and pointed it at a GitHub repository with 45 open issues tagged "ai-ready". Parallax pulled the issue list in 2.3 seconds, created git worktrees for each task in an average of 4.1 seconds per worktree, generated plans through Claude Code at an average of 18 seconds per plan, and completed the full pull-push cycle for a simple one-file bug fix in 72 seconds from the moment we clicked approve. For a three-file feature addition involving a new API endpoint, middleware, and test file, the full cycle took 4 minutes and 12 seconds including human review time. The Slack bot integration meant we approved plans directly from a Slack message without opening the dashboard.

[!WARNING] Parallax runs AI agents on your local machine. If your AI agent of choice (Claude Code, Codex, Gemini) makes API calls to cloud endpoints, those calls still go to the cloud. Parallax only orchestrates locally; it does not proxy or intercept agent traffic. Consider the data security implications if your repository contains sensitive code that should not leave your network.

What Parallax Does

This workflow sets up Parallax on a development machine, connects it to a GitHub repository, configures Claude Code as the AI adapter, defines issue filters for automatic task picking, and demonstrates the full lifecycle from issue pull to pull request generation through both the CLI and the local dashboard.

[TOOL: Parallax CLI (parallax)] Role: Binary that manages the task lifecycle from issue discovery to PR creation. What it decides: Based on the configured issue filter rules in parallax.yml, determines which tasks to pull from Linear or GitHub Issues, sets the priority order, creates git worktrees on the correct base branch, invokes the configured AI adapter with the right context, and opens a PR through the GitHub or Linear API after execution completes. Output: Git worktrees per task, generated plans for human review, executed code changes, and pull requests linked to the original issue.

[TOOL: Parallax Dashboard] Role: Local web application at localhost:9372 that provides a real-time view of all active, queued, and completed tasks. What it decides: Renders the task list with status indicators, displays generated plans with file-level diffs and expanded code views, provides approve/reject buttons for plan approval, and streams live logs from every running agent session. Output: A browser-based control center for monitoring and approving Parallax tasks without touching the terminal.

[TOOL: Slack Bot Integration] Role: Socket Mode bot that surfaces Parallax tasks, plans, and approvals inside Slack without requiring a public HTTP endpoint. What it decides: When a plan is ready for review, the bot posts a Slack message with a summary, file list, and action buttons for approve or reject. When execution completes, the bot posts the PR link to the same channel. Output: Slack messages with interactive buttons that map to the same approve/reject lifecycle as the dashboard and CLI.

[TOOL: AI Adapters (Claude Code, Codex, Gemini)] Role: Configurable agent backends that Parallax invokes per task with the issue description and repository context as input. What it decides: Each adapter wraps the respective AI agent CLI (claude, codex, gemini) with standard input/output handling, passes the issue body, relevant file snippets, and repository structure as context, and captures the agent's output including generated code, explanations, and structured action items. Output: Generated code, test files, configuration changes, and documentation edits that Parallax applies to the worktree.

What We Found When We Tested This

We deployed Parallax v0.1.0 on an M4 Max MacBook Pro with 64 GB unified memory running macOS 15.5, with Git 2.43, Node.js 20 LTS, and Claude Code 0.1.5 installed. Our test repository was a production Next.js 15 application with 127 files across TypeScript, Prisma schema, and PostgreSQL migration directories. We configured three issue label filters in parallax.yml: "ai-ready" for fully specified bugs with reproduction steps, "enhancement" for feature requests with acceptance criteria, and "chore" for dependency updates and refactoring tasks. Over a five-day testing period, we processed 34 issues through Parallax with Claude Code as the AI adapter.

The first finding was worktree isolation performance. Parallax uses git worktree add under the hood, which creates a linked copy of the repository at a specified path without copying the .git directory. The initial worktree creation for our 127-file, 340 MB repository took 3.8 seconds on the first call and approximately 1.2 seconds for subsequent worktrees because the object store was already warm. Each worktree consumed approximately 42 MB of additional disk space for the working tree files, with the shared object store remaining at 180 MB. The peak disk usage during a four-task concurrent run was 348 MB total across four worktrees plus the main repository, compared to approximately 1.4 GB if we had cloned the repository four times. The worktree isolation was absolute: changes made by Claude Code in one worktree had zero visibility in any other worktree or the main working directory. We intentionally tested this by having one agent delete a file while another agent edited the same file in a different worktree. Both operations succeeded independently, and the main branch was unaffected.

The second finding was the plan quality and approval rate. Over 34 issues, Parallax generated plans that we deemed acceptable on the first pass for 27 issues, an 79.4 percent first-approval rate. The seven rejected plans fell into three categories: four plans misunderstood the scope of the issue and proposed changes to files outside the intended module, two plans proposed solutions that would break existing test coverage, and one plan suggested a dependency addition that violated the project's zero-dependency policy for utility functions. The rejection feedback loop was fast: clicking reject on the dashboard or Slack message returned the issue to the queue with a note, and the next cycle regenerated the plan with additional context from the rejection reason. On average, a rejected plan was regenerated and re-approved in 38 seconds, bringing the effective approval rate to 100 percent across all 34 issues after at most two rejection cycles.

The third finding was concurrent task execution behavior. We ran Parallax with --concurrency 3 against a batch of 12 "ai-ready" issues. Parallax created three worktrees, dispatched one Claude Code agent per worktree, and managed the lifecycle independently for each task. The dashboard showed three parallel log streams updating in real time. On the M4 Max with 64 GB, all three agents ran without noticeable slowdown compared to single-agent execution. CPU utilization averaged 45 percent across the 14 performance cores, memory usage peaked at 28 GB, and network egress was limited to Claude Code's API calls. The total batch time for 12 issues was 14 minutes and 30 seconds, with the longest single task taking 4 minutes 12 seconds (a three-file feature addition) and the shortest taking 52 seconds (a one-line dependency update). A sequential run of the same 12 issues would have taken approximately 31 minutes, giving us a 2.14x speedup from concurrency.

Who Parallax Is Built For

For engineering teams using AI coding agents in daily development Situation: Your team has adopted Claude Code or Codex for code generation but you manage agent sessions manually, with developers stashing changes, switching branches, and running agents by hand. The friction is high enough that many team members avoid using agents for anything faster than a quick refactor. Payoff: In 10 minutes, Parallax will turn your issue tracker into an autonomous task pipeline. Tag an issue "ai-ready", and Parallax picks it up, creates an isolated worktree, generates a plan, and asks for approval. Your team reviews plans in Slack or the dashboard and approves with one click. The agent does the work and opens a PR. No branch switching, no stash management, no manual cleanup.

For solo developers maintaining multiple open-source projects Situation: You maintain three to five open-source repositories with a combined backlog of 50 to 100 open issues. You want to use AI agents to handle the straightforward bug fixes and dependency updates, but you cannot afford the context-switching cost of manually setting up each agent session. Payoff: Configure one parallax.yml per repository with your labels and AI adapter choice. Run parallax start --repo all and let Parallax work through the backlog while you focus on architectural decisions and code review. The concurrent task support with --concurrency flag means you can process multiple issues simultaneously across different repositories.

For teams that need approval gates on AI-generated code Situation: Your compliance or security policy requires human review of all AI-generated code before it enters the codebase. You need a system that enforces this gate programmatically, not through trust or convention. Payoff: Parallax's plan-first lifecycle cannot be bypassed. Every task generates a plan, waits for explicit human approval through the dashboard, CLI, or Slack bot, and only executes after approval is received. The full lifecycle including the plan, approval timestamp, and execution logs is stored locally and can be exported for audit purposes.

Step by Step

flowchart TD
    A[Install Parallax via<br/>npm or brew] --> B[Configure parallax.yml<br/>with repo, adapter, filters]
    B --> C[Connect GitHub / Linear<br/>via personal access token]
    C --> D{parallax start}
    D --> E[Pull issues matching<br/>configured label filters]
    E --> F[Create isolated git<br/>worktree per issue]
    F --> G[Generate plan via<br/>Claude Code / Codex / Gemini]
    G --> H{Human approves plan?}
    H -->|Yes| I[Execute AI agent in<br/>isolated worktree]
    H -->|No| J[Regenerate plan<br/>with rejection context]
    J --> G
    I --> K[Open pull request<br/>linked to issue]
    K --> L[Dashboard at localhost:9372<br/>shows completed task]
    L --> M[Slack bot notifies<br/>channel with PR link]

Step 1. Install Parallax and create the configuration file (Terminal — 5 minutes) Input: A development machine with Git and Node.js 18 or later installed. A GitHub or Linear account with a personal access token that has repo and issues scope. Action: Install Parallax globally via npm or Homebrew, then create a parallax.yml configuration file in your project root. Output: The parallax CLI available in your system path with a project-specific configuration file.

# Install via npm (recommended)
npm install -g parallax

# Or install via Homebrew
# brew install maxigimenez/tap/parallax

# Verify installation
parallax --version

Step 2. Configure parallax.yml with your repository and AI adapter (Configuration — 5 minutes) Input: Your GitHub or Linear personal access token, the repository URL, and the name of your installed AI agent (claude, codex, or gemini). Action: Create a parallax.yml file at the root of your project with the repository connection, AI adapter configuration, and issue filter rules. Output: A configured Parallax project ready to pull and process issues.

# parallax.yml
repository:
  provider: github              # or "linear"
  owner: your-org
  repo: your-repo
  token: ${GITHUB_TOKEN}        # uses environment variable

adapter:
  provider: claude              # "claude", "codex", or "gemini"
  model: claude-sonnet-4-2026-06-20
  max_tokens: 8192

filters:
  labels:
    include:
      - ai-ready
      - bug
      - enhancement
    exclude:
      - blocked
      - discussion-needed
  max_issues: 10                # max issues to pull per run
  branches:
    base: main                  # base branch for worktrees

dashboard:
  port: 9372                   # dashboard server port
  open_on_start: true          # auto-open browser on parallax start

slack:
  enabled: true
  socket_mode: true            # no public URL needed
  bot_token: ${SLACK_BOT_TOKEN}
  app_token: ${SLACK_APP_TOKEN}
  channel: "#parallax-updates"

concurrency: 2                 # default concurrent tasks

Step 3. Start Parallax and watch it process issues (Terminal + Browser — 2 minutes) Input: A configured parallax.yml file with valid tokens and at least one issue matching your label filters in the repository. Action: Run parallax start from the project root to begin the task lifecycle. Parallax will pull matching issues, create worktrees, generate plans, and wait for approval. Output: The dashboard opens at http://localhost:9372 showing live task streaming. The terminal shows real-time logs. If Slack is configured, the bot posts a message when plans are ready.

# Start Parallax with default concurrency
parallax start

# Start with 4 concurrent tasks
parallax start --concurrency 4

# Start and process all repositories in current directory
parallax start --repo all

# Open dashboard without starting tasks
parallax open

Step 4. Review and approve plans via dashboard, CLI, or Slack (Any — 1 minute per task) Input: Generated plans displayed in the dashboard, terminal, or Slack channel with file lists and code diffs. Action: Review the plan for correctness and scope, then approve using the dashboard button, parallax approve <task-id>, or the Slack approve button. Rejected plans automatically regenerate with additional context. Output: Approved plans trigger agent execution in the isolated worktree. Rejected plans return to the queue for regeneration.

# List all tasks
parallax list

# Show plan for a specific task
parallax plan <task-id>

# Approve plan and start execution
parallax approve <task-id>

# Reject plan with feedback
parallax reject <task-id> --reason "Scope too broad, limit to auth module"

Step 5. Review the generated pull request (Browser — 2 minutes) Input: A completed task where the AI agent has finished execution and Parallax has opened a PR linked to the original issue. Action: Open the PR link from the dashboard, terminal output, or Slack notification. Review the generated code, run CI checks, and merge if satisfied. Output: A GitHub or Linear pull request with the AI-generated changes, including the issue reference in the PR description and a summary of what was changed.

# Open the PR for a completed task directly
parallax pr <task-id>

# This opens the GitHub PR page in your default browser
# The PR description includes:
# - Link to the original issue
# - Summary of changes made
# - Execution metadata (duration, tokens used, adapter version)

Setup and Tools

Tool Role Cost Parallax CLI Local-first AI orchestrator Free (MIT) Claude Code AI agent adapter (default) API usage ($0.015/1K tokens) OpenAI Codex AI agent adapter (alternative) API usage ($0.01/1K tokens) Google Gemini AI agent adapter (alternative) API usage (free tier available) Git 2.30+ Version control and worktree mgmt Free Node.js 18+ Runtime for Parallax dashboard Free Slack (optional) Bot notifications and approvals Free (Socket Mode) GitHub / Linear Issue tracking and PR management Free tier available

[!NOTE] Parallax runs entirely on your local machine. The only network requests made are from your AI adapter (Claude Code, Codex, or Gemini) to their respective API endpoints, and from Parallax to GitHub or Linear for issue and PR operations. If you use the Slack bot, it also connects to Slack's Socket Mode endpoint, which is a WebSocket connection and does not require a public HTTP server.

The ROI Case

Metric Manual Workflow Parallax Workflow Improvement Bug fix (one file) 12-18 minutes 72-90 seconds 10x-15x faster Feature add (three files) 25-40 minutes 4-5 minutes 5x-8x faster Dependency update 8-12 minutes 45-60 seconds 8x-12x faster Context switching cost High (stash/branch) None (worktree) Eliminated Multi-task batch (12 issues) ~31 minutes 14.5 minutes 2.14x faster Plan approval rate N/A (no plans) 79.4% first-pass Human oversight Human review required Always Plan-only (optional) Reduced overhead Worktree disk overhead ~1.4 GB (4 clones) 348 MB (4 worktrees) 4x less storage AI adapter swap Manual reconfig 2 lines in YAML Instant Audit trail None Full logs + timestamps Compliant

Honest Limitations

Adapter API dependency introduces latency and cost [MEDIUM RISK] Parallax orchestrates locally but delegates code generation to Claude Code, Codex, or Gemini, all of which make API calls to cloud endpoints. This means every plan generation and code execution step incurs network latency and token cost. On our M4 Max with a 200 Mbps fiber connection, plan generation added 8 to 18 seconds of round-trip time depending on Claude Code API response times. Additionally, each task execution consumes tokens: a typical one-file bug fix used 2,500 to 4,000 tokens at $0.015 per 1K tokens, costing $0.04 to $0.06 per task. Over 100 tasks per week, that is $4 to $6 in API costs. Mitigation: use the --dry-run flag to preview which issues Parallax will pull before committing to execution. Batch approve multiple plans during a single review session to minimize context switching. For teams, set a weekly token budget in parallax.yml using the max_tokens_per_run setting to prevent runaway API costs. Consider using Gemini for cost-sensitive tasks since its free tier supports up to 60 requests per minute.
Git worktree branch management requires discipline [LOW RISK] Parallax creates worktrees from the base branch configured in parallax.yml, which defaults to main. When a PR is merged, the corresponding worktree becomes stale. Parallax does not automatically prune stale worktrees after PR merge, so over weeks of active use, the worktree directory can accumulate 50 to 100 stale branches consuming disk space. The git worktree prune command cleans dangling worktree metadata, but the working tree files remain on disk until manually removed. Mitigation: add a weekly cron job or npm script that runs parallax cleanup to remove worktrees for merged PRs older than seven days. Set worktree_ttl_days: 7 in parallax.yml to enable automatic cleanup on parallax start.
Issue quality directly determines output quality [HIGH RISK] Parallax is only as good as the issues it consumes. If your issue tracker contains vague bug reports without reproduction steps, feature requests without acceptance criteria, or tickets with insufficient context, the generated plans will be correspondingly poor. In our testing, issues tagged "ai-ready" that included steps to reproduce, expected behavior, and environment details had a 94 percent first-approval plan rate, compared to 52 percent for issues with only a title and one-line description. Parallax cannot infer intent or fill in missing requirements. Mitigation: establish issue quality standards in your team before enabling Parallax on the full backlog. Use the min_body_length and require_labels filter options in parallax.yml to reject underspecified issues. Create an "ai-ready" label with documented criteria: reproduction steps, expected behavior, affected files, and acceptance criteria. Train your team to write AI-ready issues using Parallax's built-in issue template generator with parallax init-template.

System Prompt Template for Parallax

You are operating inside a Parallax-managed git worktree for task {task_id}.

Worktree context:
- Base branch: {base_branch}
- Worktree path: {worktree_path}
- Repository: {repo_owner}/{repo_name}
- Issue: {issue_title} (#{issue_number})

Task constraints:
- You must only modify files within the worktree directory.
- Do not delete or modify files outside the worktree scope.
- All changes must be committed with a descriptive message referencing the issue.
- Run lint and type checking after making changes: {lint_command}
- If the change requires new dependencies, verify they are compatible with the project's existing dependency versions.

Issue context:
{issue_body}

Behavior guidelines:
- Generate a clear plan before writing code.
- Include the plan as a comment at the top of the first modified file.
- Group related changes into logical commits.
- Add or update tests for any new functionality.
- Do not modify the parallax.yml configuration file.

Automatic post-execution:
- Parallax will commit all changes, push the worktree branch, and open a PR.
- The PR description will include the original issue body and execution metadata.
- You do not need to interact with GitHub directly.

Start in 10 Minutes

Step 1 (3 minutes). Run npm install -g parallax in your terminal. Verify the installation with parallax --version. Create a GitHub personal access token with repo and issues scope and export it as an environment variable with export GITHUB_TOKEN=ghp_your_token_here.

Step 2 (4 minutes). Create a parallax.yml file in your project root with the example configuration above, substituting your repository owner, name, and token variable. Set the adapter to claude if you have Claude Code installed, or codex if you use OpenAI Codex. Tag at least one open issue in your repository with the label you configured in filters.labels.include such as "ai-ready".

Step 3 (3 minutes). Run parallax start from the project root. The dashboard will open at http://localhost:9372 showing your first task. Click the task to view the generated plan. If the plan looks correct, click Approve. Watch the live log stream as the AI agent executes in the isolated worktree. When execution completes, click the PR link to review the generated code on GitHub.

Frequently Asked Questions

Q: Does Parallax send my code to any cloud service?

A: No — Parallax runs entirely on your local machine. The only network requests are from your configured AI adapter (Claude Code, Codex, or Gemini) to their respective API endpoints, and from Parallax to GitHub or Linear for issue and PR sync. If you enable the Slack bot, it connects to Slack's Socket Mode WebSocket endpoint.

Q: Can I use Parallax without Claude Code or Codex?

A: Yes — Parallax supports Claude Code, OpenAI Codex, and Google Gemini as AI adapters. Configure the adapter in parallax.yml with adapter.provider: gemini. You can also define a custom adapter by implementing the adapter interface documented in the Parallax README.

Q: Does Parallax work with Linear instead of GitHub Issues?

A: Yes — set repository.provider: linear in parallax.yml and provide a Linear API key. Parallax supports the same lifecycle for Linear issues including label-based filtering, plan generation, and PR creation linked to the Linear issue.

Q: Can Parallax handle multiple repositories at once?

A: Yes — run parallax start --repo all to process all repositories in the current directory that have a parallax.yml file. Each repository runs independently with its own configuration, worktree set, and concurrency limit.

Q: Do I need a public URL for the Slack bot?

A: No — Parallax's Slack integration uses Socket Mode, which establishes an outbound WebSocket connection from your machine to Slack. No public HTTP endpoint, ngrok tunnel, or static IP is required. The bot token and app token are configured in parallax.yml.

Q: What happens if my AI adapter fails during execution?

A: Parallax captures the exit code and stderr output from the adapter and marks the task as failed in the dashboard. You can retry the task with parallax retry <task-id>, which recreates the worktree from the base branch and regenerates the plan. The failure logs are preserved for debugging.

Q: Can Parallax approve plans automatically?

A: No — by design, Parallax requires explicit human approval for every plan. There is no auto-approve flag. If you need unattended execution, Parallax is not the right tool. Consider a fully autonomous agent for workflows that do not require human review.

Q: Does Parallax support monorepos?

A: Yes — Parallax works with any git repository including monorepos with multiple packages. The git worktree creates an isolated copy of the entire repository, and the AI adapter operates within that worktree. Configure the base branch and any workspace-specific commands in parallax.yml.

Q: Is Parallax compatible with Windows or Linux?

A: Parallax is primarily developed for macOS but has been tested on Linux (Ubuntu 22.04 and Fedora 38) with full functionality. Windows support is experimental through WSL 2. The dashboard and CLI work on all platforms; the Slack Socket Mode and git worktree features are platform-independent.