Getting Started

Installation

We strictly recommend installing Parallax globally. You can use npm or pnpm depending on your package manager:

pnpm i -g parallax-dev
# or
npm install -g parallax-cli

Note: You can run it via npx parallax-cli, but installing globally gives you a faster, more permanent bin alias.

Basic Requirements

You'll need to sign into Gemini CLI first:

pnpm i -g @google/gemini-cli
# Follow the instructions to sign in
gemini

First Run

Open any codebase terminal and simply type:

parallax

You'll drop into an Ink-powered terminal UI. Type a prompt like "Find where the authentication logic lives, and tell me if it uses JWTs" and the agent will use its native tools to hunt down the answer.

Customizing Behavior

Parallax reads context mostly on its own, but you can explicitly guide it by creating a PARALLAX.md file in your root folder.

Don't want to write it yourself? Just run /init inside Parallax. The agent will analyze your project structure and write out an initial set of context instructions for you, which you can adjust later.

Essential Shortcuts

• Ctrl+C: Graceful exit (it will ask to abort any running generators before quitting).
• Esc: Exit any interactive pickers.
• Shift+Tab: Toggle "YOLO mode" (if you want to disable automatic safety boundaries for file overwrites or command executions).
• Ctrl+O: Toggle verbose tool output on or off.

CLI Flags & Headless Execution

Parallax is designed to fit seamlessly into automated scripts and workflows via its arguments.

Flags

• --yolo: Automatically approve safety boundaries from startup.
• --verbose: Boot with verbose tool output enabled.
• -s <id> or --session <id>: Launches Parallax and immediately restores the history of the given session ID.

Headless Mode

If you invoke Parallax with an inline prompt (e.g., parallax "Summarize the git status"), the interactive TUI is bypassed entirely. Parallax will boot in Headless Mode, executing the request silently in the background.

• Tool logs are completely suppressed.
• YOLO mode is implicitly enforced so it doesn't block waiting for input.
• Output: It prints only the agent's final text response to stdout.

To easily pass context to headless executions, you can combine flags. For example: parallax -s [session-id] "Create a commit based on what we just discussed".

If you prefer to capture the underlying tool executions computationally rather than the plain text string, append the --json flag. The agent will run headlessly, but cleanly pipe the complete turn execution flow (blocks, tools, results, reasoning) as a raw structured JSON array to stdout.