Guide / using Phosphor
Daily work
Everything after setup: run several lanes, steer the agent, review and merge its work, and use artifacts, routines, and skills. Each section links to its reference.
Lanes and the home screen
Every chat is a lane: one agent, usually on its own branch and worktree. The sidebar lists lanes by project, with their status, branch, and a PR chip once there’s a pull request.
- Home (New in the sidebar) sorts the lanes that need something into columns: Waiting on you, Ready to merge, Needs a push, In review, and Running. Below that, a ledger shows what the project has spent, its tokens, and how much memory the live lanes use.
- Find a lane with the magnifier in a project’s header. It matches title, branch, and PR number.
- Right-click a lane to pin it, give it a marker, open its pull request, suspend it to free memory, fork or clone it, export it as HTML, copy its spend, or delete it. Double-click to rename. Drag rows to reorder them.
Branches and worktrees
The new branch box under the home composer decides whether a chat gets its own branch and worktree. It’s on by default and branches off trunk. Turn it off for a quick question, or to keep working on the branch that’s already checked out.
The branch control in the top bar searches branches, switches between the main checkout and worktrees, creates a worktree from a base you pick, pulls trunk, and updates a worktree from trunk when it falls behind. Deleting a lane that’s alone in its worktree offers to remove the worktree too.
Talk to the agent
- While it works: Enter queues a steering message, delivered after the current tool calls. Option+Enter (Alt+Enter) queues a follow-up for when it finishes. Esc stops the turn.
- @ searches the workspace and adds a file reference.
- Images: paste or drag them in. Click one to mark it up with boxes, arrows, and text before sending.
- !command runs a shell command and adds its output to the context. !!command runs it without sending the output to the model.
- / lists commands from pi, your prompt templates, and your extensions.
- Rules · MCP next to the attach button turns CLAUDE.md and AGENTS.md on or off for the lane, and enables or disables MCP servers.
Drafts, attachments included, survive switching lanes and quitting. Cmd/Ctrl+Shift+X opens a taller field for long prompts.
Review what it did
- The transcript: each tool call is a row you can expand for its arguments and output. Edits open as diffs. Cmd/Ctrl+F searches the whole session, tool output included.
- Changes: every file the lane changed, with its diff. Revert puts a file’s working copy back.
- Files: an explorer and an editor with tabs, search, and save.
- Terminal: tabbed terminals for the lane’s folder.
Panes open from the top bar, one at a time beside the chat. Drag the divider, dock the pane left or right, or make it fullscreen. Each lane remembers its own layout.
Models, thinking, and context
- Model menu: every model you’re signed into, searchable, with stars and recents. Switch mid-session and the conversation carries over.
- Thinking: pick the level for the next turn, from off to max, as far as the model supports.
- Context meter: how full the context is, tokens and cost, an estimate of what’s filling it, and your Claude or ChatGPT plan usage.
- Compaction: sessions compact at a shared context budget, 200k tokens by default. Change it in Settings → Agent, or compact now from the lane’s ⋮ menu.
Running low on a plan? Move the lane to another one. Context meter reference
Pull requests and merging
A worktree lane is told to commit on its branch and open a pull request when the work is done. Phosphor itself only reads PR status, through the gh CLI: number, state, checks, and review. It never pushes or opens a PR for you.
To merge, use Merge on a Ready to merge card, the branch control, or the project menu. The merge runs locally with git and walks you through a dirty worktree first. A worktree lane that has fallen behind main shows Update under Needs a push.
Split work across agents
With the Subagents package installed, ask the agent to split independent work, or enable Swarm for standing authorization to delegate when useful. The current-work summary distinguishes parent activity from reported child activity. Open the dockable Subagents pane for tasks, bounded activity and results. Missing status is unavailable, not proof that work finished. Turning Swarm off does not stop existing children.
Artifacts
Ask for a plan, a doc, a diagram, a chart, or an HTML page as an artifact. It opens in the Artifacts pane next to the chat and keeps every version, even after the session compacts. The Artifacts page in the sidebar lists every artifact from every session. HTML artifacts run isolated, with no network access.
Resume, rewind, and fork
- Old sessions reopen from the sidebar with their full history.
- Rewind to here on one of your messages, or Esc Esc for a picker, branches the chat from just before it and puts your text back in the composer. The old version folds away.
- Fork and Clone in a lane’s menu make a copy and keep both.
Routines
Routines in the sidebar runs a task on a schedule: hourly, daily, weekly, monthly, once, or a cron expression. Each run starts a fresh lane with the model you picked. Routines run on your machine while it’s awake, not in the cloud. Make routine… in a lane’s menu drafts one from that lane.
Skills
A skill is a written procedure the agent can follow. The Skills page in the sidebar lists your own and the ones your packages bring. Create, import, or export your own there, or add a reviewed one from discovery.
Settings worth knowing
- Keyboard: Cmd/Ctrl+K opens the command palette, Cmd/Ctrl+N starts a session, and Cmd/Ctrl+B toggles the sidebar. Settings → Keybindings lists the rest.
- Appearance: light, dark, or follow the system.
- Agent → Directives: what Phosphor adds to every lane’s system prompt, shown in full before it’s sent.
- Optimization: Headroom, an optional local proxy that restructures large JSON tool results before they enter the context. Its Advisor reads your session files and settings and points out what’s worth changing.
- Advanced → Maintenance: finds worktrees of lanes that already landed and reports how much space they hold. It deletes them only if you ask.
- Send feedback at the bottom of the sidebar opens a prefilled GitHub issue with your rating and notes. Nothing about your code or sessions is attached.