Skip to content

Projects

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

Projects

A Project is for work bigger than one thread. It has a coordinator, an agent that plans the work and starts a subagent for each piece in its own worktree. Subagents land their work on one integration branch, and you review the result as one pull request. The coordinator answers routine questions itself and brings you what needs you.

A Project needs a repository. For a group of threads with no repository, use a Space.

A Project's coordinator chat beside its status panel

Start a Project

  1. Open the add palette: New project or repository in the sidebar's head, or New project or Space in the new sidebar. Choose New Project. Mod+K's New Project opens the same form.
  2. In Create Project, set:
    • The icon and name. The name defaults to the repository's folder name.
    • Workspace: the repository, on any of your computers. The Project lives on that computer.
    • Autonomy: who answers subagents' questions. See Questions and autonomy.
    • Full access: on by default. See Permission mode.
  3. Choose Create Project, then send your first message. Sending it starts the coordinator.

Every message you send in the Project goes to the coordinator. Send a feature or a bug and it starts a subagent for it without waiting for a go-ahead. You can send several back to back.

The coordinator

The coordinator writes no code. It reads the repository's agent instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING), plans, starts subagents, reviews their work, keeps the status board, and curates memory. Any change to a file is a subagent's.

  • Its instructions are pinned. Parallax gives the coordinator its rules on the provider's system-prompt channel every time its CLI starts, so they survive context compaction (0078).
  • It outlasts its session. When a provider session can't be resumed, Parallax starts a new one from the Project's state: the brief, memory, board, open threads, questions, landing queue, and your last 10 messages. The chat shows a divider, "New session, picked up from the Project's state". Fresh session in the Project's menu starts one on purpose (0079).
  • Subagents wake it. When a subagent finishes, starts, or asks a question, Parallax sends the coordinator a message that begins "Parallax, not the user". Events within 2 seconds of each other arrive as one message. After 100 wake-ups in a row with no message from you, wake-ups pause until you write (0025).
  • Stop stops only its turn. Its subagents keep working.

Subagents

Each subagent is a full thread (0042):

  • It works in its own worktree and branch, cut from the integration branch's tip, so it sees work that landed before it started.
  • It runs in the Project's permission mode, on any provider that offers that mode.
  • It shows only inside the Project, never in the sidebar's thread list.
  • You can open it and message it directly.
  • The Project's Agents tab lists subagents by Needs you, Working, Done, and Failed, and has a box to start one by hand. A subagent you start there wakes the coordinator too.

At most 10 of a Project's subagents run at once. The rest wait in a queue (0046).

Subagents run on the computer the Project is on. Running them on another of your computers is designed in 0057 but not turned on yet.

Permission mode

A Project's agents run without asking for each command, so the Project keeps working while you're away.

Full access Mode What it means
On (default) Bypass Permissions Agents run commands and edit files with no permission checks
Off Auto The provider's own check decides. What it won't decide waits in Needs you

Agents on Cursor, Grok Build, Hermes Agent, Ollama Cloud, OpenRouter, and local models need full access. To turn it on later, choose Full access… in the Project's menu. You can't switch back.

Agents can edit files, run commands, use the network, and push with your credentials. Bypass has no second check. The coordinator's instructions tell it to open or merge a pull request only when you ask, but nothing enforces that.

Questions and autonomy

A subagent asks with ask, states the assumption it will work on, and keeps going. It never waits for an answer (0043).

Autonomy The coordinator answers
Ask me Nothing. Every question waits on you
Routine (default) What memory or the code clearly settles. It asks you the rest
Full Everything it can justify

An answer that differs from the assumption reaches the subagent as a message. Change the level with Autonomy… in the Project's menu.

The integration branch

Each Project has one integration branch, parallax/<slug>, named from the Project and cut from its base branch (0045). The branch picker under the coordinator's composer sets the base branch.

  1. When a subagent's review passes, the coordinator queues it to land.
  2. A landing waits for your approval unless the Project lands automatically.
  3. Parallax squash-merges the subagent's branch as one commit, titled with its task's first line.
  4. Parallax runs the Project's checks command in the integration worktree, with a 30-minute limit. The coordinator proposes the command once, and you confirm or edit it before it runs.

On a conflict, Parallax sends the work back to the subagent to merge the tip and resolve, then queues it again. Red checks take the work off the branch and send the subagent the output. A second failure goes to Needs you.

The Project ends as one branch. You open one pull request from it into the base branch. The coordinator opens or merges a pull request only when you ask it to.

The desktop app has no buttons yet for approving a landing, confirming the checks command, or opening the Project's pull request.

Memory and shared context

Each subagent starts with what the Project already knows (0044).

Scope Holds
You Your preferences, across every Project and thread
Repo Facts about one codebase
Project The brief, decisions, knowledge documents, the board, and history
  • A subagent's first message carries the brief and an index of memory entries, up to 8 KiB. It reads full entries with memory_read.
  • Subagents propose entries with memory_propose. The coordinator checks each one and saves it with memory_write or drops it.
  • Tell the coordinator "remember X" and it saves it at once.
  • The shared context folder lives outside the repository, so agent notes stay out of your git history and diffs (0005).

The Knowledge tab shows, in order: proposals under To review (Accept, Edit, Dismiss), the Brief, Memory grouped as Preferences, Conventions, Decisions, and Gotchas, Unused or stale (Keep, Retire), and Documents. Click an entry to edit, Promote, or Delete it. The box at its foot takes a change in plain words, such as "we moved off Jest, use Vitest". The coordinator answers with proposals for you to accept or dismiss.

An entry no agent has read in 60 days moves to Unused or stale.

Follow a Project

The side panel pins two tabs for a Project (0083):

  • Project: the open thread count, chips for how many are working, need you, or wait for review, the coordinator's status board, Running (subagents working or waiting on you, with a question to answer in place), then finished subagents by day. The book button opens All files, the shared context folder.
  • Knowledge: memory, as above.

Over the composer, the agents bar shows the subagents at work. A new Needs you item sends a notification, "Needs you: …", with Open Project.

Where Projects show

Sidebar Where a Project is
Classic (default) The Projects drawer at the bottom. One that needs you, or matches a search, shows atop the list
New (beta) Only under Pinned, and on the Projects page

Turn the new sidebar on in Settings > Beta > New sidebar (0090). The Projects page shows every Project and Space as cards, with a search, an All, Projects, and Spaces filter, and a sort (Recent, Name, Created). Pins are kept on this computer. Mod+K opens any Project in either sidebar.

The Project's menu

Open it from a Project's card or row with its actions button or a right-click.

Item Does
Pin / Unpin On the Projects page and Pinned only
Rename… Renames the Project
Change icon… A Lucide icon and a color, or Upload image
Full access… Shown while the Project is in Auto
Autonomy… Ask me, Routine, or Full
Fresh session Starts the coordinator's next message in a new session
Delete… Stops and deletes the Project's agents with their transcripts, worktrees, and branches. The integration branch stays

A Project's name and icon are stored on its computer, so every app and device attached to it sees the same ones (0032, 0038).

The coordinator's Parallax tools

Threads get Parallax's MCP server (0041). In a Project, the coordinator and subagents get more (0019).

Tools Who Use
thread_list, thread_read, thread_search, thread_launch, thread_fork, thread_send, thread_wait, thread_interrupt, thread_update Every thread Start, read, message, and stop threads
read_context, write_context Coordinator and subagents The shared context folder
ask Subagents Ask a question and keep going
answer, escalate Coordinator Answer a question, or pass it to you
land, checks_propose Coordinator Queue a landing, propose the checks command
board_add, board_update, board_remove Coordinator The status board in notes.md
memory_read, memory_propose Coordinator and subagents Read memory, propose an entry
memory_write Coordinator Save an entry

Schedules, webhooks, pull request watches, and delegation tools are on Triggers.

Clone this wiki locally