Skip to content

Threads

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

Threads

A thread is one agent working on one task. It runs on one computer, on one provider, in its own folder, and keeps its conversation, checkpoints, and pull requests together.

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

Where a thread works

Settings > Threads > Workspace sets where a new thread in a repository works. The New thread screen can pick the other one for a single thread.

Workspace Folder Branch
New worktree (default) A git worktree under ~/.parallax/worktrees/ Its own, parallax/<name>
Local checkout The repository itself The branch you have out, or one you pick

A new worktree starts from the ref its From button shows on the New thread screen. Until you pick one, that's the first of origin/develop, develop, origin/main, and main the repository has, else your checkout's branch. Uncommitted changes in your checkout aren't in it.

A thread with no repository reads as No repo. It gets a scratch repository of its own, and its agent can still run commands and edit files on its computer. Mod+Shift+N starts one.

Delete removes the thread, its worktree, and its branch. Archive only moves it to Archived.

A thread is archived on its own once its linked pull requests have merged, unless you messaged or unarchived it after the merge. With Settings > Storage > Clean up merged worktrees on, the default, Parallax then deletes its worktree and branch if they hold nothing the merge didn't keep. The thread stays, and a new message makes the worktree again.

The composer

The composer is the box at the bottom of a thread. Below the text it holds the model, reasoning, and Access pickers, Attach files, and Send or Stop.

Model

The model menu lists the models of every provider turned on for that computer, with a rail to filter by favorites or provider. A provider with more than one account gets an account chooser above its models. You can pick another model, even another provider's, for the next message.

Which models show, and in what order, is set per provider in Settings > Providers (Providers).

Reasoning

The gauge sets reasoning effort: Low, Medium, High, Extra high, or Max. Where the model offers them, the same menu sets its context window and Fast mode (Claude Code) or Speed (Codex). Cursor has no effort menu, since its model ids carry the effort.

Access

Access sets what the agent may do without asking. The levels are the same for every provider (0027, 0054).

Level What it does
Supervised Asks you before commands and file changes.
Auto-accept edits Accepts file edits, asks before other actions. The default.
Auto The provider approves routine actions for you and blocks the risky ones.
Plan Explores and writes a plan without editing files.
Full access Runs commands and edits files without asking.

Each provider offers the levels it can honor:

Provider Supervised Auto-accept edits Auto Plan Full access
Claude Code Yes Yes Yes Yes Yes
Codex Yes Yes Yes No Yes
Cursor No Yes Yes Yes Yes
OpenCode Yes Yes No Yes Yes
ACP agents Yes Yes If the agent has the mode If the agent has the mode Yes

Plan is a legacy level. The picker lists it only when Settings > Threads > Legacy Plan mode is on, or the thread already started in Plan. Settings > Threads > Permissions sets the level a new thread starts with. You can change the level while a thread runs.

For ACP agents, Parallax answers the agent's permission requests by level. It can only answer what the agent asks, so an agent whose own settings allow everything isn't limited by Supervised.

Approvals

When the agent asks, the thread shows the request with Approve, Always allow, and Deny, and its row says Needs you. A box under the request takes a note to the agent, such as why you denied it or what to do instead. A plan waiting for approval shows Approve plan and Keep planning.

Commands, files, and threads

  • / at the start of a word lists the composer's commands and the agent's own commands and skills.
  • @ lists the thread's files, and other threads to attach (see Attaching threads).
  • Up and Down in an empty composer step through earlier prompts.

Queued messages and steering

A message sent while the agent works waits in a queue and goes as the next turn. The queue survives a plxd restart (0048).

The queue shows over the composer as Queued with a count. Each message can be edited, moved up or down or dragged, sent now with Steer now, or cancelled.

A steer goes into the turn that is running instead of after it. Mod+Enter in the composer steers. How a provider takes a steer depends on what it supports:

Provider Steer
Claude Code, Codex Joins the running turn
Cursor, OpenCode, ACP agents Stops the running turn and runs next

After plxd restarts, as after an update, a thread's queue shows Paused and waits for Resume. Settings > Threads > Continue threads after restarts, set per computer, tells a thread that was working to continue where it left off. Its queue still waits for Resume.

Checkpoints and revert

Parallax checkpoints every turn. A checkpoint is a git ref, refs/parallax/checkpoints/<thread>/<turn>, written without touching your index or branch. A thread's refs are deleted with the thread (0062).

The side panel's Changes view shows All turns or one Turn N. A stopped turn's changes show too.

Edit from here goes back to before the turn shown. It asks Edit from here? with two choices:

  • Revert files too: rolls back the conversation and restores the files in the thread's worktree.
  • Revert and keep changes: rolls back the conversation and leaves the files as they are.

Either way the turn's prompt goes back into the composer. Limits:

  • Claude Code and Codex threads can revert. Cursor, OpenCode, and ACP agent threads can't.
  • Reverting files needs a worktree of the thread's own, so a Local checkout thread reverts only the conversation.
  • A thread can't revert while a turn runs.
  • A Claude Code thread can't go back past a turn that ran before it moved to another provider and back.

Forking

A fork is a new thread that starts from a turn of another, which keeps going unchanged (0050).

  • Fork from here, in a message's hover row, forks at that message's turn.
  • Fork… in the thread's menu forks at its latest turn.

Both open Fork into a new thread: keep the thread's model, or pick another, which may be another provider's. A turn still running can't be forked.

The fork gets a new worktree cut from the parent's latest commit, or shares a Local checkout thread's checkout. Its history is copied up to the fork turn, and its agent starts with the first message you send.

A Claude Code or Codex fork at the latest turn, on the same provider and account, keeps the agent's full context, tool calls included. Any other fork gets the conversation so far as text, without tool calls, cut to about the last 64 KiB.

The side panel

Mod+Alt+B shows or hides the side panel. Its views open as tabs. The + after the tabs lists them, and each view's letter opens it while the panel has focus (0064).

View Key Shows
Changes D The thread's diff by turn, and Edit from here
Knowledge K What a Project, or a thread in a repository, keeps from its agents
Agents A Subagents this thread starts
Terminal T A terminal in the thread's folder
Files F The thread's folder
Device M iOS Simulators and Android Emulators
Pull requests P Pull requests the thread opened or linked, each also as a #n tab

Terminals run in plxd, not the app, so they keep running and keep their history after the window closes. Mod+J shows or hides a terminal drawer under the thread.

Browser

The browser is apart from the views. The globe button in the top bar, or Mod+Shift+B, swaps the side panel for it (0076).

  • The agent can open and drive tabs in it, and you can take a tab over.
  • Each thread keeps its own tabs. Sign-ins and extensions are shared by every browser.
  • Chrome extensions install from a Chrome Web Store page or link, or from an unpacked folder, in Settings > Browser > Extensions.

Thread details

The Thread details button in the top bar shows the thread's computer, Open in, its Space, Git status with Commit, Push, and Create PR, its linked pull requests, and the threads it started or came from. Create PR uses gh on the thread's computer (Getting Started).

Attachments

Paste, drop, or use Attach files.

  • Images go to the agent as images, at most 10 per message (0026). One larger than 2000 px on its long edge is sent smaller.
  • Other files are saved on the thread's computer in ~/.parallax/uploads/, up to 1 GiB each. The message ends with an Attached files: list of their paths, and the agent reads them with its own tools (0071). Images are saved there too, so the agent has a file to work with.

The transcript shows each attached file as a card above the message.

Searching and attaching threads

The sidebar's search and the command menu (Mod+K) find threads by title and by what was said in them. The command menu shows the line that matched (0047).

To give the agent another thread as context, type @ and pick it, or drag its sidebar row onto the composer. A message takes up to 8 threads. Each goes to the agent as a summary of its conversation, without tool calls, up to 32 KiB, as it stands when the message is sent. Agents can also search and read threads on their own computer with the thread_search and thread_read tools.

Naming

A new thread starts at once on a branch named from the first words of its prompt. A few seconds later a model writes its title and a better branch name from the first message (0058).

  • Settings > Threads > Naming model picks the model and its effort. The default is Codex gpt-6-luna at Low. Only Claude Code and Codex models can name threads.
  • Naming runs on your own sign-in for that provider, one small call per thread.
  • Rename in the thread's menu sets your own title. A title you set is never replaced.
  • The branch is renamed only while it hasn't been pushed.

Usage limits

A thread can wait out a usage limit and continue on its own (0049). It's off by default.

  • Settings > Threads > Resuming threads > Resume after a usage limit turns it on for a computer.
  • Resume after usage limits, in a thread's menu, overrides that for one thread.
  • A Project's threads always resume.

A waiting thread's row says Resumes and the time. The thread shows Usage limit reached with Resume now and Cancel. It resumes up to a minute after the limit resets, with "Your usage limit has reset. Continue where you left off." When the provider reports no reset time, as Cursor doesn't, it tries again after 15 minutes, doubling each time up to 4 hours.

An API key can also take over when a subscription runs out (Providers).

The sidebar

Two sidebars ship. The classic one is the default. Settings > Beta > New sidebar switches to the new one, per computer (0033, 0075, 0087, 0090).

Classic sidebar

  • Head: search, the repo filter (All threads, No repo, then each repository), New project or repository, and New thread.
  • List: threads pinned with Pin to top, then every other open thread, most recently active first. A thread rises when you prompt it and when it finishes. A Project that needs you, or matches a search, shows here too.
  • Drawers: Working, Snoozed, Archived, and Projects, folded until opened.
  • Footer: Pull requests, Usage, and Settings.

A row shows the repository, the status or age, the title, the branch, uncommitted and unpushed changes, pull request checks, the computer, and the provider's logo. Threads that another thread started don't get rows of their own.

Status Means
Working The agent is on a turn, with how long it has run
Needs you A request waits for your answer
Done It finished since you last opened it
Failed It failed since you last opened it
Resumes, Waiting It is waiting out a usage limit

The repo filter's menu also sets the view: Group (None, Repo, Day), Rows (Full, One line), and Archive finished threads after (Off, 12h, 1d, 3d, 1w). Auto-archive skips pinned threads and threads you haven't seen.

A row's menu, from its actions button or a right-click, holds Open side by side, Pin to top, Mark as unread, Rename, Archive, Fork…, Resume after usage limits, and Delete…. The snooze button on a row offers In 1 hour, In 3 hours, Tomorrow, Next week, or a custom time. A snoozed thread comes back early if it needs you.

Settings > Threads > Sidebar turns off the Working drawer and shows Archived all at once instead of 25 at a time.

New sidebar

The head has New thread, New project or Space, Search, and Projects as rows, then More, which folds open to Pull requests and Usage. Settings > Beta chooses which of Projects, Pull requests, and Usage sit in the head. Under them, Pinned lists pinned Projects and Spaces with their status. Projects no longer appear in the thread list. See Projects and Spaces.

Keyboard shortcuts

Settings > Keybinds changes any of these.

Shortcut Action
Mod+K Open command menu
Mod+P Go to file
Mod+Shift+F Search project contents
Mod+N New thread
Mod+Shift+N New thread without a repo
Mod+S Toggle sidebar
Mod+Alt+B Toggle side panel
Mod+Shift+B Open browser
Mod+J, Ctrl+Shift+` Toggle terminal
Mod+Alt+O Open folder in default app
Mod+, Open Settings
Mod+Alt+U Open Usage
Mod+F Find in thread
Mod+Shift+P Open pull request on GitHub
Mod+Alt+Up Go to parent thread
Mod+Alt+Right, Mod+Alt+Left Next or previous sibling thread
Ctrl+1 to Ctrl+4 (Ctrl+Shift+1 to 4 off macOS) Focus thread 1 to 4 of a side-by-side split
Mod+[, Mod+] Back and forward through opened threads

These are fixed:

Shortcut Action
Enter Send, or queue while the agent works
Shift+Enter New line
Mod+Enter Steer the running turn
Escape Stop the running turn
Mod+1 to Mod+9 Open that sidebar row
Alt+Down, Alt+Up Next or previous row that needs you

Settings > General > Send shortcut can make Mod+Enter send and Enter start a new line. Steering then moves to Mod+Shift+Enter.

Clone this wiki locally