Agent Threads & Multi-Turn Conversations

A thread is a persistent, multi-turn conversation with your coding harness about your code. Where an inline edit is a single instruction that runs once and exits, a thread keeps its full transcript across messages. You can ask what a module does, follow up on specific functions, inspect implications across related files, and instruct the agent to make edits across as many files as the conversation requires.

Threads live in the right sidebar under the Threads tab, alongside References, Symbols, Calls, and Search.

Starting a Thread

You can start a thread in four different ways depending on your current focus:

When anchored to code, the thread opens as a draft showing the reference path:lines beneath the title. Clicking this citation jumps your editor directly to that file and line range.

Nothing is saved to disk until you dispatch your first message. The code anchor provides context to start the conversation, but does not constrain the harness: your agent can read and modify any file in the workspace.

The Conversation Experience

Type your prompt in the compose box and press Enter to send (Shift+Enter for a newline). As the agent processes your request, px0 streams updates in real time over Server-Sent Events (SSE):

• Tool Steps: A collapsible list showing real-time agent actions, such as Read calc.go or Edit server.go. The list remains expanded while the turn is actively running and collapses once complete.
• Live Reply: The harness’s written answer streams in with rich formatting, including Markdown headings, bullet lists, inline code, and syntax-highlighted code fences with one-click copy buttons.
• Changed Files: When a turn touches the repository, px0 displays interactive file chips for every modified file. Clicking a chip opens the file in a new editor tab. Open tabs automatically reload in place as soon as a turn completes.
• Stopping a Turn: If you need to halt an in-flight run, click Stop. The harness process group is canceled cleanly, and any modifications already written to disk are preserved.

Each message continues the same conversation context. Follow-ups like “Can you add unit tests for that edge case?” or “Does this break the HTTP handler?” have access to the full conversation history.

Worktree Turn Snapshots & Safe Reversion

Starting in version 0.1.20, px0 automatically isolates working-tree edits on a per-turn basis using lightweight Git tree snapshots:

1. Pre-Turn Snapshot: Before launching the coding harness, px0 records an anonymous Git tree object (beforeSHA) representing current working-tree files without touching branches, index, or HEAD.
2. Post-Turn Snapshot: Once the turn finishes, a second snapshot (afterSHA) captures the resulting files.
3. Turn-Level Diff Review: Click any changed file chip inside a turn card to inspect the exact diff produced by that specific turn, separated from prior edits or subsequent modifications.
4. 1-Click Turn Revert: If an agent turn introduces bugs or an incorrect approach, click Revert Turn (POST /api/threads/revert). px0 restores only the files modified during that turn back to their beforeSHA state. The conversation transcript and history remain fully intact with the turn flagged as reverted, so you can re-prompt or steer the harness in a new direction.

Threads in GitHub PR Reviews

When conducting a GitHub Pull Request Review, threads include an explicit review scope selector above the message composer:

• Whole PR: Scopes context to the entire pull request from merge-base to PR head.
• My changes: Scopes context strictly to reviewer modifications made locally on top of the PR.
• Selection: Anchors context directly to the selected lines of code.

px0 automatically defaults the initial scope based on where the thread originated: the active editor diff section (PR changes vs. Your changes), the sidebar PR changes toggle, or the full PR. You can switch scope chips at any time before sending a turn; px0 saves the exact diff range as a file and provides it to the harness so the agent reads the full scope rather than guessing.

Mid-Thread Model & Harness Switching

Beneath the transcript, the Model row displays the active coding harness and model selector. You can switch models or harnesses in the middle of an ongoing thread:

• If you switch to another harness with native session capabilities, px0 starts a fresh session and seeds it with the prior transcript.
• If you switch models within the same harness, the session continues seamlessly.

Session Continuity & Harness Support

A thread turn runs as a dedicated child process. To preserve conversation history across turns, px0 uses two distinct continuity modes depending on the harness:

For harnesses supporting token-level streaming (claude, agy), px0 parses stream-json events in real time to stream text deltas and tool invocation labels directly to the browser.

Inline Edits and Batch Edits as Threads

Inline code edits (Editing with Coding Agents) share the same sidebar pane:

1. Comment Box Integration: Triggering an inline edit with Alt+E opens a comment box at the top of the Threads pane.
2. Comment Queuing: Press Enter to Add comment to stage multiple edits across files, or press Ctrl+Enter (Cmd+Enter on macOS) to Apply now.
3. Batch Execution: When multiple comments are staged, click Apply all (N) (Ctrl+Shift+Enter / Cmd+Shift+Enter) in the Batch control bar to execute them together.
4. Recorded as Threads: Every applied edit or batch is automatically saved as a thread, labeled inline or batch in the thread list. You can open it later to inspect what changed or ask follow-up questions.

Unlike open-ended conversations, inline edit threads enforce overlap protection: dispatches modifying lines that an active inline edit is currently writing will be rejected with an HTTP 409 conflict to prevent corrupted merges.

Thread List & Persistent Storage

The Threads tab provides an overview of all conversations in the workspace:

• Sorting & Metrics: Threads are sorted by most recent activity, showing the code anchor, total turn count, and timestamp.
• Status Indicators: A spinner indicates an active turn, while a warning icon marks turns that failed. A pulsing dot on the Threads tab alerts you when a background turn completes while you are viewing another tab.
• File Filter: Click This file to filter the list to threads started in the currently active document.
• Thread Deletion: You can remove threads at any time:
  • Click the trash icon in the thread detail header.
  • Hover over any thread in the thread list and click its inline trash button.
  • Focus a thread in the list and press Delete or Backspace.
  • Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Threads: Delete Current Thread.
• REST Endpoints: Backend deletion (POST /api/threads/delete) and cancellation (POST /api/threads/cancel) accept thread IDs passed either via JSON body ({"id": "..."}) or URL query parameters.
• Transcript Persistence: Threads are stored locally on the host machine at ~/.px0/threads/<workspace-hash>.json (or $XDG_CONFIG_HOME/px0/threads/), never inside your git working tree. Files are written atomically with restricted 0600 permissions.
• Restart Recovery: Threads survive server restarts. If px0 is terminated while a turn is running, the turn is cleanly marked as interrupted upon reload.