Work locally

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.

​

Add a project

1. In Twill Desktop, 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. 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. 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

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.

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.

​

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 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