Skip to content

Getting Started

Ryan Stoffel edited this page Oct 29, 2026 · 1 revision

Getting Started

This page goes from the first launch to a pull request. Install the app first (Installing).

Shortcuts below use Mod, which is Cmd on macOS and Ctrl on Windows and Linux.

1. First launch

A fresh install opens a setup with five steps. The close button, Skip setup, ends it at any point. To start a thread you need at least one agent installed and signed in.

Step What it does
Account Signs in to a Parallax account in your browser, new or existing. Not now skips it. The account links your computers and your phone.
Your agents Looks for Claude Code, Codex, Cursor, Pi, OpenCode, Hermes Agent, and Grok Build on this computer. Each one installed and signed in is turned on. Others offer Install or Sign in.
Bring your history Imports past sessions from the Claude, Codex, and Cursor apps. Each lands in Archived as a thread.
Tour Four slides on what Parallax does.
Start Start a thread, or Explore on my own.

You can do all of this later. Agents are in Settings > Providers (Providers), and importing is in Settings > Threads.

2. Add a repository

Open the add palette from the sidebar: the New project or repository button beside the search box, or New project or Space in the new sidebar. Then pick one:

Choice What it does
New repository Starts an empty repository in ~/.parallax/projects
Local folder Adds a repository that's already on this computer
Clone from GitHub Clones a repository by its owner/name or link

The same palette starts a Project or a Space.

3. Start a thread

Press Mod+N, or the New thread button, and pick the repository. Then:

  1. Type the task in the composer. You can paste images and attach files.
  2. Pick a model. The model decides which provider runs the thread.
  3. Pick an Access level. The default, Auto-accept edits, lets the agent edit files and asks before anything else.
  4. Press Enter.

The thread works in a new git worktree on its own branch, so your checkout stays as it is. A title and a branch name arrive a few seconds after it starts. Threads covers the composer, worktrees, and every option.

4. Follow it

The thread's row in the sidebar shows its state: Working with a timer, Needs you, Done, or Failed.

Needs you means the agent is asking for approval. The request shows in the thread with Approve, Always allow, and Deny, and a box to tell the agent why or what to do instead.

Messages you send while it works wait in a queue and go after the current turn. Mod+Enter steers the running turn instead.

5. Review the diff

Press Mod+Alt+B to open the side panel, then open Changes. It shows every turn's changes together (All turns), or one turn at a time (Turn N). Edit from here goes back to before a turn, with or without its files.

A thread with the diff of its three files in the side panel

6. Open a pull request

Pull requests go through the GitHub CLI, gh, on the computer that runs the thread. Set it up once in Settings > Source control:

  1. If gh isn't installed, choose Install. Parallax puts its own copy in ~/.parallax/tools/gh.
  2. Choose Sign in. Parallax shows a one-time code with Copy and Open GitHub.
  3. Enter the code on GitHub. The row then says Signed in as @your-login.

Then open Thread details from the thread's top bar. Its Git section has Commit, Push, and Create PR. Create PR needs an origin remote and the thread's commits. It pushes the branch and opens a pull request against the repository's default branch.

The pull request shows in the side panel's Pull requests view, and its checks show on the thread's row. Mod+Shift+P opens it on GitHub.

Next

  • Threads: queued messages, checkpoints, forks, and the side panel
  • Providers: every agent, sign-in, API keys, and usage
  • Projects: a coordinator that splits a feature across several threads
  • Hosts: run threads on another computer

Clone this wiki locally