Quickstart

This page walks you through your first thread. You sign in to an agent, pick a project, send a task, and review the changes. It takes a few minutes.

Before you start, install Threadrun and make sure the runtime on this computer is running. The start screen shows the composer when it is.

1. Sign in to an agent

Threadrun runs Claude Code, Codex and OpenCode. OpenCode works with free models and no account, so you can skip this step and try it first.

To use your own subscription or API key:

1. Open Settings → Accounts.
2. Find the agent in the list and press Manage.
3. For Claude Code, press Log in with Claude if you have a Pro or Max plan. Or paste an Anthropic API key and press Save key.
4. For Codex, press Log in with ChatGPT if you have a ChatGPT plan. Or paste an OpenAI API key and press Save key.

The sign-in page opens in your browser. Follow it, then enter the code the app shows, or paste the code back into the box.

For OpenCode, press Connect next to a provider to use its models.

2. Pick a project

1. Click New thread, then Select project.
2. Choose a project from one of the tabs:
   • GitHub lists repositories from your GitHub account. If the list is empty, connect GitHub in Settings → Accounts.
   • This Mac lists checkouts that Threadrun finds in folders such as ~/Dev and ~/code.
   • All shows both.
3. For a repository that isn't in the list, paste its GitHub URL or owner/repo into the search box. Threadrun clones it.
4. For a folder on your computer, press Open folder….

A project needs a GitHub remote to run. If a project has no remote, Threadrun shows a notice. Push the project to GitHub first.

3. Choose a model, effort and mode

The settings row under the composer holds your choices for the thread:

• Run on picks this computer or one of your servers.
• Project shows the project you picked.
• Harness picks the agent.
• Skills & MCP picks the skills and tools the agent can use. See Skills and MCP.
• Model, Effort and Mode come from the agent. Claude Code also offers a context window choice, Standard or 1M.

The choices depend on the agent and the model. If a model has no effort levels, the app says Not offered by this model.

4. Describe the task and press Enter

1. Click the box that says Describe a task for the agent… and type your task. Name the goal, and say what finished looks like.
2. Press Enter (Shift+Enter starts a new line, so you can write a longer task). Threadrun starts the thread in its own sandbox, with its own copy of the repository.

You can also click Send.

5. Watch the steps

The thread shows what the agent does as it works. The header says Working… while the agent runs.

• Messages and the agent's plan appear in the thread. Plans show as a checklist.
• Each tool call shows what the agent did, with its input and output.
• File edits show as colored diffs.

To see the full log with timestamps, press Activity.

To send a follow-up, type in Reply to the agent… and press Enter. To stop the agent, click Stop.

6. Answer permission requests

When your policy asks for approval before an action, the thread shows a card titled Your policy asks for approval. Choose one of the buttons on the card.

Admins can also answer requests in Approvals, in the sidebar. Other roles see Waiting for an admin.

7. Review the changes

When the agent finishes, check its work before you use it.

1. Open Files in the thread header.
2. Choose the Changes tab. It lists each changed file with its additions and deletions. Open a file to see its diff.
3. To test the changes on this computer, click Copy to this Mac (Copy to this PC on Windows). Threadrun copies the changed files into a folder you choose. By default, that is your checkout of the project.

To open a pull request or ship the work another way, read Review and ship.

Next steps

• Threads explains workspaces, files and idle threads.
• Factories gives one goal to a team of agents.
• Troubleshooting has fixes for when something doesn't start.