> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Work locally

> Use your own agent account and project folders, with local changes visible in your editor.

A local project connects one or more folders on your computer to Twill. The agent uses your native account and configuration, and you can watch its changes in your editor as it works. Local model usage does not consume Twill credits; your provider's charges and limits still apply.

<Note>
  Local projects need Twill Desktop on macOS 13.5+, or on Windows 10+ or Linux
  (both experimental). On Windows, Claude Code also needs [Git for
  Windows](https://git-scm.com/downloads/win). Keep the computer awake and
  connected.
</Note>

## Add a project

1. In [Twill Desktop](https://twill.ai/download), choose **+** beside **Local projects**.
2. Name the project and use **Add folder** to select one or more folders. Ordinary folders and Git repositories both work.
3. Choose **Create project**, then connect an agent from the model menu. Existing native logins are discovered automatically.
4. Choose your branch and permissions, then send a message.

Use the project's **… → Edit project** menu to change its name or folders. You don't need GitHub to work locally; connect it when you want to [hand work to the cloud](/handoff).

Local projects and their chats belong to your private personal workspace. They aren't shared with a cloud workspace's team, and deleting a cloud workspace doesn't delete your local projects or files.

## Choose your checkout

Make this choice in the branch menu before the first message. Follow-ups reuse the task's checkout.

| Choice                              | Where changes go                                                                                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Current folder**                  | Your existing checkout, including uncommitted files. Edits appear immediately in your editor.                                                     |
| **Another branch**                  | Twill switches the project folder to the selected branch. Git blocks the switch if it would overwrite changes.                                    |
| **Create and checkout new branch…** | A new branch from the folder's current commit, in each project repository.                                                                        |
| **Start in a new worktree…**        | A separate checkout from committed code on the chosen base branch. Uncommitted edits stay in the original folder. Each repository needs a commit. |

A subfolder selection is the working directory. With several folders, the agent starts at their common parent and receives instructions to stay within your selected folders. This is a scope instruction, not an operating-system sandbox.

## Choose permissions

| Mode               | Behavior                                                                                            |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| **Ask me**         | Shows the harness's tool permission requests for you to allow or deny.                              |
| **Approve for me** | Automatically allows tool requests while retaining harness restrictions. Default for a new project. |
| **Full access**    | Removes harness sandbox restrictions and tool approval prompts.                                     |

Questions and plan approvals still come to you in every mode. Your choice is remembered per project on this device and applies when you submit a turn; changing it doesn't alter an active or queued turn.

Codex can also ask a question without waiting for the answer and keep working. That question appears in the run's activity with its proposed answers. On the latest turn, **Answer** sends your choice as a follow-up message, which the agent picks up as it works or on its next turn.

Local runs use your agent's repository instructions, skills, MCP servers, and other native configuration. Twill supplies project scope and tools for cloud handoff and setup. Workspace cloud integrations aren't automatically installed on your computer.

## Review files and preview the app

Open **Changes** in the task header to inspect the diff against the starting commit. It includes changes already in the folder when the task began, as well as later edits from your editor. **All files** browses tracked and nonignored files.

File review is available to the owner in Twill Desktop on the connected computer. The runner reads files directly for the viewer; viewing them doesn't upload their contents to Twill. Agent output and explicitly shared files still sync with the conversation.

Use **Open folder** to inspect the checkout in your editor. For a running app, choose **Open preview** and enter its port. Twill opens `http://127.0.0.1:<port>` in your system browser; this preview is local to your computer.

<Accordion title="File viewer limits">
  The viewer lists up to 2,000 files and displays text files up to 128 KiB.
  Inspect binary files, symlinks, generated files, and common credential files
  directly in the task folder.
</Accordion>

## Keep working from another device

You can read local chat history and send follow-ups from a signed-in browser or phone while your computer's runner is reachable. Only the computer's owner can control its local runs. A project marked **Offline** needs Twill Desktop opened on that computer before it can run more work.

Closing the desktop window keeps Twill available in the menu bar or system tray; on Linux it minimizes. **Quit Twill** stops local processes. Interrupted turns keep their files and aren't automatically replayed.

To work while the computer is off, use [Handoff](/handoff) and wait for the cloud task to start.

## Chats without a project

Choose **Don't work in a project** in the project picker. Twill Desktop creates a folder under `~/Documents/Twill/YYYY-MM-DD/<chat-name>-<task-id>` for the chat. Follow-ups reuse it, and the chat appears under **Other** in the sidebar. No Git repository is required.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The composer is disabled or the computer is offline">
    Open Twill Desktop on the named computer and check its network connection.
    Twill reconnects stopped runners automatically. If the connection was
    disconnected explicitly, choose **Reconnect this computer** in local setup.
    A model may also need you to sign in again through the model menu.
  </Accordion>

  <Accordion title="A model is missing or unavailable">
    The picker uses the connected computer's agent catalog and global provider
    configuration. Project-specific model configuration isn't enumerated. Check
    the native agent login and provider access. A listed model can still be
    subject to your provider's account limits.
  </Accordion>

  <Accordion title="A pull request isn't showing up">
    Install and sign in to GitHub CLI (`gh`) on your computer. Twill discovers
    PR links in the agent's final answer and PRs on its task worktree branches.
    A shared project branch alone doesn't associate a PR with a chat. Status
    refreshes while the runner is connected; GitHub App installation isn't
    required for local PR tracking.
  </Accordion>

  <Accordion title="Disconnect this computer">
    In local setup, choose **Disconnect and stop local runs**. This revokes the
    runner connection and stops its agents. Project files and native agent
    logins stay on the computer. Reconnecting restores the existing projects.
  </Accordion>
</AccordionGroup>