Repository navigation
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.
- 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.
- 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.
- 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 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.
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.
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.
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.
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.
- When a subagent's review passes, the coordinator queues it to land.
- A landing waits for your approval unless the Project lands automatically.
- Parallax squash-merges the subagent's branch as one commit, titled with its task's first line.
- 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.
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 withmemory_writeor 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.
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.
| 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.
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).
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.
Start
Using Parallax
Your computers
Maintenance
Contributing