Threads
A thread is one task for one agent. This page shows you how to start a thread, follow it, and manage it while it sits idle.
What a thread is
Each thread has:
- one agent (Claude Code, Codex or OpenCode) working on one task;
- its own sandbox, a sealed container on the runner you chose;
- its own copy of your repository, cloned into that sandbox;
- its own branch, when the project is on GitHub.
Threads don't share files, so you can run several at once. Each one keeps its own history and changes until you delete it.
Start a thread
- Press New thread in the sidebar (⌘N).
- Pick a project under Select project. You can choose a repository from GitHub or This Mac, paste a GitHub URL, or open a folder. Without a project, the thread gets a scratch workspace.
- Choose the agent under Harness.
- Optionally set Skills & MCP, the model, effort and mode. See Agents and accounts.
- Type your task and press Enter, or click Send.
Attach images or files with the attach button. You can also drop them on the window.
When you paste three or more lines, or a long passage, Threadrun attaches it as Pasted text instead of putting it in the box. The card shows its first lines and its length; click × to remove it. The agent gets the full text with your message. Shorter pastes go in the box as usual.
To change where new threads run, use the Run on picker. Each thread remembers its runner. See Runners.
The thread view
The header shows the title, the thread's state (Idle, Working, Failed or Closed), the agent and project badges, and the totals.
The toolbar has:
- ↑ Top and ↓ Latest, to move through a long chat;
- Files and Activity, to open the side panels;
- Phone, to follow the thread from your phone (see Phone access);
- ⬇ Copy to this Mac, to copy the output to your computer (see Review and ship);
- Delete.
The timeline shows your messages, the agent's replies, each tool step, plan checklists, and subagents. A subagent carries a Subagent badge, and its own steps are nested under it.
Replies are formatted as they arrive: headings, lists, tables, quotes, code blocks and links. A reply that is JSON is shown pretty-printed, and a diff is shown in color. Click a link to open it in your browser. Click a file path in a reply, such as src/main.rs, to open that file in Files.
Totals show the tool calls, input and output tokens, cache reads and writes, and cost. A cost appears only when the agent reports one. A context meter shows how full the agent's context window is; it updates as the agent reports it (OpenCode reports at the end of each turn, Claude Code and Codex as they go). It turns amber at 75% and red at 90%.
The header shows the title, the state, the agent and project, the totals and the context meter. Find, Files and Activity are always there; More actions has the rest: jump to the start or the latest, follow on your phone, repeat as a loop, copy to this computer, and delete.
To send a follow-up, type it in the box and press Enter. While the agent works, Stop replaces Send.
Files and the Activity log
Files opens the workspace as a searchable tree. It updates as the agent works. Select a file to preview it. Markdown is rendered, code is highlighted, images are shown and CSV appears as a table. HTML pages open in a built-in browser, with their styles, scripts and images; switch to Code to read the source and back to Page to see it rendered. PDFs, and pages you want in your own browser, open with Open in browser ↗.
Activity shows the full log with timestamps. It includes tool output, errors, and sandbox steps such as pausing, stopping and waking. Type in Search activity to show only the lines that contain your text.
Find
- In a thread: press ⌘F (Ctrl+F on Windows) or click Find in the toolbar. The thread shows only the messages, tool steps and notes that contain your text, with the number of matches. Press Escape or Done to see everything again.
- Threads: type in Search threads at the top of the sidebar to filter threads by title or project.
Looking at files never wakes a sandbox.
When a thread is idle
Threadrun frees up resources when a thread is quiet. The times count from the thread's last activity:
| After | What happens |
|---|---|
| 1 minute | The thread is paused. It uses no CPU, but its memory stays, so it resumes at once. |
| 10 minutes | The thread is stopped. It uses no CPU or memory. On small servers this happens after 2 minutes. |
| 1 hour (once stopped) | The thread is archived. Its workspace is saved, and the container, network and volume are removed. |
A thread that is working is never paused.
Your history, files and changes are kept through all three steps. Caches are not kept in an archive, and dependencies such as node_modules are installed again when needed. Archives follow the retention period set in Governance.
The next prompt wakes the thread. A paused thread answers at once. A stopped thread starts its sandbox first. An archived thread restores its workspace into a new sandbox, which takes a little longer. The agent starts a new session with a recap of the conversation so far, so it can carry on.
Stop a turn
While the agent works, press Stop in the composer. The current turn ends, and the thread stays open for your next message.
If a turn has no activity for 15 minutes, Threadrun cancels it for you. The Activity log records the cancellation.
Restart the agent in a fresh session
When the context meter is showing, Clear restarts the agent in a fresh session in the same sandbox. The agent forgets the conversation. Your files and the history you see stay.
Compact works differently. It summarizes the conversation, and the agent keeps the summary and the files. When the context is full, a banner offers both Compact and Clear context.
Delete a thread
Press Delete in the toolbar, then Delete again to confirm. Deleting removes the thread's sandbox, its archived workspace and its history. It can't be undone. Viewers can't delete threads, and each deletion is logged.
Export a thread
Open Activity and press Export JSONL. Threadrun saves every event in the thread, one per line, as a JSON Lines file. See Review and ship for more on the Activity log.