Your agents.
Your workspace.

Getting started

Introduction#

A workspace for coding agents#

T3 Code runs coding agents on your computer and lets you control them from its desktop, web, or mobile app. Your projects, conversations, and provider configuration belong to the machine where the agents run.

You can use the desktop app on your development machine, open the web app in a browser, or connect from a phone. Start with installation, then follow your first thread.

How to use this guide#

• Getting started: install the app, connect a provider, and start working.

• Concepts: understand projects, threads, worktrees, environments, and permissions.

• Working with agents: write messages, manage threads, inspect activity, and review code.

• Providers: set up the agent runtimes and accounts you use.

• Connected machines: reach your workspace from another computer or your phone.

• Tools and customization: adjust settings, themes, browser sessions, and visual tools.

• Reference: look up shortcuts, updates, usage limits, and troubleshooting.

Use the sidebar to jump between sections. Each section has its own link, so you can bookmark or share a specific topic. Search finds topics across this guide and the contributor documentation.

For development setup, architecture, and release runbooks, see the contributor guide.

Guide based on T3 Code’s user documentation and glossary.

Getting started

Installation#

T3 Code runs coding agents on your computer and lets you control them from its desktop, web, or mobile app. Set up the machine where the agents will work first.

Requirements#

You need an installed, authenticated provider before starting a thread. You can launch T3 Code and configure providers afterwards.

Command line#

curl -fsSL https://t3.codes/install.sh | sh

On Windows, in PowerShell:

irm https://t3.codes/install.ps1 | iex

This installs the t3 binary to ~/.local/bin. If your shell reports command not found afterwards, that directory is not on your PATH yet; the installer prints the line to add. Set T3CODE_CHANNEL=nightly to install the nightly train, or T3CODE_VERSION to pin an exact version.

Run t3 help or t3 --help for the full reference. To start in a new working directory, use an explicit path such as t3 ./my-project. A bare directory name is accepted only if it already exists.

If t3 or t3 start reports an already running server, connect to that server instead. Stop it before starting a replacement, or use a different --base-dir for an independent server.

To try T3 Code once without installing it, run npx t3@latest instead (needs Node.js for npx).

Intel Macs#

There is no t3 executable for Intel Macs (the desktop app is available). To run a server there, build it from source with Node.js 24 and vp (Install vp):

git clone https://github.com/pingdotgg/t3code
cd t3code && vp i && vp run build:desktop
node apps/server/dist/bin.mjs

t3 update and the background service do not apply to a server run this way; update it with git pull and a rebuild.

Desktop app#

Download a release from GitHub Releases, or use a package manager:

The .deb updates itself like the other desktop builds. It asks for your password to install each update. If your desktop has no password prompt, the update fails. Download the new .deb and install it the same way.

The t3 command#

The desktop app includes the t3 command-line tool. To run it from any terminal, open Settings → General → About and choose Install next to t3 command. On macOS and Linux it adds a t3 link to a folder on your PATH; on Windows it adds the app's command folder to your PATH. Open a new terminal afterwards. Remove takes it off again. If you already have t3 from npm, it stays as it is.

Windows Subsystem for Linux#

Choose a WSL distro in Settings → Connections to run agents and projects there. Install the provider CLIs inside that distro. T3 Code installs its own server runtime there automatically; the first launch after an app update can take longer.

Open a project from a terminal#

With the desktop app already running on the same machine:

t3 app

This opens a new thread for the current directory, adding the project if needed. Pass a path, such as t3 app ../my-project, to open another directory. It requires the desktop app, so a standalone server or an SSH session is not enough. If the command cannot reach the app, start or update the desktop app and try again.

Mobile app#

Install T3 Code from the App Store or Google Play. The phone connects to a server on another machine. Follow remote access to link it through T3 Connect or a pairing URL.

Nightly builds need the beta app. The store apps cannot connect to them. A Nightly build also shows these links as QR codes in Settings → General → Mobile app.

• iPhone and iPad: join the TestFlight beta.

• Android: join the beta group. With the same Google account, open the Google Play testing page and become a tester.

If the app crashes during launch, open Settings → Diagnostics on the next launch that succeeds. It lists startup crashes from the last 7 days with the error and component stack that store crash reports leave out. Copy the report and paste it into a GitHub issue. Error messages can quote values from the app, so read it over before sharing.

Providers#

Open Settings → Providers in the web or desktop app, select the environment, and enable the provider you want. Installation, login, and configuration belong to that environment's machine, even when you connect from a phone or another computer.

Provider CLIs must be on the server's PATH. If T3 Code cannot find one, set its Binary path in provider settings, especially when using a version manager. Cursor's executable is cursor-agent, although its login command is agent login. Codex connected through ChatGPT and Antigravity can use their managed runtimes without a PATH entry.

T3 Code warns when a provider version has known compatibility problems with your release. Check Settings → Providers on that environment for the recommended version or range. When its package manager supports installing a specific version, you can install the recommendation there. Otherwise use the provider's installer on the environment's machine. An unlisted version is unverified.

When a provider CLI is behind its latest release, its provider card shows the available version. Update now runs the installer that owns the CLI (Homebrew, or a global npm, pnpm, Yarn, Bun, Volta, or Vite+ install), or the CLI's own update command when T3 Code cannot tell. Update a CLI installed with mise through mise. Cursor and Antigravity update with T3 Code. Homebrew installs compare against the version Homebrew offers, which can trail the npm release by a few hours.

Add another provider instance for a separate account or configuration. Each instance can have its own environment variables, such as API keys or a custom base URL. Mark secret values as sensitive; after saving, T3 Code does not display their original values.

For provider-specific setup and accounts, see Codex, Claude, OpenCode, Antigravity, Pi, and Muse Code.

Next steps#

• Working with threads: start tasks and organize parallel work.

• Permission modes: choose when agents ask before acting.

• Remote access: connect from another device.

• Running in the background: keep a Linux or macOS host available.

• Updating T3 Code: update the app and connected servers.

Source: T3 Code documentation ↗

Getting started

First-run setup#

T3 Code shows a setup flow when you open a new installation or connect to the hosted app for the first time. Existing workspaces skip this flow.

Connect your computers#

Select one or more computers to set up. If you opened T3 Code directly from a server or the desktop app, that computer is already connected and selected. It is identified by its name, which may differ from the device running your browser.

You can add more computers before continuing:

• T3 Connect connects computers that are signed in to your account. Install the CLI and run t3 connect on each computer you want to add, then start T3 Code or run t3 serve so the computer stays available.

• Add a computer connects directly to a server on your network or tailnet. Start the server with t3 serve, then run t3 pair --tailscale and paste the pairing link. You can also run t3 serve --host <address> and use t3 pair when the server is already reachable on your network.

Saved computers and computers discovered through T3 Connect are selected by default. Uncheck any you do not want to set up; this does not disconnect them. Continue when your selected computers are connected. Setup checks agents across the selected computers, then offers project import grouped by computer.

If T3 Code cannot confirm the workspace during startup, the setup flow shows Still connecting instead of opening the app. Select Reload to try again.

If T3 Code cannot read your saved settings, it shows Could not read settings. Select Retry after storage becomes available. Setup does not replace unreadable settings with defaults.

Check your agents#

T3 Code checks each selected computer for Claude Code and Codex. If an agent is not installed or signed in, select its action to open a terminal with the correct command ready to run. Install uses the vendor's own installer, which keeps Update now working in Settings. Other providers can be enabled in Settings.

The setup terminal uses the home directory and environment configured for the selected provider instance. Sensitive values remain redacted in Settings and terminal metadata while the terminal process can use them.

Import your projects#

T3 Code finds directories that Claude Code or Codex has used. Git repositories are listed first, newest activity on top. When the remote is on GitHub, the group shows the repository as owner/name. Clones with the same remote share one group. Directories that are not git repositories sit under "Other folders".

The default selection includes git repositories active within the last 30 days with at least three conversations. Use the checkboxes, or "Select all" and "Select none", to change the selection. Linked git worktrees, Codex scratch directories under Documents/Codex, and anything under Downloads are not offered.

A large or malformed history can reach the scan limit. T3 Code keeps the projects it found and warns when projects or conversations may be missing.

Imported projects include Codex and Claude conversations active within the last 30 days. You can continue those conversations in T3 Code.

Conversation import is best effort. T3 Code keeps the first user prompt and the newest remaining visible user and assistant messages, with 200 messages total. It omits tool activity and attachments. For Codex, it omits generated setup context only when a canonical user event and a valid shared turn ID identify the same user turn. Ambiguous legacy or response-only context stays in the imported conversation so T3 Code does not remove user text. It reads one conversation at a time and skips files larger than 16 MiB. It ignores malformed records and skips unreadable or unparseable conversations.

Each import attempt reads up to 100 conversation files and 64 MiB per project, with up to 100,000 input records. Run import again to continue a large batch. Completed conversations are not imported again. You can continue without the remaining history.

You can continue without configuring agents or importing projects, or return to an earlier step using the setup progress bar. Navigation pauses while an import is running.

Source: T3 Code documentation ↗

Getting started

Your first thread#

1. Connect a provider#

Install T3 Code, then open Settings → Providers. Select the environment where your agent will run and enable a provider. You need an installed, authenticated provider before starting a thread.

Follow the guide for Codex, Claude, or another provider to finish setup. If a provider CLI cannot be found, set its Binary path in provider settings.

2. Open your project#

The welcome wizard can import existing projects and conversations. To open a directory from a terminal while the desktop app is running on the same machine:

t3 app ./my-project

This opens a new thread for the directory and adds the project if needed. The command requires the desktop app; it does not open a standalone server or an app on the other end of an SSH session.

3. Choose a workspace and send a task#

Start a thread for the task, choose your provider and model, and select a permission mode. Use New worktree when changes need a separate Git branch and working directory.

Describe the result you want and the constraints that matter. Attach relevant files or add context in the composer, then send the message. The agent works on the environment's machine.

4. Review and continue#

Inspect the activity log and turn changes. Respond to questions or approval requests in the conversation. Send a follow-up to steer ongoing work or queue the next step.

Keep related work in the same thread. Start another thread for an independent task, and settle finished work to keep your active list useful.

Next, learn the core concepts, explore keyboard shortcuts, or set up remote access.

Guide based on T3 Code’s user documentation and glossary.

Concepts

The core concepts#

Environments and clients#

An environment is a running T3 Code server and the machine, credentials, files, and state it owns. A client is the desktop, web, or mobile interface connected to it. The desktop app can also host a server.

The device showing the interface can be different from the machine doing the work. Install and authenticate providers on the environment's machine. Remote access connects other clients to that workspace.

Projects and worktrees#

A project points to a directory in an environment. Its workspace root is the base directory for that project's files.

A worktree is a separate Git checkout. Choose one when a task needs its own branch and working directory. This lets independent threads work in separate checkouts. See threads and worktrees and project settings.

Threads, turns, and activity#

A thread is the saved conversation and work history. It survives the provider process exiting. Use a new thread for a separate task.

A turn is one user-to-agent cycle. The agent can finish before checkpoint and diff processing finishes. Activity includes tool actions, approvals, and failures that appear alongside messages.

Providers, models, and instances#

A provider is the agent runtime T3 Code controls, such as Codex or Claude Code. A provider instance is a configured provider with its own settings and lifecycle. Multiple instances can use the same provider with different accounts or configuration.

Choose a provider and model for your work. When switching providers, T3 Code can transfer conversation context; provider capabilities and permissions can differ.

Permissions and planning#

The thread's permission mode controls when an agent must ask before acting. The agent's interaction mode, such as planning, controls how it approaches the task. These are separate choices.

Choose permissions in the composer, and set defaults in Settings. See permission modes for the behavior of each mode and provider differences.

Checkpoints and diffs#

A checkpoint saves workspace state for comparison and restore, using a hidden Git reference. A turn diff shows workspace changes attributed to one turn.

Review changes before deciding what to keep or publish. The source control guide explains turn changes, pull requests, and review.

For the precise architecture terminology, see the contributor glossary.

Guide based on T3 Code’s user documentation and glossary.

Concepts

Permission modes#

Permission modes control when an agent needs your approval to act. Choose a mode in the message composer; it applies to that thread.

Set the default for new threads in Settings → General → New threads → Permissions. Projects can override the environment default. New threads use this setting rather than the mode of the thread you were viewing. The initial default is Full access; existing threads and modes you choose in a draft keep their permissions.

Approve or reject requests in the conversation to let the agent continue. Permission modes do not prevent the agent from asking questions about the task.

Provider differences#

Providers enforce permissions differently. Some read-only actions can proceed in Supervised. Auto uses automatic review on Codex, Claude, Cursor, and Grok; providers without an equivalent, including OpenCode and Antigravity, fall back to asking. On Grok, commands its review blocks come to you for approval.

Muse Code offers only Supervised and Full access. A Muse thread already set to another mode runs in Supervised.

Grok offers no Auto-accept edits. A Grok thread already set to it runs in Supervised. Grok file-change approvals offer Allow all edits this session. Its command approvals have no session-wide choice, because Grok would remember that command for the whole project.

ACP Registry agents run their own tools in their own mode; T3 Code answers their approval requests by the permission mode. See ACP Registry permissions.

Antigravity can still send native approval requests in Full access. It only offers remembered approvals for actions that support them.

See the provider guides for setup and provider-specific limits.

Source: T3 Code documentation ↗

Concepts

Context & provider switching#

T3 Code transfers conversation context when you switch providers, continue through a portable restart, or use a fork that the provider cannot resume itself.

Short conversations transfer intact. For longer conversations, T3 Code favors recent requests and answers, the original request, and relevant activity such as command outcomes. Selected messages keep their full text, order, and user or assistant role, including partial work from failed or interrupted turns. Your new request stays separate and is never shortened to make history fit.

Codex receives historical messages directly when its installed version supports that operation. Other providers receive the same selection as attributed conversation context. A handoff does not copy the outgoing provider's reasoning, tool-call state, or attachments.

The handoff includes references to omitted history. The agent can use T3 Code's thread-reading tool to retrieve saved messages and activity, including the remainder of a long item. For an important constraint, you can still repeat it in your next message. A handoff is a budgeted selection, not an agent-written summary.

Context limits#

A handoff must leave room for existing provider context, your request and attachments, instructions, tools, and subsequent work. If even its retrieval references cannot fit, T3 Code reports an error instead of shortening your request. Compact the target conversation or select a larger-context model before trying again.

Server operators can set T3CODE_CONTEXT_HANDOFF_TOKEN_CAP to change the initial history allowance (default 16,000; clamped to 1,024–64,000). This is an upper bound, not a provider context-window guarantee. Text accounting conservatively charges one token per UTF-8 byte, including attribution and JSON escaping. Imported history has a separate 64,000-byte ceiling; your current input and attachment payloads do not consume that ceiling.

T3 Code uses available capacity information for your selected model and options, together with provider context telemetry. Starting a fresh provider conversation clears prior usage, while keeping known model capacity. Changing models or context-window options discards stale usage and compaction thresholds.

When no capacity information is available, T3 Code assumes a 128,000-token window. It reserves at least 16,000 tokens, or a quarter of the window when larger, for instructions, tools, and subsequent work. Images reserve an estimated 8,192 tokens each, independent of their file size; other attachments reserve 4,096 each for their references. Existing context is estimated from saved activity when usage telemetry is unavailable. Known smaller windows still constrain the handoff. These are fallback estimates, not exact token counts. Image resolution, custom models, and hidden native context can differ, so the provider may still reject an input.

Source: T3 Code documentation ↗

Working with agents

Threads & worktrees#

Use a new thread for a separate task. Choose New worktree when its code changes need a separate branch and working directory.

Start a thread#

On web and desktop, a new thread keeps the current project and carries your model and mode selections, unless the destination project has its own model default. Its branch and workspace mode come from your configured defaults. To continue in an existing worktree, use New thread in this worktree from the branch toolbar.

When you change a new thread's project, T3 Code stays in the current environment if that project exists there. Otherwise it selects an environment that has it.

Start without a project#

A thread does not need a project. To start one without a project, click or start without a project under a new thread's heading, pick No project from the project menu in that heading or from New thread in... in the command palette, or press mod+alt+n. On mobile, pick No project from the project list. It starts on your current machine; before sending, pick another machine from the machine menu to move it there. To move a draft into a project, pick the project in the heading.

Each thread without a project works in its own folder under ~/.t3/scratch (the scratch folder of your T3 data directory), named after its date, the first words of its first message, and a short id, like 2026-09-25-convert-these-pngs-to-webp-a1b2c3d4. Deleting a thread keeps its folder, so the files the agent wrote stay until you delete them. Branch, worktree, and diff controls stay hidden because these folders are not Git repositories. This is unavailable when the data directory itself sits inside a Git checkout.

Start in the background#

In a desktop browser or the desktop app, press Cmd+Enter on macOS or Ctrl+Enter on Windows and Linux to start a new thread and immediately open another draft. The next draft keeps the workspace mode and base branch you selected. With New worktree, each background submission creates its own worktree.

To send the same prompt to several models on web or desktop, Shift-click models in a new thread's model picker to add or remove them. A regular click returns to a single model. Choose a base branch and send. Each selection starts a separate thread and worktree while you stay in the new thread composer. This requires a Git project.

Pin and reorder threads#

Pin a thread from its menu to keep it above your active work.

On web and desktop, unpinning, settling, snoozing, and archiving a thread each show a notification with Undo for five seconds. Undo restores the thread's previous state, including its pinned position, and reopens an archived thread you were viewing. Discarding an unsent draft from the sidebar works the same way: Undo brings back its text and attachments. mod+z triggers the most recent Undo when no text field is focused; see Keybindings.

On web and desktop, you can also drag files from your computer onto any thread row: the thread opens and the files are attached in its composer, ready for your next message. The same per-message file limits apply as when attaching files directly; see Attach files.

On web and desktop, pinning or unpinning a thread keeps the sidebar at your current scroll position instead of following the thread to its new place in the list.

Pinning does not prevent automatic settlement. Settling a thread removes its pin.

On web and desktop, drag a thread between sections to change its state. Drag a thread up into the pinned section to pin it at the spot you drop it; drag a pinned thread down into the active list to unpin it. Dragging a thread onto the Settled header settles it, and dragging a settled thread into the active list un-settles it. A snoozed thread can be dragged out of the snoozed shelf, which wakes it, but threads cannot be dragged into the shelf because snoozing needs a wake time. Dragging a pinned thread out of the pinned section does not ask for unpin confirmation. Pinned and active boundary labels appear only while dragging, without moving the rows. The other rows slide aside to show where the thread will land. When you cross into another section, the dragged thread shows the action the drop performs, with its icon: Pin, Unpin, Settle, Un-settle, or Wake. Its status and hover actions hide during the drag. A pinned thread keeps its pin only while it stays in the pinned section; once it leaves, the badge takes over. Reordering within the same section shows no badge. When there are no pins, drag to the top edge to pin a thread. Section labels stay readable for the whole drag, and the section the thread is over takes the accent color. Section labels also identify empty sections and a collapsed settled shelf.

Drag within the pinned or active section to change its order. Other rows slide aside to show the spot where the thread will land. Drops into either section keep the position you choose. On mobile, open a thread's menu and choose Arrange threads. Drag a handle within or between Pinned and Active to reorder, pin, or unpin. Drop onto the Settled divider to settle a thread. The dragged card shows the action before you release it. Expand Snoozed or Settled to drag a parked thread back into either live section. Each drop saves; Done returns to the thread list. Move up and Move down are also available in the thread menu. The server saves the order, so it survives a refresh and appears on your other connected devices.

On web and desktop, the list also animates section changes made with thread actions such as Pin, Settle, and Snooze. These transitions respect your system's reduced-motion preference. While dragging, rows follow the insertion gap without replaying a second transition after the drop.

New threads appear above the active threads you have arranged. Settling clears a thread's active position, so using Un-settle returns it to the top. Pinning and snoozing preserve its active position until you move it again. Thread activity does not change the order. The settled shelf continues to use settlement time.

If dragging is unavailable for one environment, update the T3 Code server running in that environment. Pinned and active reordering require server support. Threads from older servers keep their default order until the server is updated.

To generate a fresh title from the conversation, open a thread's menu and choose Regenerate title. The action is unavailable while title generation is in progress or when the connected environment needs a server update.

Agents connected through T3 Code can use the same server-owned metadata workflow to rename a thread, regenerate its title, or link and unlink a pull request. These changes appear on web, desktop, and mobile without requiring the originating browser to remain open.

Fold working threads (beta)#

Turn on Settings → General → Working section (beta) on web and desktop, or Settings → Thread behavior → Working section on iOS and Android, to move threads that are working or monitoring into a collapsed Working section below the active list. A thread returns to the top of the active list when it finishes, fails, or needs an approval or answer. The Working section lists the thread you last sent work to first. Pinned threads stay in the pinned section. Each device keeps its own choice.

While this is on, the active list is ordered by when each thread last came back to you, so you cannot drag or move threads within it. Your saved order returns when you turn it off.

Settle finished work#

Choose Settle thread from its menu to move finished work out of the active list without deleting the conversation. Un-settle thread restores it to active work and prevents automatic settlement until new activity resumes the usual rules. Manually settling an idle thread dismisses unanswered async questions without sending an answer or restarting the agent. Settling also closes the thread's terminals that wait at an idle prompt, and keeps their output. A terminal that runs a command, such as a dev server, stays open.

To reclaim disk space from settled work, turn on Run in the thread's worktree when the thread settles for one of the project's actions, or set "runOnSettle": true on a t3.json script, for example cargo clean. It runs each time a thread in its own worktree settles, manually or automatically, even if a terminal there still runs a command such as a dev server. Threads in the project's main checkout skip it. Its terminal closes when the command succeeds and stays open when it fails.

On web and desktop, press a thread's Settle button and drag up or down to settle every thread in that section between it and the one you release on. The Un-settle and Wake buttons work the same way in their sections. Press Escape while dragging to cancel.

By default, environments settle inactive threads after three days and settle threads whose pull request merged. A closed pull request can also settle an idle thread. Work in progress, pending questions or approvals, and live background work prevent automatic settlement. An open pull request does not prevent inactivity settlement, but an old closed or merged pull request does not settle work you resumed after it closed. Only your own messages count as resuming. A turn that finished background work or a pull request watch starts on its own does not.

To keep one thread out of the settled shelf no matter how long it sits idle, open its menu, choose Auto-settle behavior, and pick Disabled. The current option is checked. Pick Enabled to return to the usual rules. Manual settle, snooze, and archive still work while it is disabled.

Change these rules in Settings → General on web and desktop, or Settings → Thread behavior on mobile. They continue to run when your apps are closed. On web and desktop, choose an environment at the top to change only its rules, or All environments to update connected environments together. Mixed values show where the selected environments disagree. Mobile applies these rules to connected environments that support shared settings. Offline environments and older servers keep their previous values. Changing a rule does not reopen already settled threads.

Link a pull request#

The server finds the PR for each unsettled thread's saved branch, even when your apps are closed. Settled threads keep their saved links. Update the server if automatic branch links do not appear.

On web and desktop, right-click a pull request link in a thread and choose Link to thread to select a different PR. Use Unlink from thread on the same link to return to the branch PR, if one exists. The linked pull request participates in automatic settlement.

Find and reference work#

On web and desktop, open the command palette with Cmd/Ctrl+K to search threads across connected environments. Message search starts after two characters and includes your messages and final agent responses.

Use Settings → Keybindings to find or customize shortcuts for searching files and copying a thread reference. A copied reference uses the thread's pull request link when available, otherwise its thread ID. See keybindings for custom configuration.

Inspect agent work#

Limited means the provider stopped on a usage or rate limit. The conversation keeps the provider's explanation. Retry after the limit resets, or switch to another provider instance. On web and desktop, press Resume in an empty composer to continue a limited or interrupted turn manually. Queued messages stay saved while the limit blocks the thread. They run after the continuation finishes. If the queue was held by a restart, resume it then.

When the provider reports a reset time, choose Resume at reset to schedule a continuation. You can cancel it from the thread. Enable Auto-resume limited threads in Settings → General on web and desktop, or Settings → Thread behavior on mobile, to schedule limit stops by default. The environment must be running when the reset arrives; it resumes overdue continuations after a restart. Sending a new message, archiving, or settling the thread prevents a pending continuation from starting.

Choose Snooze until reset to hide the thread until its allowance returns. Snooze and auto-resume are independent: snooze alone wakes the thread without sending a message; enabling both wakes and continues it. Wake now cancels the snooze. Enable Snooze limited threads in thread behavior settings to snooze limit stops by default. Providers without a reset time offer manual retry and the normal snooze choices.

On web and desktop, use Agents to follow work delegated to subagents. Stop on a thread also stops the subagents it delegated to.

Subagent threads started by the agent can't take messages; message the parent thread instead. When such a subagent needs an approval or an answer, the parent thread asks for it.

Expand a tool call in the conversation to see its full command and output. Summaries shorten shell wrappers and can still describe the latest call after it finishes; the call's own result shows its status.

Snooze until later#

Choose Snooze → Custom… from a thread's menu to pick a date and time in your local time zone, or a duration in minutes, hours, or days. Durations start when you confirm; one day means 24 hours. On web and desktop, you can also snooze several selected threads together. Choose Wake thread to bring a thread back early.

Source: T3 Code documentation ↗

Working with agents

Messages & context#

Give the agent a task in the composer. Add files, quote a previous response, or include a skill when the task needs more context.

Messages can contain up to 120,000 characters. Longer drafts stay in the composer so you can shorten them or split them into several messages.

Pasting 32 KiB or more of text adds that fragment as a text-file attachment so the agent can inspect it without filling the model context. A smaller paste also becomes an attachment when inserting it would exceed the message limit. On a hardware keyboard, use Cmd+Shift+V on Apple devices or Ctrl+Shift+V elsewhere to keep a large paste editable in the composer instead.

Formatting#

The composer writes Markdown and shows it styled as you type. Markers such as ** stay in the text and show beside the styled words when your cursor is on them. Lines starting with -, 1., - [ ], >, # or --- become lists, task lists, quotes, headings and rules; ` followed by Enter opens a code block. What you typed is what the agent receives, markers and numbering included, and #1234 without a space still looks up a pull request.

Enter sends. In a list or quote, Shift+Enter continues it, and Shift+Enter on an empty line leaves it; Tab nests a list item. In a code block, Enter starts a new line at the current indentation, Tab and Shift+Tab indent the selected lines, and a closing ` followed by Enter, or two blank lines at the end, leave the block. Backspace at the start of a code block turns it back into plain lines. Choose the language in a code block's corner to change it. Very large code blocks are shown without syntax highlighting.

Attach files#

Attach up to 100 files per message. Each image can be up to 10 MiB, with at most 80 MiB of images in one message. Other files, including videos, can be up to 50 MiB each, subject to the environment's upload support and limit. The agent receives them on the environment's machine. Provider and model limits still apply, including images already in the conversation. A video attachment gives the agent a file path; it does not enable native video input.

Uploads begin when you add an attachment. All uploads must finish before the message can send. Retry or remove a failed upload. On web and desktop, reloading before an upload finishes requires you to attach that file again.

You can drag or paste images into the web or desktop composer. HEIC and HEIF photos are converted to JPEG there and when selected from the mobile photo library; photos over the image limit are also resized to fit. On mobile, you can also send files to T3 Code through another app's system share sheet.

See images and videos for previewing and saving media.

Send while the agent is working#

On web and desktop, choose Settings → General → Follow-up behavior to queue new messages for a later turn or steer the running turn immediately. The setting applies to this client; already queued messages keep their place. Queued messages are saved on the server and can be edited, reordered, or removed above the composer. Cmd+Enter on macOS or Ctrl+Enter on Windows and Linux uses the opposite action: it steers when your default is Queue and queues when your default is Steer.

Use Cmd+Shift+Enter on macOS or Ctrl+Shift+Enter on Windows and Linux to send the oldest queued message as a steer. This leaves the current draft intact and requires an active turn that supports steering. Change thread.steerQueuedMessage in Settings → Keybindings to use another shortcut.

Press Option+Up on macOS or Alt+Up on Windows and Linux with the cursor at the start of the composer to edit the most recently queued message. Change thread.editQueuedMessage to use another shortcut.

Mobile has the same choice under Settings → Follow-ups. While a turn is running the send button shows which action it will take. Long-press it to use the other action for a single message, or hold Cmd while sending from a hardware keyboard. The button only offers Steer when the running agent supports it.

Queue messages offline on mobile#

Mobile keeps local copies of draft attachments, so you can preview them and queue messages while disconnected. Uploads resume when you reconnect. Drafts and queued messages survive app restarts. Signing out of T3 Connect keeps that work on your device until you sign back into the same account.

Custom models#

On web and desktop, use Settings → Providers → Models to add an unlisted model with a custom name and options. Only options supported by the provider integration affect turns. Antigravity uses its account catalog and does not support custom models.

Model defaults#

T3 Code remembers your provider, model, and model options for new threads. A project's configured model takes precedence; resetting that project setting returns to the remembered selection.

Leaving reasoning level or service tier unset uses the provider's own configuration.

Quote an assistant response#

On web and desktop, select text within one assistant response and choose Cite in composer. You can add a comment about the quote and write instructions around it.

Select the quote in a draft or sent message to return to its source. If the source is unavailable or has changed, the saved quote remains readable.

The chip shows your comment when it has one, or a short quote preview otherwise. Use the pencil button to add or change the comment. To remove the citation, place the caret beside its chip and delete it like other inline context. Copying, reloading, and restoring a stashed prompt keep each comment with its quote, and sending tells the agent which words were quoted and which comment you wrote. The quoted text and comment count toward the message limit.

Mobile displays saved quotes and comments, but does not create citations or navigate to their sources.

Recall a sent prompt#

Press ArrowUp in an empty composer to bring back the last prompt you sent in this thread. Press ArrowUp again to go further back, and ArrowDown to come forward. Moving forward past the newest prompt clears the composer. Recall walks the prompts loaded in the thread. Attachments, terminal context, and other extras from the original message are not restored, only the text you typed. A composer that holds an attachment or a picked element does not count as empty.

When the composer has text, the arrow keys move the caret as usual. Recall takes over only while the text is an unedited recalled prompt, with the caret on the first visual line for ArrowUp or the last visual line for ArrowDown, counting wrapped lines. Editing a recalled prompt turns it into a normal draft.

Edit an earlier prompt#

On web and desktop, choose Edit from here beneath a sent message to rewind the conversation to before that message. Choose Revert and keep changes to leave workspace files as they are, or Revert files too to restore them as well. File restore is only offered for threads running in a worktree, and it is refused when another thread or agent session also uses that directory, a folder inside it, or a folder that contains it, since restoring would erase their changes. A thread that works in the project directory rewinds the conversation only. The selected prompt and its attachments return to the composer for editing and resending. Any unsent draft stays above the restored prompt.

This removes the selected message and later conversation from the active thread and provider history. It does not undo external actions or separate provider memory. The action is available only when the provider supports rewind.

Prompt stash#

On web and desktop, press Cmd+S on macOS or Ctrl+S on Windows and Linux to save the current prompt and its attachments for later. Wait for uploads to finish first. With an empty composer, the same shortcut restores a single stash or opens the stash menu when there are several.

Stashes containing uploaded files must be restored in their original environment. Those files are retained for 24 hours. After an upload expires, restore the prompt and use Attach again or remove the missing file before sending.

Voice input on iPhone#

On supported iPhones with iOS 26 or later, use the composer's microphone to record, then confirm to transcribe. Text is inserted where your selection was when recording started, ready for you to review and edit before sending.

The first use may download Apple's speech model and needs a network connection. Later transcription works offline for that language. Recordings can be up to five minutes long. Canceling, leaving the screen, or an audio interruption discards the recording and preserves your existing draft. While recording, the screen stays awake; it can sleep normally once recording stops.

Voice input records from the first connected microphone in Settings → Microphone. The list mixes kinds (built-in, other wired, other Bluetooth, CarPlay) with wired and Bluetooth devices you have dictated with, listed by name. Drag to rank them together: for example, put Other Bluetooth above your AirPods so a new headset is preferred while the AirPods microphone stays low. By default, CarPlay comes after the built-in microphone.

Transcription runs on your device. T3 Code deletes the temporary audio after transcription or cancellation; only the message text is sent when you submit.

Queued messages#

On web and desktop, the composer shows Interrupt while the agent is working and the draft is empty. Adding text or attachments replaces it with a steer arrow. Click it to send a message into the active turn, or press Enter on desktop. Hold Cmd on macOS or Ctrl on Windows and Linux to switch the button to a queue icon. Click while holding that key, or press Cmd+Enter or Ctrl+Enter on desktop, to queue the message for after the active turn.

Queued messages appear above the composer. Rows show a thumbnail of any attached image alongside the text. Drag a row by its handle to reorder it, use the handle's arrow keys, promote the message to a steer, or remove it.

If the server restarts, saved queued messages keep their order and are held. Press Resume in an empty composer on web or desktop, or Resume queue in the queue sheet on mobile, to continue. You can edit, reorder, or remove held messages without starting them.

The pencil on a queued row opens that message in the composer for editing. The original message stays in the queue until you save, and its row is highlighted while you edit. The message's attachments appear above the text with a remove control, and new images can be added the usual way. The checkmark saves the queued message in place; Cancel on its row leaves it unchanged. Whatever you had typed in the composer before starting the edit is restored afterwards. If the queued message starts or is removed while you are editing, the edit ends: changed content moves into the composer when it is empty, and is discarded otherwise.

Commands and skills#

Type / for commands or $ to add a skill from the selected environment and provider. On mobile, both are also available before starting a thread on New task.

The slash menu also includes skills unless you turn off Settings → General → Show skills in slash menu. Only skills enabled for the provider are listed.

After you add or change skills, plugins, or MCP servers, use Restart agent session in the command palette on web and desktop. The conversation continues, and your next message starts the agent again with the new setup.

Provider commands must start the message to run. T3 Code commands such as /model and /plan, and skill mentions, work on any line.

Send /compact in an existing conversation to reduce context usage when the provider supports it. Web and desktop also offer compaction from the context meter.

Goals#

With Codex and Claude, send /goal followed by what "done" means, for example /goal all tests in packages/api pass. The agent keeps working across turns until it judges the goal met. The thread shows Goal while it works, and a row above the composer shows the goal and its progress.

• /goal alone shows the current goal. /goal clear removes it.

• Codex also supports /goal pause and /goal resume. Stopping a Codex goal pauses it.

• Stopping Claude ends the current turn, but the goal stays set. Claude checks it again at the end of your next message.

Context in your message#

Context you attach lands where your cursor is, as a chip inside your text: a terminal excerpt, a review comment from a diff or file, a preview annotation, or a file. You can type before and after a chip, move it by cutting and pasting, and delete it like a character. Hover a chip for its brief details. Select a terminal excerpt to open its captured output, or select a review comment, picked element, or preview annotation to open its full details. Chips read as "Terminal excerpt, Terminal 1 lines 3-4" and similar to screen readers.

A pull request appears as its icon and number. Its color reflects whether it was open, draft, merged, or closed when it was attached. Select it to inspect the captured title and branches, then choose Open pull request to visit the pull request. On web and desktop, type # to browse the newest pull requests in the current project's repository. Continue typing digits to filter the recent list by any part of its pull request numbers. A complete number is also resolved directly, even when that pull request is older than the recent list. Type a single word after # to search pull requests in the repository by text. Choose a result to insert it as a chip.

Another thread can be context too. Type @ followed by part of its title to pick one from the same server, or on web and desktop drag a thread out of the sidebar and drop it on the composer; a multi-selection drops together. The chip shows the thread's current title and opens it when selected. Your prompt only carries a reference: the agent reads the thread's history on demand, so attaching a long thread costs nothing until the agent looks. Attaching a thread does not change it, and the agent cannot send messages to it unless you ask.

Images keep their thumbnail shelf above the text and also get a chip at your cursor, so you can say exactly which image you mean. Deleting an image chip leaves the image on the shelf; removing the thumbnail asks first when the image is still mentioned in your text, then removes both. Files exist only as chips: deleting a file's last chip removes the file from the message.

Copy text that holds chips and paste it into another draft, in the same thread or another one, and the chips come along with what they point to. Images and files are fetched again from the environment they came from; while that happens the chip shows a dashed outline, and if it cannot complete T3 Code tells you and leaves the chip for you to remove or replace. A chip whose context is no longer available shows the same dashed outline; hover it for what to do.

Copying a message with the copy button, or copying text out of it, gives other apps readable Markdown with a link in place of each chip. Older messages that were sent before chips still show their context. Stashing a prompt keeps its chips and what they point to; restoring brings them back.

On mobile, tap a chip to inspect its content. File references open the current file; attached files show the copy that was attached to the message.

Attached files#

Select a file chip in your draft or a sent message to preview it. Code and JSON use syntax highlighting; Markdown, HTML, CSV, and TSV offer rendered and raw views. Audio files have playback controls. Large text files show a limited preview; save the file to read it in full.

On web and desktop, files open beside the conversation with the same controls as a workspace file: a header row with the view toggle, Copy contents and Save file. On mobile, documents open in the same file screen as workspace files; its menu holds Copy contents, Save or share and Open in file viewer. Pictures, videos and PDFs keep their native viewers, and other document formats such as Word or Pages open in the device's own viewer when it has one. If nothing on the device can show a format, save or share it to open it elsewhere.

Images and videos in messages#

Select an image or video attachment or link to preview it. Playback support depends on your browser or device; save an unsupported video to open it in another app.

On web and desktop, right-click media to save it or copy its path or URL. On mobile, touch and hold an image or video thumbnail and choose Save or share. On iOS, return to the thumbnail to open this menu after watching a full-screen video.

File links refer to the environment's machine, including when you connect remotely. Previews use the original file, even outside the workspace. Moving or deleting it can break the preview, so save a copy if you need to keep it.

Files outside the workspace#

Follow an agent's file link to read a report or other file outside the workspace. These files open read-only. An HTML file outside the workspace cannot load scripts, styles, or images from neighboring files.

HTML and PDF files in the file viewer#

On web and desktop, HTML and PDF files open as rendered pages. Switch an HTML file to source view to read its markup; a link to a specific line opens source automatically. HTML previews cannot access your T3 Code session.

The file viewer recognizes images, HTML, and PDF files by their filename extension, including filenames or folders containing # or ?.

On mobile, select a PDF attachment or link to open it. iOS uses the native viewer; Android opens a compatible installed file viewer.

Source: T3 Code documentation ↗

Working with agents

Answering questions with files#

When an agent asks a question that accepts a custom answer, use Attach files or paste an image into the answer field. On mobile, use the attachment button to choose photos or files. You can send a file by itself, with a selected option, or with a typed answer.

Each question keeps its own attachments as you move between questions. Your normal prompt draft stays separate. Wait for uploads to finish before submitting; retry or remove any failed upload. A failed response keeps the draft available to try again.

Files upload to the environment running the thread, including remote environments. The agent receives paths to those saved files with your answer and can open them with its available tools. Questions that only accept predefined choices do not offer attachments. Older servers need updating before this option appears.

Submitted attachments remain in the thread history. Reverting a thread removes attachments belonging to discarded answers; deleting the thread uses the same file cleanup as other attachments. You can attach up to 100 files across one set of answers, using the same file and total image size limits as the normal composer.

Source: T3 Code documentation ↗

Working with agents

Reviewing agent activity#

On web and desktop, consecutive tool calls appear as an expandable summary. Open it to inspect commands, tool inputs, status, and exit codes. Raw command output and tool-result bodies are not shown. Use Open diff on a file change to review its contents.

T3 Orchestrator summaries describe the actions taken, such as Ran 2 commands and sent messages to 3 threads. Repeated messages to the same destinations show both counts: Sent 5 messages to 2 threads. Thread creation counts the threads returned by the tool, including batches.

Groups with many kinds of activity show up to two specific action categories and a count of the remaining actions. Commands, file changes, and orchestration changes take priority over reads and status checks. Expand the group for the full list.

Failed calls do not count as successful messages or creations. Waiting on a thread does not mean it finished, and an interrupt or cancellation request does not mean the thread stopped. When tool details are unavailable, summaries use a broader description instead of guessing how many threads were affected.

Source: T3 Code documentation ↗

Working with agents

The terminal#

Each terminal keeps up to 5,000 lines and 8 MiB of scrollback on its environment server. T3 Code removes the oldest output when either limit is reached. A long line can be shortened at the start. New terminal output is not truncated.

These limits apply when you reconnect and when T3 Code restores saved terminal history. A client can show less scrollback than the server keeps.

On web and desktop, use Shift+PageUp and Shift+PageDown to read scrollback without leaving terminal input. Ctrl+Shift+Home and Ctrl+Shift+End jump to the start and latest output; use Cmd instead of Ctrl on macOS. Full-screen terminal programs keep these navigation keys.

To copy all retained output, choose Select all in the terminal's context menu, then copy. Cmd+A on macOS and Ctrl+Shift+A elsewhere select the same output. Ctrl+A still moves to the beginning of shell input on Windows and Linux. Jump to latest in the context menu returns to the current output.

Source: T3 Code documentation ↗

Working with agents

Git & pull requests#

T3 Code integrates with GitHub, GitLab, Forgejo, Gitea, Bitbucket, Azure DevOps, and GitCafe to clone and publish repositories, create pull requests, and review changes.

Review turn changes#

A turn's changed files and diff show only the turn's own work. When a turn pulls, merges, or rebases, the files Git brought in are left out. A file stays in the list when the turn edited it, committed it, or fixed a conflict in it. Use the branch comparison to review everything that changed against your base branch. Restore still returns the complete saved workspace.

Connect an account#

Install Git and configure authentication on the machine running your T3 Code server. For a remote environment, do this on the remote machine. After signing in, open Settings → Source Control and choose Rescan.

GitHub#

T3 Code talks to GitHub's API directly and only needs a token. Any of these works, in this order of precedence:

1. A token saved in Settings → Source Control → GitHub. It is kept in the server's secret store, and works without the GitHub CLI.

2. GH_TOKEN (GH_ENTERPRISE_TOKEN with GH_HOST for GitHub Enterprise Server) in the server's environment.

3. GitHub CLI 2.81.0 or newer, signed in with gh auth login.

If gh is signed in to several accounts or hosts, expand GitHub in the same place to pick the account each host uses or turn a host off. A saved token or GH_TOKEN takes precedence over that choice; a host turned off stays off either way.

For GitHub Enterprise, sign in with gh auth login --hostname YOUR_HOST. T3 Code treats a custom server name as GitHub once it has a credential for that host.

Forgejo and Gitea#

Install Forgejo CLI (fj) or Gitea CLI (tea) 0.16 or later on your T3 Code server. Sign in with fj --host https://your-server auth add-token or tea login add. Repeat for each server you use, including Codeberg.

T3 Code prefers a matching fj login and falls back to tea when fj is unavailable or has no login for that server. Once an account is selected, failed actions stay on that account. Settings shows the detected CLI. Forgejo and Gitea share one integration entry. Servers hosted under a URL subpath, such as https://example.com/forgejo, use tea because fj 0.6 does not preserve the subpath when checking its account.

When cloning or publishing, use a full repository URL to select a specific server. You can use owner/repo when only one fj server is configured, or with your default tea login when fj is unavailable or unconfigured. With multiple fj servers, use the full URL. If you have multiple tea accounts on one server, select one with tea login default <login-name>. Git push and clone also need Git credentials or an SSH key for that server.

GitLab#

Install GitLab CLI, then sign in:

glab auth login

Bitbucket#

Open Settings → Source Control, expand Bitbucket, and enter one of:

• Access token: a token created for one repository, project, or workspace. It can only reach what it was created for.

• Atlassian account email and API token: an Atlassian API token for your account. It can reach every repository you can. Give it read/write access to repositories and pull requests, plus user read access (read:user:bitbucket).

A field saves when you leave it, and applies right away. The access token wins when both are saved. Credentials are saved on the environment's server, so select a remote environment to configure it. Saved tokens can't be viewed again; enter a new one to replace it, or choose Remove to clear everything saved for Bitbucket.

If no credentials are saved, T3 Code falls back to these variables in the server's environment. Restart the server after changing them:

export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token"
# or
export T3CODE_BITBUCKET_EMAIL="you@example.com"
export T3CODE_BITBUCKET_API_TOKEN="your-token"

Azure DevOps#

Install Azure CLI, add the DevOps extension, and sign in:

az extension add --name azure-devops
az login

GitCafe#

Install the GitCafe CLI and sign in:

bun install -g @gitcafe/cli
cafe auth login --host https://git.cafe/api

Alternatively, open Settings → Source Control, expand GitCafe, and enter a token. It is kept in the server's secret store, applies right away, and is used before CAFE_TOKEN and the cafe login. Or set CAFE_TOKEN in the server's environment and restart it. Both tokens are only sent to git.cafe; CAFE_TOKEN follows CAFE_HOST if you set it. Repositories on staging.git.cafe need their own login with --host https://staging.git.cafe/api.

Line comments, reviewer requests, and labels are not available for GitCafe pull requests yet. Merging a stack lands it through GitCafe, and updating a branch restacks the layers above it.

Start, clone, or publish a project#

To start from nothing, choose New project in the command palette (Cmd/Ctrl+K), or New project under Add Project on any client, and type a name. T3 Code makes a Git repository in ~/.t3/projects (the projects folder of your T3 data directory) with a README, an icon, and a first commit, then opens a new thread in it. Until the project has a thread, new threads work in its folder, even when your default is a new worktree. The folder is named after the project, like pinball-stats for "Pinball Stats". Turn on Create private repository on GitHub to also publish it. If Git has no name or email on that machine, the project is created without the first commit.

Use Add Project in the command palette (Cmd/Ctrl+K) to clone a repository. Choose a hosting provider or paste a Git URL, then choose where to save it. The project opens right away while the clone runs in the background: you can write your first prompt, and sending waits until the files are in place. A toast tracks progress and lets you cancel; if the clone fails, retry it from the toast or from the banner above the composer.

For a local Git repository without a remote, Publish Repository creates a hosted repository, adds it as origin, and pushes your commits. If there are no commits yet, it creates the remote; make your first commit before pushing.

Create a pull request#

Use a thread's Git actions to commit, push, and create a pull request. T3 Code can generate commit messages, review titles, and descriptions from your changes.

An existing fork PR can appear beside the branch even if you pushed without setting an upstream. If its badge is missing because several remotes hold that branch, set the branch's upstream to the intended remote with git branch --set-upstream-to=<remote>/<branch>.

Choose the writing style and model in Settings → Source Control. Repository conventions uses the project's instructions and recent commit subjects.

Review and merge#

Open Pull requests to review changes and comments, request reviewers, check out a branch, or merge. You can edit review titles and descriptions and your own comments where the host allows it. GitLab calls these merge requests.

On mobile, Pull requests lists reviews across your connected environments. Open a review to read its description, activity, commits, and changed files. Line comments stay as drafts until you submit the review. Work on PR opens a chat with the review attached; sending the first message prepares a worktree from the review's branch.

Previously loaded lists, review details, guides, and diff pages remain readable on mobile without a connection, including after restarting the app. Saved content refreshes when the environment reconnects; submitting changes requires a connection.

Enable Remove agent credits when merging in Settings → Source Control to remove recognized agent co-author and generated-by lines from GitHub merge and squash commit messages. Human co-authors stay credited. The setting is off by default and projects can override it. It also applies to auto-merge, but not merge queues or native stack merges. Original commits keep their messages, so merge and rebase can still retain agent credits in those commits.

On web and desktop, hold Shift in the GitHub pull request list for quick actions. To close several, press Close, drag across the rows in the same group, and release. Press Escape before releasing to cancel. Failed closes stay in the list so you can retry them.

GitHub, GitLab, and Azure DevOps support auto-merge while checks are outstanding. GitHub also supports approving waiting fork workflows and opening a revert pull request for a merged change.

GitHub sharing is off by default. In Settings → Connections → GitHub sharing (Environments on mobile), choose Read PRs or Read and act for each environment you trust to share GitHub access. Enable both the original environment and the environment answering its requests on this client. Read and act can use broader GitHub permissions than the original environment's credential; only enable it for environments you control and trust. Changing a saved endpoint or removing an environment clears its permission.

GitHub review details, linked PR status, and permitted review actions can then use another connected environment signed in to the same GitHub account. Each needs a project on that host. A connected local environment is preferred for actions and can answer slow or failed reads. Browsers and mobile clients need a paired environment to use its GitHub credentials. Credentials stay on their machines. Previously verified credentials remain usable for routing for ten minutes during a GitHub outage; new credentials must be verified first. An action with an uncertain result is never automatically retried elsewhere. Listings, diffs, and checkout or PR creation from Git actions continue to use the project's environment.

For Azure DevOps, use the host website to change comments. Bitbucket does not support reopening a declined pull request.

Review guides#

Review guides are in beta. Turn on Review guides in Settings → Source Control to add the Guide tab to pull requests on that server. On mobile, move between stops with Next and the back button; a stale guide offers a rewrite and hides excerpts that no longer match the current change.

The Guide tab gives you a tour of a pull request without reading it line by line: stops through the change in reading order. Each stop points at the lines worth reading, and a stop marked Look closely has a call only a maintainer can make. Mechanical changes such as renames and snapshots are grouped at the end, and every changed file appears somewhere on the tour. Conversations already resolved in review are left out. For a pull request in a stack, the guide covers that layer only, and may point out what a lower layer introduced or what a higher one uses.

Choose Write guide to have the review guide model from Settings → Source Control read the change in a temporary checkout; without one set, the source control writer model is used. Nothing in the checkout is changed, and a large pull request takes a few minutes; you can go elsewhere in the app. On web, you are told when the guide is ready; on mobile, return to the guide to check its progress. Claude and Codex can write guides. The guide is kept for everyone using this server. To write it again, for example after a push or after changing the model or instructions, choose Rewrite guide from the pull request's ⋯ menu.

On web, while reading a stop, select lines in an excerpt to add a comment to your review or ask an agent about them; comments wait with the ones from the Code tab until you send the review. Choose a suggested question, or Ask about this stop, to open a thread that already knows which stop you are on. Finish review on the last stop opens the review with everything you collected.

Agents can write guides too: ask one to prepare guides for a set of pull requests, and it starts them for you. Each is read through the project whose checkout has that repository.

To shape guides to your taste, write Review guide instructions in Settings → Source Control, such as what to show first or what to skip; projects can override them. They change emphasis and ordering, not the guide's layout or which files it covers.

Mark files as viewed#

Tick a file off in the Code tab once you have read it and it collapses; the toolbar keeps a running count. A tick belongs to the pull request rather than to a commit, so scoping the tab to a single commit keeps them. A file pushed to after you cleared it comes back marked Changed.

On GitHub these are GitHub's own viewed marks, so a review carries between T3 Code and github.com in either direction. Forgejo, GitLab, Bitbucket, and Azure DevOps expose no record T3 Code can read, so the server you are connected to keeps them instead: they follow you across the apps connected to that server, but the host's own site will not show them, and the count reads viewed in T3 Code.

On mobile, open a changed file and mark it viewed from its header. Viewed files collapse, and their marks follow the same rules as on web and desktop.

Troubleshooting#

• Not authenticated: run the provider's login command on the server, then rescan. For Bitbucket, check the credentials saved in Settings → Source Control, or confirm the running server received the environment variables.

• GitHub sign-in cannot be verified: update GitHub CLI to at least 2.81.0, or save a token in Settings → Source Control.

• Push fails despite a connected account: check the Git remote's credentials. SSH and HTTPS remotes can require separate setup from the hosting provider's API access.

• A review cannot load: open it on the host website while resolving connectivity, permissions, or rate limits.

Linked pull requests#

A thread can hold several pull requests, including reviews from another repository on the same host. Use Link pull request in the command palette or Linked pull requests panel, or right-click a pull request link in the conversation. Creating a pull request from Git actions links it automatically. Agents can link their pull requests with the link_pull_request tool.

Use Link this PR in a branch-detected badge's tooltip to keep it with the thread. From a review on the Pull Requests page, Link to thread lets you search for an active thread. The review header also lists the threads that link to it, including archived threads, so you can return to their context.

Thread badges show a stack's layer count or the current review number with a count of additional links. Clicking a badge with more than one review opens the Linked pull requests panel. On mobile, the Git overview lists linked reviews and their stacks; tap a review to open it. Linking and unlinking are available in the web and desktop clients.

The Linked pull requests panel lists every review and groups stacks. Unlink a review from its row menu. An unlinked stack layer stays out of later syncs. Open linked reviews refresh on the server; closed reviews refresh periodically so reopening one on the host is detected. Merged reviews refresh when requested. A settled thread's reviews stop refreshing until you unsettle it. With Auto-settle merged threads enabled, a thread can settle after every linked review is terminal. An open or unsynced link keeps it active.

Ask the agent to watch, monitor, or babysit a pull request and it calls watch_pull_request. While the thread is active, the server checks the pull request every two minutes and wakes the agent when a check fails, the required checks pass, someone else comments or reviews, or the branch starts to conflict. Threads in a project that watch the same pull request share one check. On GitHub, a check first asks whether anything changed and reads the pull request only when it did, which keeps watching inside GitHub's rate limit. Comments from your own account do not wake it. Watching ends when the pull request merges or closes, after 10 wakes in a row that bring only comments, after 8 failed reads in a row, or when you press Stop on the thread. A rate limit only pauses watching. Settling or archiving a thread also ends all its watches. Unsettle the thread before starting a new watch. Subagents cannot watch pull requests; the thread that delegated to them does. To start or stop it yourself, use the row menu in the Linked pull requests panel. In the thread details card, a watched pull request shows an eye; click it to stop watching.

A watched thread counts as working between wakes, so it stays in the Working section and does not auto-settle. Agents stop watching when they hand the work back to you, and the thread then returns to your inbox.

Cross-repository links use a project on the same host. Azure DevOps reviews require a project checked out from the matching organization and repository.

GitHub stacks#

The Pull Requests page shows each PR's position in its GitHub stack. Open the stack badge in a review to navigate its layers. Merge stack submits the selected pull request and every unmerged layer below it to GitHub together, respecting branch rules and merge queues. The confirmation shows the scope and merge strategy. GitHub rebases the remaining stack after merging.

Rebase stack updates remote branches from bottom to top without changing your local checkout. It can rewrite history and restart checks. If a layer fails, earlier updates remain; resolve that layer before retrying. GitHub may require manual conflict resolution after a lower layer is amended, even when its changes look independent. Stack actions require an environment that supports them.

Source: T3 Code documentation ↗

Providers

Choosing a provider#

Use the runtime you already work with#

T3 Code controls agent runtimes on the environment's machine. Open Settings → Providers, select that environment, and enable the providers you want to use. Provider installation, sign-in, and configuration happen on that machine.

Accounts and configuration#

Add a provider instance for a separate account or configuration. Instances can have their own environment variables, including API keys or custom base URLs. Mark secret values as sensitive; after saving, their original values are not displayed.

Provider CLIs must be on the server's PATH. Set Binary path when T3 Code cannot find a CLI. Managed Codex and Antigravity runtimes can work without a PATH entry.

Capabilities and compatibility#

Providers differ in permissions, models, context handling, and available tools. Check the relevant guide before relying on a capability. T3 Code warns about known provider-version compatibility problems and shows recommended versions in provider settings.

Use the provider card's Update now action when available. See installation for installer behavior and updates for keeping the app, servers, and providers compatible.

Guide based on T3 Code’s user documentation and glossary.

Providers

Codex#

Use your ChatGPT plan or an existing Codex CLI login to code in T3 Code.

Connect with ChatGPT#

Connect during onboarding or in Settings → Providers. For a remote machine, select that environment first. T3 Code handles Codex installation; sign in on OpenAI and allow sharing of your ChatGPT plan.

Manage shared usage and credits in ChatGPT through Manage usage in T3 Code. If a request uses a feature that ChatGPT sharing does not support, use another provider for that request.

When reconnecting, choose the same account in T3 Code and on OpenAI's sign-in page. Disconnecting stops running threads but keeps their history and lets you reconnect later.

If remote sign-in cannot return automatically, paste the full URL from the final localhost page into the sign-in panel, even if that page could not load.

Use an existing Codex login#

T3 Code can use your installed Codex and its existing login. Run codex login on the environment's machine to sign in. Provider setup covers installation and custom configuration.

Use multiple accounts#

Add another ChatGPT account in Settings → Providers, then select the account from the thread's model picker. Compatible accounts can continue the same thread. Connecting accounts through T3 Code leaves your CLI login unchanged.

Multiple CLI logins#

A shared Codex home with a shadow home lets work and personal accounts continue the same threads. The accounts share Codex sessions and configuration while keeping their own login and available models.

Keep your first account in ~/.codex. On the environment's machine, sign the second account into a fresh directory:

mkdir -p ~/.codex_personal
CODEX_HOME=~/.codex_personal codex login

Then add a second Codex instance in Settings > Providers:

Both instances must use the same CODEX_HOME path. T3 Code prepares the shared state in the shadow directory; do not populate it by copying your whole Codex home.

The shadow account needs its own auth.json file. If Codex uses an OS credential store, configure file storage for this setup. See OpenAI's credential storage guide.

Use a completely separate CODEX_HOME path, with no shadow home, when you want separate Codex sessions and configuration. That instance cannot continue threads from the other home.

Switch accounts in an existing thread#

Choose the other account from the thread's model picker. T3 Code offers compatible Codex instances that share the thread's CODEX_HOME path. Changing accounts does not move the conversation into a separate Codex home.

If the account is missing from the picker, compare the home paths in provider settings. If two instances show the same unexpected account or models, check their reported accounts, refresh provider status, and confirm the second instance has its own shadow path and login. A shadow-home conflict usually means the directory contains a copied Codex setup. Use a fresh shadow directory and sign in again.

Answer questions while Codex works#

Codex can ask a question and keep working. Answer it in the thread's question panel. The answer becomes a new message: it reaches the active turn, or starts another turn if Codex has finished. Unanswered questions survive reconnects. If you do not want to answer, dismiss the question from its panel. Dismissing closes it without sending anything to Codex. This requires a Codex version that supports async questions.

Approve app access#

Codex tools can request access to another app. Respond to the named app's request in the thread on web, desktop, or mobile. Some tools offer access for one request, the current session, or permanently. See Permission modes for command and file approvals.

Codex says I hit a usage limit#

When Codex stops on a usage limit, the thread names the window that ran out and when it resets, when Codex reports them. Send the message again after the reset. On a workspace plan the message also says whether your workspace owner needs to add credits or raise the spend limit to continue sooner.

Send feedback to OpenAI#

In an existing Codex thread, send /feedback with an optional description, for example /feedback The agent stopped before finishing the tests. This uploads the conversation and Codex logs to OpenAI. The returned thread ID can be shared with OpenAI support.

Source: T3 Code documentation ↗

Providers

Claude#

T3 Code uses Claude Code's login and configuration. Start with the default provider for one account; provider setup covers installation and shared provider settings.

Separate accounts or configurations#

Use a separate Claude config directory for each account. This also works for named presets that need different Claude settings or a router connection.

Keep your existing account in the default directory. On the environment's machine, create the second login:

mkdir -p ~/.claude_personal
CLAUDE_CONFIG_DIR=~/.claude_personal claude auth login

Add another Claude instance in Settings > Providers:

An empty config-directory setting uses Claude Code's normal configuration. The custom setting changes CLAUDE_CONFIG_DIR, leaving HOME and the system keychain location intact. Use the same variable for the login command. Setting HOME instead can put credentials where this provider will not find them.

Check the account reported in provider settings after signing in. Existing threads can switch only between Claude instances with the same config directory. Separate account directories stay isolated, including their local conversation state. Claude does not have Codex's shared-home and shadow-home arrangement.

For presets that differ only in API keys or endpoints, use the instance's Environment variables. Variable assignments do not belong in Launch arguments.

Claude Code's verbose mode can stay enabled when you use Claude for text generation, including thread titles, branch names, commit messages, and pull request descriptions. On a remote connection, T3 Code uses the Claude configuration on the connected server.

Compact long conversations#

Set Auto-compact after in the Claude provider settings to an integer between 100000 and 1000000. For example, 300000 asks Claude to summarize at about 300,000 tokens. This changes when compaction happens, not the model's context window. Leave it empty for Claude Code's default.

You can also send /compact in an existing conversation. Web and desktop offer Compact context from the context meter. When you return to a large thread after Claude's prompt cache expires, a Compact chip with the thread's token count shows next to the send button. While it is on, Enter summarizes the history first, then sends your message. Click the chip to switch it to Full and keep the full history for that message. The cache lasts about an hour on a Claude subscription and 5 minutes with an API key, Bedrock, or Vertex. See commands and skills for using composer commands.

Usage limits#

If your Claude subscription runs out of usage mid-turn, the thread shows which limit was reached and the remaining wait when Claude provides a reset time. Claude Code holds the turn until that window reopens, so it can keep showing as working. Wait for the reset, or stop the turn and continue later. The warning's timestamp shows when the displayed wait started.

Skills#

Claude skills come from the config directory's skills folder and the project's .claude/skills folder. If both define the same name, the config-directory copy wins. Skills disabled in Claude's settings do not appear in the composer.

Use $ in the composer to select a skill. Skills marked disable-model-invocation can still be started by you. Invoke those one per message: Claude directly runs only the last named skill and may try to start earlier ones through its Skill tool, which refuses skills reserved for manual invocation.

OpenRouter#

Create a Claude instance with its own config directory, such as ~/.claude_openrouter, and keep Binary path set to claude. In that instance's Environment variables, use:

If that Claude config directory has a cached Anthropic login, run /logout in a Claude Code session using that directory before starting the router setup. Cached login credentials can conflict with the router token.

Select the model you want in T3 Code. For an OpenRouter model outside the built-in list, open that Claude instance in Settings > Providers and add its full model ID with Add custom model. Then select it in the chat model picker. ANTHROPIC_DEFAULT_*_MODEL variables map Claude Code aliases such as sonnet; they do not replace the explicit model ID selected in T3 Code. Custom models may have fewer effort, thinking, or context controls than built-in models.

Verify the model used in OpenRouter's activity dashboard. For current compatibility requirements, use the OpenRouter Claude Code guide.

Other routers#

A local router uses an ordinary Claude provider instance. Give it a separate config directory and put the router's endpoint and credential variables in that instance's Environment variables. The router must run where the environment can reach it. Follow the Claude Code Router instructions for its installation and routing configuration.

Source: T3 Code documentation ↗

Providers

Cursor#

Cursor V2 runs through the official @cursor/sdk TypeScript package. It does not use Cursor's ACP transport for V2 execution.

Prerequisites#

• Node.js 22.13 or newer. The repository's supported Node version satisfies this requirement.

• Sign in with Cursor in Settings > Providers > Cursor, or provide a Cursor API key in CURSOR_API_KEY.

• A model accepted by the Cursor SDK. auto is sent to the SDK as its default model selection.

The adapter currently uses the SDK's local-agent runtime so runs operate in the selected T3 Code workspace. Cursor cloud agents need repository and cloud-environment configuration that T3 Code does not expose yet.

Sign in#

Choose Sign in, then open the sign-in page and complete it in your browser. T3 Code updates automatically when sign-in finishes. This works when connected to a remote environment too. On mobile, use Settings > Provider accounts for an already configured Cursor instance.

Each provider instance keeps its own login on the environment that runs it. Your Cursor editor and CLI login are separate. A configured CURSOR_API_KEY overrides browser sign-in; remove that override to use the browser flow.

Use Change account or Sign out in the same settings section. Both stop that instance's running threads and keep their history. Sign-out forgets the saved credential; to revoke the generated key before it expires, remove it from your Cursor dashboard's API keys.

V2 Capability Mapping#

The adapter supports:

• creating and resuming local Cursor agent threads;

• changing the model and model parameters between turns;

• assistant text, reasoning, tool activity, plans, and todo streaming;

• thread-scoped T3 Code MCP tools;

• image attachments;

• interruption, queued app messages, and orchestrator-owned interrupt/restart steering;

• provider conversation snapshots through Agent.messages.list();

• Cursor task subagents, projected as read-only child app threads with their tool activity and final result.

The public SDK does not currently expose native agent fork, conversation rollback, active steering, or interactive approval callbacks. Direct active steering is advertised as unsupported, while V2 steering uses the orchestrator's interrupt-and-restart path and preserves the app run identity across provider turns. Same-provider Cursor forks use the orchestrator's portable full-thread context handoff into a fresh Cursor agent. The SDK has in-process custom callback tools, but the V2 adapter intentionally uses the authenticated, thread-scoped MCP server instead.

Portable handoffs summarize eligible timeline items and can omit the end of long messages. Read Context in portable handoffs before using a fork for work whose exact instructions must carry forward.

Cursor task events include an agentId, but the local SDK does not register that identifier as a resumable agent: Agent.resume() returns AgentNotFoundError. The adapter therefore does not attach a provider thread to native task projections or advertise subagent thread IDs. A projected child is read-only: send messages from the parent thread.

Runtime modes map to the controls the local SDK exposes: full access disables its sandbox, while restricted modes and explicit non-full-access sandbox policies enable it. Explicit approval policy overrides also control Cursor Auto-review. Auto-review is not represented as an interactive T3 Code approval flow.

The existing Cursor binary path and API endpoint settings belong to the CLI/ACP integration. Cursor V2 execution does not launch that binary, and the SDK does not expose an API endpoint override.

Replay And Live Testing#

Cursor replay fixtures preserve the SDK boundary: agent open/resume, sends, ordered onDelta updates, terminal results, cancellation, message snapshots, and close. The real V2 adapter, orchestrator, event store, projections, and checkpoint logic still run in tests.

Record a fixture against the real SDK with:

pnpm --filter t3 record:cursor-replay --scenario simple

Use --out <path> to record a temporary probe without replacing a checked-in fixture. Supported scenarios are listed by the recorder when an invalid scenario is supplied.

Source: T3 Code documentation ↗

Providers

OpenCode#

Install and authenticate OpenCode on the machine running your environment, then enable it in Settings > Providers. See provider setup. T3 Code requires OpenCode 1.14.19 or newer, including when you connect an existing OpenCode server.

OpenCode 2#

T3 Code supports OpenCode 2.0.18 and newer. It detects the version on its own, so the same provider settings work for OpenCode 1.x and 2.x. OpenCode 1.x shows Limited support in its provider settings.

OpenCode 2 is a separate package, @opencode/cli. To move from 1.x, install it yourself, for example npm install -g @opencode/cli. Then refresh provider status. T3 Code's update button updates whichever package you have installed. It never switches a 1.x install to 2.x.

OpenCode 2 converts the shared OpenCode database to its own format the first time it runs. Don't run OpenCode 1.x and 2.x side by side on the same machine. Threads you started on 1.x continue on 2.x.

Plan mode uses OpenCode's plan agent.

Local or external server#

Leave Server URL empty to let T3 Code start OpenCode locally. A password in provider settings applies to both that server and T3 Code's connection. With no password setting, the local server uses OPENCODE_SERVER_PASSWORD from its environment.

To use an existing OpenCode server, set Server URL and its password in provider settings. T3 Code uses only that configured password for an external server; it does not forward a local OPENCODE_SERVER_PASSWORD. If connection or version checks fail, check the URL, credentials, and OpenCode version, then refresh provider status.

After a lost connection, send another prompt to reconnect to the same OpenCode session.

Approvals#

OpenCode follows the shared permission modes. Auto has the same rules as Supervised because OpenCode has no AI approval reviewer. Environment files such as .env and .env.local need approval in restricted modes even though normal file reads do not; .env.example is allowed.

Allow for workspace applies to matching requests in other OpenCode sessions using the same workspace. It is broader than the current thread, especially on a shared external server. Use Allow once for a single request. Denying an action does not stop the whole turn.

Refresh models, commands, and skills#

After changing an OpenCode login or configuration, use Refresh provider status in Settings > Providers for that environment. On mobile, use Refresh models in the thread settings. Reconnecting also refreshes the catalog; periodic provider health checks do not.

Credential changes are read on refresh. Native OpenCode configuration can remain cached while the local helper is running. Let it sit for 30 seconds without model refreshes or text-generation work, then refresh again to reload the files. Repeated refreshes keep the helper alive. An external server may need its own reload or restart before T3 Code can see configuration changes.

Existing threads keep their selected model and options even when it disappears from the catalog. If OpenCode rejects that model, select an available one and retry.

Source: T3 Code documentation ↗

Providers

Antigravity#

T3 Code runs Google's official Antigravity ACP agent on your selected environment. It has its own sign-in, separate from the Antigravity IDE or CLI. Google controls which models and account access are available through this agent.

Set up Antigravity#

On web or desktop, open Settings > Providers, choose the environment that runs your project, and enable Antigravity. Install its runtime there, then choose Sign in and complete the browser sign-in. Wait for T3 Code to confirm account access and load models before starting a thread. Once the runtime is installed, you can also sign in from Settings > Provider accounts in the mobile app.

Installation continues if you leave settings or reconnect. Setup requires permission to operate the environment; update an older server if it does not offer Antigravity setup.

Sign in from a remote device#

Google returns to a 127.0.0.1 address. It can finish directly when your browser is on the environment's machine. From another device, the final page will usually fail to load because the sign-in listener is on the environment.

Copy the full return address, including everything after ?, into the return URL field in the client where you started sign-in, then choose Continue. Keep the original address; do not replace it with the server's hostname. Only that T3 Code sign-in session can finish the attempt. If it expires, retry sign-in and use the new link.

The return URL contains a temporary sign-in code. Paste it only into the setup field. A successful callback page alone does not confirm account access; wait for T3 Code's confirmation.

Other sign-in methods#

Choose Sign-in method in the Antigravity provider settings:

The Antigravity API key field is stored in plain text in settings on the environment. The agent uses the method and credentials selected for this instance; ambient GEMINI_API_KEY and Google credential variables do not override them. Changing the method stops the instance's sessions. Sign out before replacing an account.

Runtime installation#

Managed installation supports Apple Silicon macOS, Linux x64 or ARM64, and Windows x64 or ARM64. Intel Macs can connect to a supported remote environment. Allow several GB of free disk space, especially on Linux.

Use a manual installation#

Download the archive for your environment from the official ACP Registry. Extract the ACP executable and its localharness_external helper into the same directory, at the same version. Make both executable on macOS or Linux; Windows uses .exe files.

Set Binary path to the ACP executable on the environment and update it yourself. Leave the field blank to use the managed runtime, or a compatible executable on PATH if no managed runtime is installed.

Models and threads#

The model list comes from your Antigravity account and can differ from other Antigravity apps. A resumed thread keeps its selected model. If access to that model ends, select another available model before continuing.

Use Antigravity's native /plan command for planning. T3 Code's separate Plan mode is unavailable. Tool approvals follow Permission modes. Questions with fixed choices still need one of the offered answers, even in Full access.

T3 Code keeps conversation history and file diffs, but Antigravity cannot rewind its conversation. Reverting a thread or editing and resubmitting an earlier turn is unavailable. Continue with a follow-up message or start a new thread.

Skills and attachments#

Put project skills in .agents/skills. T3 Code also reads .gemini/skills and the legacy .agent/skills directory. Among these project locations, the first copy wins in this order: .gemini/skills, .agents/skills, .agent/skills. See commands and skills for invoking them.

Skills for every project go in ~/.gemini/config/skills or ~/.gemini/antigravity-cli/skills. Antigravity does not read ~/.agents/skills, so a skill there only appears when the project itself is your home directory.

Antigravity receives images directly. Every other attachment, including PDFs, text, audio, archives, and videos, is passed as a saved file path for the agent to inspect with its tools. A video path does not enable native video input.

Subagents#

Antigravity groups subagent activity into batches. You cannot open or control individual subagents, and an idle batch does not confirm that every child succeeded. See agent work for where to inspect activity.

Accounts and removal#

Add an Antigravity provider instance for each Google account in Settings > Providers on web or desktop. Each has its own sign-in; downloaded runtimes are shared on the environment.

All three keep thread history and workspace files. Sending /logout by itself in a thread signs out its instance, including stopping that instance's other sessions. Sign out, then sign in again to replace an account.

Before removing a managed runtime, disable its instances and cancel any active installation. Clear any explicit binary path pointing into that runtime. Removal is refused while the runtime is in use.

Check access and troubleshoot#

Open Usage > Limits to see the remaining Gemini and shared Claude/GPT allowances for Google sign-ins. Each group has separate five-hour and weekly limits and reset times. Limits refresh with provider status and include usage outside T3 Code.

A server restart keeps your Google sign-in. The provider shows the saved account until a session, a refresh, or a sign-out reports something new.

To check access and reload models, use Refresh provider status in web or desktop provider settings, or Refresh models in mobile thread settings. If asked to sign in again, use provider settings on web or desktop, or Provider accounts on mobile.

If Google reports SUBSCRIPTION_REQUIRED, an account restriction, or a usage limit, follow the provider's message and any retry time. See Google's account plans for eligibility.

Source: T3 Code documentation ↗

Providers

Pi#

T3 Code can use your existing Pi coding agent installation while keeping Pi's models, auth, extensions, skills, context files, and native session history.

Set Up Pi#

1. Install Pi on the machine running the T3 Code server. Pi requires Node.js 22.19 or newer; its platform installers can install Node if needed. T3 Code supports Pi 0.80.5 or newer.

2. Run pi in a terminal, then /login to connect your model provider or configure its API key.

3. Open T3 Code Settings, enable Pi, and refresh the provider.

For an npm installation, use:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

If pi is not on the server's PATH, set Pi's binary path to the executable. Provider environment variables and launch arguments are also available for installations that need a custom agent directory, endpoint, or model configuration. --provider must be paired with --model. T3 Code rejects launch arguments that change Pi's execution mode or select a session because T3 owns those parts of the process lifecycle.

On a remote or headless server, connect to that machine over SSH and run pi, then /login. Open the authorization URL on your own computer. If the callback cannot reach the server, paste the final redirect URL or authorization code back into Pi when prompted. You can also set your model provider's API-key environment variable in the Pi instance's settings; mark secret values as sensitive.

Update installer-managed Pi with pi update. If another package manager owns the installation, update it through that manager instead. For example, a Nix profile installation uses nix profile upgrade pi.

What Carries Over#

T3 Code discovers the models reported by Pi and exposes their supported thinking levels. The thinking picker marks the discovered active model's configured level as its default without overriding it. Other models keep their Pi defaults when no level is selected. Threads use Pi's native session files for resume, rollback, and forks within the same Pi instance. Forks preserve the native conversation through the selected turn in the destination workspace. Switching providers uses portable conversation context. Extension dialogs appear in the T3 Code composer, and the composer context meter follows Pi's own usage reporting while a response streams and after it settles.

Pi skills appear in the composer's $ menu. This includes user skills and project skills that Pi loads for the current workspace; selecting one uses Pi's native skill expansion.

Pi loads its normal user and project extensions. Blocking select, confirm, input, and editor dialogs work in T3 Code. Notifications appear in the work log. Pi terminal decoration such as titles, status lines, and widgets does not have a T3 Code equivalent.

Permission Modes#

T3 Code applies the composer permission mode through Pi's blocking tool hook:

• Supervised asks before commands, file changes, and extension tools. Read-only tools continue.

• Auto-accept edits allows Pi's edit and write tools, but asks before commands and extension tools.

• Full access allows tools without T3 Code approval prompts.

The Auto option is not shown for Pi because Pi does not expose an AI approval reviewer. Threads that already stored Auto before Pi support was added behave and display as Supervised.

Changing the mode restarts the Pi provider session and resumes the same native conversation. The policy covers Pi tool calls; it is not an operating-system sandbox, and code that a trusted Pi extension runs outside a tool call remains governed by Pi's own extension trust model.

T3 Code's delegate_task tool creates durable child threads in the shared subagent UI. If the user installs Pi's example subagent extension, T3 Code also shows its task progress and results in that UI. Pi runs those children without a session, so they cannot be opened or resumed as T3 Code threads.

Troubleshooting#

• If Pi is unavailable, confirm that the configured binary runs on the server machine, then refresh the provider in Settings.

• If no models appear, open Pi directly and confirm its authentication and model configuration.

• If discovery cannot complete, T3 Code keeps Pi available with the Pi default model. Start a thread to let the interactive Pi session handle any startup prompt.

• If a project extension is missing, approve the project in Pi, then start a fresh provider session.

• If a project skill is missing from the $ menu, approve the project in Pi and refresh the provider.

• The context meter appears once Pi reports usage for the thread. Some model providers only report usage when a response completes, so the meter can wait for the first reply.

Source: T3 Code documentation ↗

Providers

Muse Code#

Muse Code is a beta integration and is disabled by default. Install Muse Code on the machine hosting your environment, then run muse login as the account that runs T3 Code.

Open Settings → Providers in the web or desktop app, select the environment, and enable Muse Code. Set Binary path if Muse is not on the host's PATH. Refresh provider status after installation or login, then select Muse in a thread's model picker.

Provider status does not check your login. If you are signed out, messages fail until you run muse login on the host.

Sign-in and API keys#

T3 Code ignores a META_API_KEY that the T3 server inherits from its own environment, so Muse uses the credential saved on the host by muse login. To use an API key instead, add META_API_KEY to the Muse instance's environment variables in Settings → Providers. Muse gives that key priority over the saved login.

Remote access and instances#

Connect from web, desktop, or mobile through remote access. Muse uses the selected environment's files and login; connecting devices do not need Muse installed. Install and sign in separately on each host where you want Muse to run.

Add a provider instance for a separate configuration. Instances on the same host share its Muse login; give an instance its own META_API_KEY to bill it separately. Existing conversations retain their instance when its model catalog becomes unavailable.

Models#

Models and reasoning choices come from Muse on the selected host. After changing Muse configuration, refresh provider status in Settings → Providers. On mobile, pull down in thread settings to refresh models. If a saved model becomes unavailable, select an available model before sending another message.

Muse can list models that your account cannot use. If a message fails with "does not exist or you lack access", pick another model, or add one your account can use under Custom models in the instance settings.

Permissions and limitations#

Muse offers two permission modes: Supervised asks before commands and edits, and Full access runs them without asking. Muse has no equivalent of Auto-accept edits or Auto, so they are not offered. Muse does not offer a separate Plan mode in T3 Code.

Muse can use T3 Code's tools. If Muse cannot reach them, the turn continues without them. Switching providers can pass conversation context as a handoff.

Muse skills do not appear in the composer's $ menu. Muse still loads them itself. Manage them with muse skills on the host.

Forking a Muse conversation starts a new session with a copy of the conversation context. Conversation rewind is unavailable.

Install Muse and sign in on the host; in-app installation and sign-in are not available. Updates can run from Settings → Providers when T3 Code recognizes the Muse launcher; otherwise update Muse on that host manually.

To stop using Muse in an environment, disable it in Settings → Providers. This keeps the host's Muse login, thread history, and workspace files.

Source: T3 Code documentation ↗

Providers

ACP agents#

T3 Code can run installed ACP commands or coding agents from the official ACP Registry. Registry agents bring their own models, tools, and sign-in, while T3 Code provides projects, threads, checkpoints, and task delegation.

Google Antigravity is available through its official antigravity-acp Registry entry. Add it like any other Registry agent; it does not need an Antigravity-specific T3 Code provider.

T3 Code prefers the current ACP v2 preview protocol and uses its richer messages, usage, plans, configuration, compaction, and agent-terminal updates when the agent supports them. It also negotiates ACP v1 for Registry agents that have not migrated yet, so agents such as Pi continue to work through the same generic integration.

Add an agent#

1. Open Settings → Providers.

2. Select Add provider and search the ACP Registry.

3. Search for the agent and select Add on its result.

4. Confirm the name and instance ID, then complete the agent's sign-in step.

Search only shows agents that can run on the connected server. Registry agents are third-party code; review an agent's source and license before adding it.

Add a local command#

In Settings → Providers → Add provider, select Local ACP command. Enter the executable name or path on the selected environment, add one literal argument per row, and choose a display name. For DeepSeek Harness, use dsh with arguments --profile and acp.

Local commands require no registry entry or download. Environment overrides apply to the command; credentials and skills remain managed by the installed agent or its wrapper. Models and reasoning options come from ACP, including model IDs that contain JSON. T3 Code launches the executable directly without expanding shell expressions.

Where agents run#

Registry agents always run on the machine that hosts your T3 Code server. That stays true when you connect through app.t3.codes, T3 Connect, or a relay.

Agents install under tools/<agent-id>/<version>/ inside T3 home. T3 Code verifies SHA-256 when the Registry entry provides one; entries without a checksum retain the Registry's HTTPS distribution guarantee. Registry npx and uvx packages use T3-owned npm prefixes and Python tool directories at the exact version published by the Registry. Their commands are available in a new server terminal for sign-in and direct use. Removing an agent's last provider instance removes T3-managed binary files but keeps package installs. To use an existing local binary, set Executable override explicitly.

Signing in#

Open the agent's account section in Settings → Providers on web or desktop. Choose Sign in and, if the agent offers several methods, select one. For an installed, configured provider, mobile also offers Settings → Provider accounts.

Browser sign-in shows the agent's URL and waits for you to open or copy it before telling the agent to proceed. The page opens on your device, while the agent runs on the environment. Terminal methods run in an in-app terminal on that environment. On mobile, send responses through the terminal response field. T3 Code reconnects after terminal login and waits for the agent to confirm sign-in before reporting success. You can cancel or retry an expired attempt.

Browser and terminal sign-in leave credentials in the agent's own store. Agents that use API keys through environment variables still take those keys in the instance's environment settings. A configured environment or agent home applies to both sign-in and chat.

If the agent advertises logout, choose Sign out. Changing a shared agent login stops running threads for instances of that same agent on the environment. Thread history and workspace files are kept. ACP does not describe account isolation, so adding another instance does not guarantee a separate account; use the agent's own configuration to isolate accounts when supported.

If an agent cannot complete its advertised flow remotely, its CLI remains available on the server. For example, Codex supports codex login --device-auth, and Grok Build supports grok login --device-auth.

Models and options#

The model picker lists the models the agent reports. If the agent reports none, or hides some, add your own model IDs under Custom models in the instance settings.

Other settings the agent offers, such as reasoning effort or approval mode, appear in the composer's model options menu like they do for built-in providers. Agents with their own plan and build modes follow T3 Code's Plan and Build toggle. Models and options that change while an agent is running update the picker without waiting for another provider probe.

Commands and skills#

Slash commands the agent provides appear under Provider in the / menu while a session is running. Commands the agent names with a $ prefix appear in T3 Code's $ skill menu instead.

Native sessions#

When an agent advertises ACP session listing and import support, expand its provider card, choose a project, and select List sessions. Importing one creates a deterministic T3 thread backed by that native session. Importing the same agent session again returns the existing thread, including when another client performs the import.

The thread keeps the native session's title and last-update value as provider metadata without overwriting a title you set in T3 Code. Agents that report ACP context usage drive the composer's context meter and cumulative cost metadata. Text resources and links render as assistant output; binary resources, images, and audio that T3 Code cannot render yet appear as explicit placeholders instead of disappearing.

Permissions and terminals#

Registry agents read files, edit, and run commands themselves, under their own sandbox and approval rules. They start in their own default mode, and their mode picker in the model options menu switches it. How far an agent is confined depends on that mode and the agent's own settings, so use its sandbox and permission controls when that matters.

When a registry agent asks for approval, T3 Code answers by the thread's permission mode: Supervised shows the request in the conversation, Auto-accept edits approves edits and shows the rest, and Auto and Full access approve automatically. File reads and searches never wait for approval.

Devin runs its commands through T3 Code's terminals, and those commands follow the thread's permission mode. For other agents, T3 Code shows the command, output, and exit status the agent reports but does not run or stop their terminals.

Registry agents can schedule work and use T3's MCP tools. Child-task presentation depends on what the agent exposes: ACP has no portable native subagent-lineage contract, so richer delegation views remain agent-specific.

Checkpoints#

Checkpoint rollback restores your files as usual. ACP agents cannot rewind their own conversation, so the next turn after a rollback starts a fresh agent session that no longer remembers the conversation from before the checkpoint.

Registry instances are not used for T3's app-owned text generation, such as thread titles, commit messages, branch names, or pull request descriptions. Configure a text-generation-capable provider for those actions.

Advanced configuration#

• Executable override runs an existing local executable instead of the managed distribution, keeping the registry-declared arguments and environment.

• Authentication method picks a specific method when the agent advertises more than one.

• Custom models adds model IDs the agent does not report.

Source: T3 Code documentation ↗

Connected machines

Remote & mobile access#

Connect a phone, browser, or another desktop app to T3 Code running on a different machine. That machine must stay running and reachable while you work.

T3 Connect#

T3 Connect makes an environment available to your other devices without setting up router forwarding. In the desktop app on the host, open Settings → Connections, sign in, and enable T3 Connect for that environment.

For a command-line host, run:

t3 connect

Follow the sign-in instructions. Setup offers a background service; if you decline it, start the server with t3 serve. Saving your sign-in alone does not make the machine reachable.

On your other device, sign in to the same T3 Connect account and choose the environment. Over SSH, the CLI prints a browser link and a short code. Open the link on any device, confirm the code matches, and approve. The CLI continues on its own, so you do not need to forward an OAuth callback port.

T3 Connect renews access credentials when needed without disconnecting a healthy connection. Pull request diffs and provider settings keep working after the previous credential expires. A failed renewal affects that request; it does not disconnect an otherwise healthy conversation.

Pair over a LAN or private network#

Use direct pairing when the other device can reach the host's network address.

On a desktop host, open Settings → Connections, enable Network access, then create a pairing link using an address the other device can reach. Changing network access restarts the desktop app. You can turn it off in the same place.

For a command-line host, replace <private-ip> with the host's LAN or tailnet address:

t3 serve --host <private-ip>

If a server is already running, generate a fresh link without restarting it:

t3 pair

Scan the QR code on your phone or paste the pairing URL into Add environment in the receiving app. Connection settings are under Settings → Connections on web and desktop and Settings → Environments on mobile. A loopback address such as 127.0.0.1 reaches only the device opening the link.

Pairing authorizes that device for future connections. Use a fresh one-time link for each new device; you do not need the original token to reconnect. Links created in Settings can only be copied from the client that created them while its Connections page stays open. If you leave or reload that page, create another link to share.

Reach one machine several ways#

A machine can have more than one route: LAN, Tailscale, another VPN, a public URL, SSH, or T3 Connect. Tailscale shares its 100.64.0.0/10 address range with other VPNs such as Cloudflare WARP, so an address in that range shows as VPN unless the machine confirms it is on Tailscale. To add a route, choose Add route in the machine's route list, or next to it in the T3 Connect list. Pairing the same machine again over another address also adds a route instead of a second machine. A new route is placed by speed, in that order, and you can reorder routes at any time.

While connected through T3 Connect or a paired address, T3 Code also learns the machine's current LAN and Tailscale addresses and adds them as routes, so pairing once through T3 Connect is enough to use the LAN at home. When the machine's LAN address changes, for example after it joins another Wi-Fi network, the learned route follows it. The machine must allow network access for its LAN address to be learned. You can reorder a learned route, but not remove it; it goes away with the route it was learned through, or when the machine stops reporting that address.

T3 Code connects over the first route that answers. Away from home, a LAN address that does not answer is checked briefly and skipped. It is only tried again, after the other routes, if none of them connect. While connected over a later route, T3 Code checks the earlier ones when your network changes, when you return to the app, and every minute, and moves back as soon as one works.

On web and desktop, select the route count under the machine's name in Settings → Connections to see its routes. Drag a route to change the order, or remove it. On mobile, open the machine under Settings → Environments and choose Edit. Signing out of T3 Connect removes only that route; a machine you can still reach another way stays saved.

Open Permissions next to Routes in web or desktop, or Your permissions in the mobile route details, to see what your current connection can do on that environment. For a remote environment, this is in its route details. Permissions shown there apply only to the route marked In use; other routes are not checked. Direct pairing and T3 Connect have separate sessions and may grant different permissions.

Balance new threads across machines#

Auto balance is off by default. On web and desktop, enable it in Settings → Connections → Load balancing to automatically choose a machine for new threads in projects grouped across connected environments. The section appears once two or more machines are switched on. Each machine starts at Normal. Choose Prefer to favor it when it has CPU and memory available, Less often to reduce its share, or Manual only to exclude it from automatic selection. These are preferences, not fixed traffic percentages. Preferences are saved separately in each client.

The composer checks eligible machines when choosing a draft's environment, then keeps that choice stable. Choose Auto balance again to check current resources, or choose a specific machine to override it. Choosing a branch or worktree also keeps the draft on that machine. Existing threads stay where they started. If resource checks are unavailable or all eligible machines are full, choose a machine manually to continue. Mobile keeps its manual environment selection.

Tailscale HTTPS#

Join both devices to the same tailnet. In the desktop app, enable Tailscale HTTPS in Settings → Connections. Turn it off there to remove that route.

To start a command-line server with Tailscale HTTPS:

t3 serve --tailscale-serve

For an already-running server:

t3 pair --tailscale

The pairing link uses an address such as https://machine.tailnet.ts.net/. The mapping created by pair --tailscale persists across restarts. Remove its default-port mapping with:

tailscale serve --https=443 off

If that port is already in use, choose another with --tailscale-serve-port. See t3 pair --help for other pairing options.

Hosted web app#

app.t3.codes needs an HTTPS endpoint. It connects directly to your server; a hosted pairing link does not make an unreachable backend reachable or convert HTTP to HTTPS.

For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can open it, or pair from the desktop app. On mobile, an IP address entered without a scheme uses HTTP, so include https:// when your server uses HTTPS.

Desktop-managed SSH#

In the desktop app, open Settings → Connections → Add environment, choose SSH, and enter a host or SSH alias such as user@example.com. T3 Code starts or reuses a server there and opens the port forward for you. Projects, provider credentials, and agent work stay on the remote machine.

The remote host must be Linux or an Apple Silicon Mac with curl or wget, tar, sha256sum or shasum, and provider setup. The first launch downloads T3 Code's server to ~/.t3/runtime on the host, so it takes longer than later ones. Provider CLIs must be on the PATH of a non-interactive login shell there; check with:

ssh user@example.com 'sh -lc "command -v claude codex"'

If SSH reconnecting fails after an app update, retry the launch once. Removing the connection stops a server that T3 Code launched; a server that was already running is left alone.

For Antigravity's Google callback on a remote host, see remote sign-in.

Browser on a remote environment#

Browser tabs belong to the environment, so you and your agents see the same tabs from any device. The desktop app shows its own environment's tabs directly. Every other device, and the desktop app for other environments, streams them from the host. Agents keep using them while no device is connected, and localhost addresses reach servers on the host.

The first tab downloads a headless Chrome, about 120 MB, into the T3 home. It is the same browser HTML renders use, so a host downloads it only once. Some Linux hosts need setup before it can start.

Agent tabs have separate storage and share a Chromium process. Take control before typing into an agent's tab, then release control when you want the agent to continue. Read-only connections can watch without changing the page.

While you have control, the tab works with your device: text the page copies or cuts goes to your clipboard, a file picker on the page opens your device's picker, and a finished download is offered for you to save. Popups such as sign-in windows open as their own tabs. Downloads stay on the host until the tab closes. Audio does not play on your device.

On a phone, tap the floating preview's corner dot to show its controls, then Pop into separate window to keep watching in picture-in-picture over other apps.

Browser host setup#

macOS, Windows, and Linux desktops run the browser as is. Some Linux hosts need one-time setup: Ubuntu 23.10 and later block the sandbox the browser runs in, and minimal images and containers lack libraries it loads. When that happens, the server says so at startup, and browser tabs and HTML previews show the command to run on the host:

sudo t3 browser setup

The server shows the exact line for how you started it, such as sudo npx t3 browser setup, and keeps your PATH when Node is installed only for your user. Where t3 is not on your PATH, such as with only the desktop app installed, it names the full path of the app's own t3 instead. It allows Chrome's sandbox with an AppArmor profile and installs any missing libraries with apt. It is safe to run again. Without sudo, it only reports what it would change.

The browser always runs in Chrome's sandbox. Where you cannot change the host, set T3CODE_SERVER_BROWSER_SANDBOX=0 for the environment to run without it.

Connect an outside agent#

Claude Code, Codex, ChatGPT and other agents T3 Code did not start can drive threads on an environment through its MCP server. See outside agents for setup.

Manage or revoke access#

On the host, Settings → Connections lets authorized administrators create pairing links and revoke client sessions. Revoking an unused link prevents new pairings; revoke a device's session to remove its existing access. Command-line management is available through t3 auth --help.

A session with an open connection stays listed after its access credential expires.

To choose a token's permissions, pass --scope once for each scope you want:

npx t3 pair --scope orchestration:read --scope relay:read

The selected scopes replace the default permissions. The same option works with npx t3 auth pairing create and npx t3 auth session issue; each command's --help lists the available scopes. Without --scope, pairing tokens retain standard client permissions and issued bearer sessions retain administrative permissions.

To change an existing client's permissions, create a fresh pairing link with the scopes it needs. In a browser opened directly on the environment, open that link to replace the browser's current grant. For mobile or a saved remote environment in web or desktop, use Add Environment with the fresh link or code; pairing the same environment replaces its saved grant. Reconnecting alone does not change permissions.

Grouping checkouts does not combine their permissions. Shared project settings require orchestration:operate on every member environment; actions on one checkout use that checkout's permissions.

source-control:write covers direct Git and pull request changes made from the client: pushing, switching or creating branches, cloning, and removing worktrees. It does not restrict what a task does. Starting a task in a new worktree still creates that branch and worktree with orchestration:operate, and the agent it runs can use Git however the environment allows.

Settings changes, provider management, and environment maintenance can be granted separately from access administration. New standard pairings include these permissions. Existing clients can stay connected after an update, but newly separated features may require pairing again with the permissions they need. Older clients may show controls that the server denies. Create a fresh pairing link to change a client's permissions.

filesystem:read allows browsing host files, opening workspace files, and viewing local changes. Add filesystem:write to allow editing files or saving plans to the workspace. These scopes control direct file access from the client.

To remove an environment from T3 Connect, open your account menu's T3 Connect page, or Settings → T3 Connect on mobile, and choose Deregister. This revokes its cloud access and frees its host space even when the environment is offline or has been wiped. Removing an environment from a device's connection settings only forgets it on that device; it stays registered to your account.

When idle tunnel cleanup is enabled, T3 Connect removes a linked environment's tunnel after it stays offline for several minutes. The environment stays linked and keeps the same address. When the host starts again or wakes, T3 Connect creates a replacement tunnel on its own. You do not need to pair again. Cleanup usually runs five to ten minutes after the tunnel goes down.

T3 Connect also removes the tunnel of an environment running an older version of T3 Code once it has been offline for seven days. That environment shows a message asking you to update. Start T3 Code on that computer and update it to the latest version; it reconnects at the same address without pairing again.

On a command-line host, t3 connect unlink disables exposure while retaining your login; t3 connect logout also clears that login. Background-service removal is separate.

Treat pairing URLs and authorization codes as passwords. Do not include them in screenshots, logs, or bug reports.

T3 Connect troubleshooting#

Run t3 connect status on the host to inspect saved authorization and link configuration. It is not a live reachability check. If the environment appears offline, run t3 service status and read the displayed log. If it disappears when SSH closes, see background-service troubleshooting.

After fixing a permanent rejection, restart the host's server. On Linux, use systemctl --user restart t3code.service for the background service. For a foreground server, stop it and run t3 serve again with your usual options. Include the diagnostic message and trace ID when reporting a persistent failure.

For a connection that still fails after linking, check the date and time on both devices. For server version warnings, follow Updating T3 Code.

Using the Desktop App as a Remote Only#

If a computer should only drive work running elsewhere, turn off its local environment. In the desktop app, open Settings → Connections and switch off Local environment. T3 Code restarts without a local server: no local agents or terminals run, WSL backends stay off, and other devices can no longer connect to this computer. Your projects, history, and saved connections are kept, and you keep working through pairing, T3 Connect, or SSH.

Switch Local environment back on in the same place to restart with your previous local settings.

Source: T3 Code documentation ↗

Connected machines

Running in the background#

On Linux and macOS, T3 Code can run as a service for your user so you do not need to keep a terminal open.

Manage the service#

Install the t3 CLI first (Install T3 Code), then run these commands on the machine that will host T3 Code:

Uninstalling the service leaves your projects, threads, and settings intact. Running t3 service install again repairs a service that t3 service status reports as broken.

t3 update downloads the newest release on your channel and switches t3 and the service to it. Restarting interrupts running agent turns, terminals, and remote clients, so it asks first; answer no and the service keeps running the old version until you run t3 service restart. Pass --yes from a script. A server you started by hand is left running; stop and start it again to pick up the new version. Wait for any remote update already in progress before updating; to match a remote client's version, follow Updating T3 Code.

Pass an exact version (t3 update 0.0.42) to pin one, --channel nightly to switch trains, or --allow-downgrade to move backwards. preview is a maintainers' test train: its builds can be broken and are never offered as updates, so the installer and t3 update ask for confirmation before installing one.

t3 uninstall removes the background service, the t3 launcher, and the downloaded versions after showing you the list and asking once. Your projects, threads, and settings under ~/.t3/userdata are kept. Pass --yes from a script.

Platform support#

Linux needs systemd user services. Setup enables lingering so T3 Code starts at boot and keeps running after logout. If this needs administrator permission, setup prints a recovery command before changing the service.

macOS starts the service when you log in and stops it when you log out. Keep the Mac logged in and awake for unattended remote access. Installing over SSH while nobody is logged in at the Mac's screen can fail at the final start step; the service is still installed and will start at the next login.

Windows background services are not supported.

T3 Connect can offer service installation during setup, but the two are managed separately. Signing out of T3 Connect does not stop or uninstall the service.

Troubleshooting#

Start with t3 service status on the host. It prints the log path and, on Linux, checks whether the installed service is running, enabled, and allowed to survive logout.

If it stops when your SSH session closes, check for linger-disabled. An administrator can enable lingering with:

sudo loginctl enable-linger "$(id -un)"

Over SSH, allow sudo to prompt:

ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'

Then retry service setup as your normal user. Run only the loginctl command with sudo; running T3 Code as root creates a separate installation and Connect identity. Without administrator access, run t3 serve in a terminal and keep that session open.

On macOS, check System Settings → General → Login Items if the service no longer starts at login. If agent work cannot access Desktop, Documents, or Downloads, it may need Full Disk Access for the t3 executable listed in ProgramArguments in ~/Library/LaunchAgents/com.t3tools.t3code.service.plist.

For failures after signing in to T3 Connect, see connection troubleshooting.

Source: T3 Code documentation ↗

Connected machines

Outside agents & MCP#

Agents that T3 Code did not start can work with an environment through its MCP server. They can read projects and threads, start and message threads, and check which providers and models are available. This covers Claude Code or Codex in your own terminal, ChatGPT, and bots that support MCP. Each agent signs in once, and you choose what it may do.

Get the MCP URL#

In Settings → Connections, open a saved environment's menu and choose Copy MCP URL. The URL is the environment's address followed by /mcp, for example:

https://<environment-address>/mcp

The copied URL uses the route this device is connected over, so an agent on the same device can reach it.

• An agent on your own computers can use any address that computer reaches the environment at: a LAN or Tailscale address, T3 Connect, or localhost on the host. See remote access.

• A hosted agent, such as ChatGPT or a bot running in the cloud, must reach the environment from the internet. Use the T3 Connect address. A Tailscale address only works from your own tailnet.

Approve a sign-in#

The first time an agent connects, it opens a sign-in page on the environment. The page names the agent and where its access goes:

• For an agent on your computer, approval returns to a localhost address on the computer that opened the page.

• For a hosted agent, approval goes to that service, such as chatgpt.com. Anyone who runs that service gets the access.

Only approve a sign-in you just started. To approve, enter a pairing code from Settings → Connections or from t3 auth pairing create on the host. A browser already signed in to the environment as an administrator can approve without a code.

Then choose what the agent may do:

• Read only is the default. The agent can read projects and threads and see the available providers and models. It cannot change anything.

• Supervised through Full access also let it start, message and stop threads in every project. A thread it starts or steers cannot run with more permissions than the mode you chose.

Claude Code#

claude mcp add --transport http t3 https://<environment-address>/mcp
claude mcp login t3

claude mcp login opens the sign-in page in your browser. On a machine without a browser, add --no-browser, open the printed URL elsewhere, and paste the final URL back when asked. claude mcp list shows t3 as connected once you approve.

Codex#

codex mcp add t3 --url https://<environment-address>/mcp
codex mcp login t3

codex mcp login --no-browser prints the sign-in URL instead of opening it. codex mcp list shows t3 with OAuth once you approve.

ChatGPT#

Add the environment as a custom MCP app in ChatGPT's apps settings:

1. Create a new app or plugin with a custom MCP server.

2. Set the server URL to https://<environment-address>/mcp, using the T3 Connect address.

3. Choose OAuth for authentication. ChatGPT discovers the rest; you do not need a client ID or secret.

4. Create the app, then approve the sign-in page that opens.

Other agents and bots#

Any agent that supports remote MCP servers over HTTP with OAuth can connect. Give it the MCP URL and choose OAuth, and the agent finds the sign-in settings itself. Agents without OAuth support cannot connect.

Remove an agent#

Approved agents appear under Settings → Connections like other clients. Revoke one there to cut off its access immediately. A sign-in lasts 30 days; after that the agent asks you to approve it again.

Source: T3 Code documentation ↗

Connected machines

Devices#

The Device panel shows a live iOS Simulator or Android Emulator next to a thread, so you can watch an agent verify mobile work and tap the device yourself. Agents get the same device through device_* tools and the agent-device command line, which T3 Code sets up for them.

Open a device#

Open the right panel in a project thread and choose Device. On first use, the panel walks through three steps: starting the device hub, checking iOS and Android support, and choosing whether agents may control devices. Opening the panel alone does not download or start anything. If the hub is already installed, the setup screen says so and reuses it.

Choose a running device to watch it, or choose Start next to a stopped device to boot it. The panel shows when you or an agent starts a device. Each device opens in its own tab. Use + → Device to open another, and double-click a tab name or choose Rename from its context menu to rename it. Only the visible tab streams video; switching tabs keeps both devices running. Choose Float device over chat in the toolbar to keep watching and tapping the device in a small window while the right panel shows something else; drag the window by its handle, resize it from any edge, and use Open in right panel to bring it back. Turn off the device hub in Settings → Integrations → Devices to stop the helper processes; simulators and emulators keep running until you power them off.

Simulators run on the machine that hosts the environment server. iOS needs macOS with Xcode. Android needs the SDK Platform-Tools, Android Emulator, and Command-line Tools (latest), plus a virtual device created in Android Studio's Device Manager. T3 Code detects standard SDK locations; set ANDROID_HOME for a custom location. The panel explains missing dependencies. After installing them, restart the environment server and refresh devices.

The screen is interactive: click and drag to touch, type while the screen is focused, and use the toolbar for Home, Back, and Recents on Android, rotate on iOS, and power off. Close the tab to stop watching; the device keeps running unless you power it off. Closed tabs stay closed after a reload. To watch the device again, choose it from + → Device.

Choose 3D view to inspect supported devices while the live screen stays interactive. On iPhone Duo, use the fold and stance controls to change its physical pose, or pinch over the device to adjust the hinge. Turning the model to the other screen switches the live display and touch input to that screen. Restore 3D view returns the device to a screen-facing position. On supported Android foldables, use Fold device and Unfold device beside the screen to change its posture in either view.

Tools#

The toolbar's Tools button opens a drawer for the open device. It shows the foreground app, and lets you switch light and dark mode, change text size, flip accessibility settings, overlay the accessibility element frames on the screen, set a fake location, and grant or revoke app permissions. iOS also exposes Liquid Glass, color filters, VoiceOver, and sending a test push notification; Android adds orientation and toggling the network. The drawer only shows what the platform can do, and every control reflects the value read back from the device after a change.

Agents and devices#

When an agent opens a device, it floats over the chat in web and desktop clients connected to the thread, the same way an agent-driven browser does. Turn off Auto-show floating preview in Settings → Integrations → Browser to open a right-panel tab instead. In the mobile app, open the agent's thread and tap the device button above the composer to watch the live screen and control it. If the thread has several devices open, choose one in the viewer. Closing the viewer stops streaming and leaves the device available to the agent. Device activity also appears in the thread timeline.

Agents drive the device through the agent-device command line. T3 Code installs and starts it only after Agent device access is enabled. iOS taps build a small test runner on first use, which takes a couple of minutes once per server. Restart an existing agent session after granting access so it receives the device CLI environment.

To keep agents away from simulators, turn off Agent device access in Settings → Integrations → Devices. This hides the device tools from agents started from then on; your own Device panel is unaffected.

Remote connections#

The device stream goes through the environment server, so it works over the local network, Tailscale, and T3 Connect. Live video needs a secure page (HTTPS or localhost); on a plain-HTTP remote origin iOS falls back to a slower still-image stream and Android cannot show video.

SSH device hosts#

In Settings → Integrations → Devices, choose the environments that should use the host and add it under Device hosts. Enter an SSH alias or user@host, with an optional identity file and port. These resolve on the environment server, so use the SSH configuration and keys available there. Password prompts are not supported.

Test connection checks SSH, Node, npm, and platform tools without installing anything, with a result for each selected environment. Targets that resolve to the environment’s own machine are skipped, since its devices are already local. The first device listing installs pinned device tools on the host. Node 22 or newer and npm must be available to non-interactive SSH commands. T3 checks common Homebrew and Android SDK locations; custom installations need the appropriate PATH and ANDROID_HOME on the host.

The picker identifies devices by host when several hosts are configured. Connections recover after interruptions. Removing a host closes its device sessions and stops its T3 helpers when reachable; simulators keep running.

T3 provides discovery, streaming, and control. Arrange app builds, installation, and connectivity to development servers such as Metro separately. A simulator on another machine cannot reach Metro through your environment's localhost without forwarding or another reachable address.

Device tool updates#

The connected T3 server manages the device hub and agent tools on its own machine and configured SSH hosts. Required versions install automatically the next time those tools are used. Settings → Integrations → Check device tool versions reads installed versions without installing tools or starting devices.

To receive newer tool versions on a remote environment, update that environment's T3 server. Updating only the browser or mobile app does not update the remote server. An offline host keeps its installed files, but an update needs network access before device support can start; T3 does not fall back to an older version. Reconnect the host and use Retry if installation fails. Existing device and agent-access settings are preserved.

Source: T3 Code documentation ↗

Connected machines

Mobile notifications#

Sign in to T3 Connect, link your environments, and enable Device Notifications in Settings → Notifications to receive alerts when an agent finishes, fails, needs approval, or asks for input. Tap a notification to open its thread. Your environment must have agent activity publishing enabled.

Enable Ongoing Agent Activity on Android or Live Activity Updates on iOS to follow work without opening the app. Finished results remain visible for up to 15 minutes. You can dismiss an Android activity card without disabling alerts; turn off ongoing activity in Settings to stop future cards.

Ordinary alerts stay quiet while the mobile app is in the foreground. Ongoing activity continues to update. Viewing a thread on another device does not silence your phone's alerts.

Android notifications require Android 7.0 or newer and Google Play services. Android 16 and newer can promote ongoing activity to a Live Update, subject to system settings and device support. Other devices show a regular ongoing notification. Android 7's battery-saving modes can delay removal of expired cards.

Notification permission and Android notification channels are controlled in system Settings. Background delivery requires T3 Connect; a direct or Tailscale connection alone does not enable push notifications. The mobile app does not need to maintain a connection to your environment. Force-stopping the Android app in system Settings prevents push delivery until you open it again.

Source: T3 Code documentation ↗

Tools & customization

Settings & project overrides#

On web and desktop, the "Applying settings for …" sentence at the top of Settings pages picks the project and environment a change applies to. Pages that only hold device preferences, such as Appearance, don't show it. They start at All projects and All environments and stay selected as you move between categories or search for a setting.

Preferences saved on this device, such as appearance, confirmations and browser profiles, always show and ignore the selection. Everything else is stored on a server. Choose one environment to edit its settings, or leave All environments to edit every connected environment at once. Offline environments keep their current values; this is a bulk edit, not a synced global default.

Choose a project to override settings for it on the selected environments. A layers icon beside each server row's title shows where the value comes from: the built-in default, the environment, or a project override. Click it to see that chain on every selected environment. An override can be reset to inherit again. Settings that cannot be overridden by a project are shown read-only while a project is selected.

When the selected environments disagree, the control shows Mixed in place of a value and the layers icon turns amber. Picking a value applies it to every selected environment.

Changing an environment value never touches a project's own override. When projects override the setting you are editing, the layers icon counts them and the chain lists each one with its value: click a project to jump to it, or Reset all to make those projects follow the environment again.

Providers and diagnostics are per machine: they show one environment at a time, the primary one until you pick another. Every other setting fans out to the selection.

With a project selected, a provider's switch in Settings → Providers turns it on or off for that project only, in either direction: a provider off on the machine can be used in one project, and one on everywhere can be kept out of another. That project's model pickers follow the switch, and no new turn there can start on a provider it turned off, including queued messages and follow-ups from delegated tasks. A turn already running when the switch flips finishes. A delegated task's result still lands in its parent thread, which sees it on its next turn. Reset returns the project to the machine's setting. Every other provider setting stays per machine.

On mobile, open Settings and use the filter in its header to choose connected environments and a project. The filter stays available in server-setting pages. With All projects selected, the Server settings categories and auto-settle controls in Thread behavior edit the selected environments' defaults. Choosing a project edits its overrides on the selected environments. Use Use defaults in a page to remove that page's project overrides. Open Settings → Projects & threads → Overview to rename the project across its selected connected checkouts and see where those checkouts live. Settings that are environment-wide stay read-only while a project is selected. When selected targets disagree, a control shows Mixed until you choose one value. Appearance, keyboard, and other phone-only settings ignore the filter.

Worktree branch names#

In Settings → Source Control → Worktree branch naming, choose a static prefix, a model-selected semantic prefix such as feat/ or fix/, or custom instructions for the complete name. The static prefix defaults to t3/; a trailing slash is optional, and an empty prefix adds nothing. Invalid characters in a static prefix are replaced with hyphens. Custom instructions are appended to the naming prompt and can specify issue IDs, namespaces, and casing.

These settings apply to automatically named new worktree branches. Select a project to override its environment defaults. Worktree directories keep their original names. If generation fails, or a custom name is invalid or already taken, the temporary branch name remains.

Scheduled tasks on mobile#

Open Settings → Scheduled tasks to create recurring tasks or manage existing ones across your connected environments. Use the settings filter to narrow the list by environment or project. Each task runs on the environment you choose, using its project, model, and workspace settings. Fixed-time schedules use that environment's time zone, which may differ from your phone's.

You can edit, pause, resume, run immediately, or delete a task from the list. Webhook tasks only run when their URL is called, so they can't be run immediately. Leaving an edited form asks before discarding unsaved changes.

Webhook automations#

In Settings → Scheduled tasks, choose On webhook as a task's schedule to run it whenever another service calls its URL, such as GitHub on a new pull request or a CI job that failed. A public URL needs a T3 Connect managed tunnel; after you save the task, copy its URL from the editor. Without one, the editor shows only the URL's path. Rotate replaces the URL and the old one stops working.

The prompt decides what the agent sees. Placeholders pull values out of the request: {{body.path}} for a JSON or form field, {{headers.name}}, {{query.name}}, {{body}} for the raw body, and {{request}} for everything. For example, Review this PR: {{body.pull_request.html_url}} sends only the pull request link. A placeholder with no value is left empty.

For GitHub, turn on Require signature, keep the header x-hub-signature-256, hex encoding and the sha256= prefix, and enter the same secret in the repository's webhook settings with content type application/json. Requests without a valid signature are rejected. Set this up on desktop or web; mobile keeps an existing signature check but can't turn one on.

On desktop and web, pick Deliveries from a task's menu to see recent requests and the prompt each one produced.

If the environment is offline, the sender gets an error and nothing runs; redeliver from the sender, such as GitHub's Recent Deliveries, once it is back. To have T3 Connect keep requests instead, turn on Hold webhooks while offline in Settings → Connections. T3 Connect then stores requests to a T3 Connect URL for up to 24 hours and delivers them when the environment returns. Leave it off if you don't want request bodies stored outside your machine. To skip requests that waited too long, set Skip requests older than on the task.

Defaults and inheritance#

General contains the model and workspace for new threads. Integrations controls agent browser access. Source Control contains automatic pull, the default pull request merge method and text generation. The same rows edit environment defaults or project overrides depending on the project crumb.

The Project category, shown while a project is selected, holds the project's name, icon, actions, checkouts and removal. Actions belong to a project: editing them creates the project's own list on each selected environment, and reset returns to the environment's shared list. A project's t3.json actions can be imported there.

Settings a repository can also declare in t3.json, such as the workspace for new threads, resolve in one order: a project override, then the environment setting, then t3.json, then the built-in default. Leave a setting on Inherit to let the next tier decide. Browser access changes apply when an agent session next starts.

New worktrees initialize git submodules recursively. If that step is slow because the repository declares many nested submodules, set Submodules in Settings → General (with the project selected to override it there) to Top level only to stop at the ones the repository declares itself, or Skip to leave them for a setup script. It resolves in the same order as the workspace default: a "worktreeSubmodules" value in the t3.json of the branch being checked out applies when the project and environment are both on Inherit.

Worktree location#

New worktrees go in the worktrees folder of the T3 home directory. To put them somewhere else, such as another drive, set Settings → Storage → Worktree location to an absolute path like D:\worktrees or ~/worktrees. The setting is per machine. Existing worktrees stay where they are, and cleanup covers both the default folder and the custom one.

Storage cleanup#

Open Settings → Storage to enable automatic cleanup on one machine or all connected environments. Policies are off by default and run on the server at startup, when changed, and hourly. Offline machines keep their existing policies.

Select a project to set Automatic worktree cleanup to Inherit, Off, or Custom. Inherit follows each machine's rules; Off keeps that project's worktrees until you remove them manually. Custom applies separate worktree rules to the selected project or checkout. Browser captures and log retention remain machine-wide.

Worktrees can be removed after a chosen number of inactive days, after merging, or when they have no commits beyond the default branch. Only T3-managed worktrees are eligible. Active sessions and shared worktrees prevent removal. Keep worktrees with local changes defaults to Uncommitted changes, which protects tracked edits and untracked files but deletes ignored files such as .env and build output. Any local files also protects ignored files other than node_modules. Edited tracked files protects only tracked edits and allows untracked and ignored files to be deleted. Branches and thread history stay; starting another turn recreates the checkout. Merge cleanup requires a merged pull request whose commits are included in the remote default branch. A squash or rebase merge on GitHub also counts when the pull request targeted the default branch and the worktree is still at the pull request's last commit.

Enable Delete worktrees with deleted threads to remove safe worktrees after their last thread is deleted, including archived threads and worktrees left by earlier deletions. The server waits for sessions and terminals to stop and retries skipped worktrees after restart. Existing prompts for deleting a worktree manually remain available when this policy is off.

Choose Delete now to run the enabled rules immediately. The latest results show which worktrees were removed or kept and why, plus any failures.

Browser captures and rotated logs have separate retention periods. Expired capture links stop working. Current logs, message attachments, and browser profiles are kept.

Project icons#

Select the project and open Project to choose an icon, emoji, monogram, or image. The choice applies to every checkout in the project group and appears on connected clients. Choose Automatic to let T3 Code detect an icon again.

Choose Monogram in the icon picker to set one or two letters or numbers and a color.

When no image is found, web and desktop show a two-character monogram with a color from the icon palette, derived from the saved project name. For example, Nebula becomes NA, Silver Orchard becomes SO, and M7 Forge becomes M7.

Keep the default branch current#

In Source Control, enable Automatically pull to keep the default-branch checkout up to date with its configured upstream. Choose an environment to set the default or a project to override it. On mobile, use Settings → Source control to change selected environment defaults or project overrides.

T3 Code only pulls when it can fast-forward and the checkout has no changed files, untracked files, or local commits. It skips checkouts on another branch or without an upstream. If a checkout has local work, resolve it yourself before automatic pulls can resume.

Source: T3 Code documentation ↗

Tools & customization

Appearance & themes#

On web and desktop, open Settings → Appearance to choose a theme and follow the system appearance or stay in light or dark mode. To use different themes for light and dark mode, select the corresponding preview within each theme. Appearance preferences are saved separately on each device or browser.

On web and desktop, use Change theme in the command palette to select a theme without leaving chat. Press Cmd+Option+A on macOS or Ctrl+Alt+A on Windows/Linux to open the theme picker directly. Use Change appearance in the command palette to choose System, Light, or Dark independently of the theme. Cmd+Option+Shift+A on macOS or Ctrl+Alt+Shift+A on Windows/Linux cycles through those modes. Customize these shortcuts under Settings → Keybindings.

On mobile, open Settings → Appearance. Mobile has its own themes and text, code, and terminal preferences. It does not follow environment themes or defaults.

On Android 12 or newer, choose the Material You theme in Appearance to use colors from your wallpaper. Selecting another theme replaces those colors. Like other themes, Material You can be selected separately for light and dark appearances. Android uses Material You Layout by default unless you have turned it off in Appearance. It changes shapes, spacing, and controls independently of the selected theme.

Composer context#

Git-backed projects show branch and worktree controls below the composer while you create a thread. The controls retreat as the composer docks after you send the first message.

Turn on Composer context to keep those controls visible after the thread starts. This preference applies to the web and desktop clients.

Motion#

The main sidebar, right panel, and terminal drawer open and close immediately by default. Move the Panel animations slider above 0 ms to add motion, up to 400 ms, unless reduced motion is enabled in your operating system. Moving between threads always snaps to the selected thread's panel state without replaying its transitions.

Custom themes#

On web and desktop, choose Create theme to adjust a palette, or import a T3 Code or VS Code theme. The theme editor's color picker lets you select an area of the app to find the color to change. Export your theme as JSON to share it.

Environment themes#

Environment themes and defaults come from the server serving your web app or the desktop app's main local environment. app.t3.codes and additional connections do not use them.

Select a published theme in Settings → Appearance to follow its palette as the server updates it. Duplicate makes an independent copy you can edit. A saved custom theme with the same ID takes precedence. If the server stops publishing the selected theme, T3 Code falls back to its standard theme.

Run this on the server to set a default and switch connected clients to it:

t3 theme set nightfall

Clients that are offline apply it when they reconnect. Each client applies the setting once; choosing another theme afterward sticks until the next t3 theme set. Run the command again to reapply it, even if the name is unchanged.

t3 theme clear removes the default without changing anyone's current theme. t3 theme show lists the default and published themes.

Publish a theme#

Save a theme exported from T3 Code into ~/.t3/userdata/themes/ on the server, or the themes directory under your custom state directory. The filename supplies the theme ID: nightfall.json can be selected with t3 theme set nightfall. Keep the filename stable when updating its colors. Do not use system, light, dark, or a built-in theme's ID.

For an integration that generates a palette, this shorter format also works:

{
  "name": "Nightfall",
  "appearance": "dark",
  "canvas": "#1a1b26",
  "accent": "#7aa2f7",
  "colors": {
    "terminalSelection": "#292e42",
    "error": "#f7768e"
  }
}

Set appearance to light or dark and supply hex colors for canvas and accent. T3 Code generates the rest. The optional colors overrides use the names in the theme editor's advanced view.

Write updates to a temporary file and rename it into place so clients never read a partial theme. Invalid files are not published.

Source: T3 Code documentation ↗

Tools & customization

Visual replies#

Agents can answer with a page instead of only text: a chart, table, diagram, image collage, or mockup. Ask for one ("show this as a chart", "make a collage of these screenshots") and the agent builds a self-contained HTML page, which appears in the thread above its written reply. It works with every provider, on web, desktop, and mobile.

Pages use your current theme, including custom themes, and follow light and dark mode as you switch. Scripts run inside the page, but it is sandboxed away from T3 Code and your session. Links you click in a page open in your browser. Use the expand button to open a page full size; from there you can view its source or save it.

Agents can place local images in a page by file path. T3 Code embeds them when the page is published, so the page keeps working after the original files move or are deleted. Deleting the thread deletes its pages.

Before publishing, agents check their work with screenshots from a small headless browser that T3 Code keeps for itself; it never uses a browser you installed. The first preview on a machine downloads it once (about 120 MB) into T3 Code's data folder, so that preview can take a minute. Browser tabs on a remote environment use the same browser, so whichever comes first downloads it. Some Linux hosts need setup before it can start. Pages publish without it.

MCP apps#

Some MCP servers return an interactive app with their tool results, following the MCP Apps standard. When an agent calls one of those tools, the app appears in the thread in place of the tool call, on web, desktop, and mobile. Codex supports this today, for any MCP server you have configured for it; other providers show these calls as ordinary tool calls.

Apps follow your theme. An app can call tools on its own server and post a message to the thread; T3 Code asks first unless the server marks the tool as read-only, and it asks before every message. On mobile, an app also asks before opening a link, and T3 Code asks before saving a file an app offers. An app stays viewable after its agent stops, but using it needs the agent of the thread that created it running, so send a message in that thread first if the app says it is unavailable. An app that navigates away from its own page is stopped.

An app can open full screen; use the button in its top corner, or press Escape outside the app, to return it to the thread. Anything else that needs your attention, such as an approval, also returns it to the thread. On mobile, full screen opens the app again in its own screen, so anything the app does not save itself starts over. An app can also keep the agent informed of what you did in it, such as a filter you picked; T3 Code sends the latest note from each app with your next message.

Source: T3 Code documentation ↗

Tools & customization

SnapShots#

A SnapShot captures the window you are working in and attaches it to your current draft. The attachment carries the app name and window title, and when available the app icon and the window's accessibility data (its controls, text, and their positions in the image). Agents can use that data to reason about the screenshot.

SnapShots are off by default and available in the desktop app on macOS, Windows, and Linux with Wayland. X11 sessions are not supported.

Turning it on#

Open Settings > SnapShots and turn the feature on. Setup has two steps: allow capture, then choose a shortcut. Each step shows only what your desktop needs. Finish later turns capture back off but keeps anything you already installed, so you can resume where you left off.

• macOS asks for Screen Recording during setup. It asks for Accessibility only when Include app text is on.

• Windows needs no setup or permission.

• Linux depends on your desktop. See Linux desktops.

Turning capture off releases the shortcut. It does not uninstall a helper or extension you installed.

Taking a capture#

Switch to the window you want and press the shortcut. The default on macOS and Windows is both Shift keys together. T3 Code attaches the image to your draft and brings itself forward. If no thread is open it starts a draft in the current project.

Pressing the shortcut while T3 Code is in front captures T3 Code itself.

Pending captures are kept on disk until the attachment is saved to the draft, so a capture survives closing the app mid-way and is attached on the next launch. Captures rejected because the image is too large are discarded.

Changing the shortcut#

Select the shortcut in Settings, press the new keys, then Save. On macOS and Windows you can use a modifier pair such as Command+Command or Ctrl+Ctrl, or a key chord. T3 Code refuses shortcuts that collide with its own keybindings or that the operating system already reserves.

On Linux, choose a key chord; modifier pairs are not supported. On Niri and Hyprland the shortcut lives in your compositor config, so Change shortcut reopens setup to review the change.

Include app text#

Include app text controls whether captures include the window's accessibility data. Turn it off to attach screenshots only. On macOS this also drops the Accessibility permission requirement.

Availability depends on the app. Some apps expose only their window controls, not the document or terminal contents. If an app is slow to answer, T3 Code attaches the screenshot without the data rather than waiting.

On GNOME, browsers may need app accessibility enabled in the desktop's accessibility settings before they expose text. Restart the browser after enabling it.

An icon beside the app name on an attachment shows whether accessibility data was included. Select it to inspect what was captured.

Sound, flash, and animation#

Settings controls the capture sound, the brief flash on the captured window, and the animation that flies the image into your draft. Each can be turned off independently. The operating system's reduced-motion setting also disables the animation.

Linux desktops#

SnapShots work on Wayland sessions. Each desktop provides capture differently, and setup names your current desktop and shows only what it needs. Preferences carry across desktops, but each desktop's helper and shortcut approval are separate.

GNOME. Install the bundled T3 Code SnapShots extension during setup. It is installed per-user, offline, and needs no administrator password. Sign out and back in after the first install so GNOME discovers it, then enable it from setup or from GNOME's Extensions app. If GNOME has disabled all user extensions, turn them on there first. Disable or remove the extension in GNOME's Extensions app to revoke access.

KDE Plasma 6. Install the bundled capture helper during setup; no sign-out is needed. If the shortcut does not fire, check T3 Code under System Settings > Keyboard > Shortcuts. If a shortcut using Shift and a number does not work on your keyboard layout, use a letter chord instead. Remove the helper from Manage capture > Access > Advanced.

Hyprland and Omarchy. Install the bundled helper during setup, then choose a shortcut and select Review changes. T3 Code shows the exact change it will make to your Hyprland config. Save shortcut writes only that change, keeps a backup, and reloads Hyprland. Approve the screen-sharing prompt for the helper if one appears. On Omarchy, bind in your own config, not the shipped defaults. Some Hyprland versions return an "access denied" image instead of an error when capture is blocked; check the helper's screen-sharing permission.

Niri. Choose a shortcut and select Review changes. T3 Code shows the exact binding it will add to your Niri config, validates the result, keeps a backup, and saves it when you approve. Niri reloads the config on its own. The binding needs the gdbus command, normally part of your distribution's GLib tools. Remove the line from your config to release the key.

Other Wayland desktops. T3 Code uses the desktop's screenshot portal when it can capture the active window. Otherwise Settings shows Manual capture only and the shortcut opens the desktop's window picker. Picker captures do not include accessibility data.

Apps running through XWayland inside a Wayland session can still be captured.

Source: T3 Code documentation ↗

Tools & customization

Importing browser sessions#

The desktop app can import cookies from another browser so you can reuse its signed-in sessions in the preview browser.

Open Settings → Integrations → Browser profiles → Add profile, then choose a browser under Import from. Close the source browser before importing, and allow an operating-system keyring unlock prompt if one appears.

This is a one-time copy. Later login changes stay separate between the two browsers, and some sites may still require you to sign in again.

On macOS, Safari imports need Full Disk Access. Choose Allow, drag T3 Code into the System Settings permission list, and turn access on. Continue becomes available when access is detected. macOS may require you to quit and reopen T3 Code before the grant applies; reopen the import wizard afterward. You can revoke Full Disk Access once the import is done.

On Windows, import supports Firefox and Helium profiles that use standard profile encryption. Other Chromium-based browsers use app-bound encryption and cannot be imported. Partitioned cookies are skipped on all platforms.

Source: T3 Code documentation ↗

Tools & customization

Default browser#

On macOS, the desktop app can be your default web browser. Links you open from other apps then open in T3 Code. When the thread on screen shows its browser panel, the link opens there as a new tab. Otherwise it starts a new thread without a project, with the browser panel maximized on the page, so you can ask an agent about it right away.

Choose T3 Code under System Settings → Desktop & Dock → Default web browser. To go back, choose another browser there.

HTML files you open from Finder open the same way. Prompt links to app.t3.codes open in the app as a draft.

A link that launches T3 Code waits until the app has connected to its environment, then opens.

Source: T3 Code documentation ↗

Tools & customization

Sharing prompt links#

A prompt link opens T3 Code with a prompt ready to send. Use one to share a prompt on social media, or to put a one-click fix in a pull request comment.

A link never runs anything. It opens a draft. You read the prompt, then press Send. A link cannot change your permission mode, branch, or worktree. Your own defaults apply.

Make a link#

Open the command palette and choose Copy prompt link. It copies the draft in the composer. When the project is on GitHub, Copy prompt link with repo and model also adds the repository and the model you picked. Sent messages have a Copy prompt link button too.

You can also write a link by hand:

https://app.t3.codes/new?prompt=Rate%20my%20swearing
https://app.t3.codes/new?prompt=Fix%20the%20build&repo=owner/name&provider=codex&model=gpt-5.5
https://app.t3.codes/new?pr=owner/name/123&prompt=Fix%20the%20failing%20check

Encode the prompt for a URL. In JavaScript, use encodeURIComponent.

Open a link#

On app.t3.codes, the link first asks where to open it: the desktop or mobile app, this browser when it is connected to a machine, or the download page. Select Remember my choice to skip this step next time.

• No repo: the draft opens without a project, on the machine you used last.

• repo: the draft opens in your most recently used project for that repository. A fork counts only for its own owner. When you do not have the repository, choose Clone or Use without project.

• provider and model: used when you have that provider set up. Otherwise your default model is used, and T3 Code tells you.

• pr: opens the thread linked to that pull request on any connected machine, with the prompt in its composer. When no thread is linked, the draft goes on the pull request branch in a new worktree. T3 Code checks the code out only after you confirm, because the checkout runs your setup script on it.

A thread link with a prompt, such as https://app.t3.codes/<environment>/<thread>?prompt=…, puts the prompt in that thread's composer. If you already typed a draft there, T3 Code asks before it replaces it.

T3 Code removes characters you cannot see, such as zero-width and hidden tag characters, because they can hide instructions for the agent. When a prompt had them, T3 Code warns you that it may be malicious.

Source: T3 Code documentation ↗

Reference

Keyboard shortcuts#

Customize shortcuts in Settings → Keybindings on web and desktop. That page also lists the command IDs and defaults available in your version.

Composer controls#

In Settings → General → Send shortcut, choose whether Enter sends, requires mod+Enter for multiline prompts, or always requires mod+Enter. Shift+Enter inserts a new line. This applies to the web and desktop composer at desktop widths.

Follow-up behavior chooses Queue or Steer while the agent runs. Use mod+Enter to do the opposite for one message, even when the send shortcut requires a modifier. mod+Alt+Enter sends, keeps that thread running in the background, and opens a fresh new-thread composer. In a new thread, mod+Enter does the same. Change these shortcuts in Settings → Keybindings under Composer: Opposite Queue or Steer Action, Composer: Start in Background, or Composer: Send and Start New Thread. These bindings take priority over the send shortcut. Click the send button to use the configured follow-up behavior.

When an active turn has queued messages, mod+Shift+Enter sends the first as a steer. Change it under Queue: Send First Queued Message as Steer in Keybindings.

Use mod+shift+m to choose a model and mod+shift+h to choose a host. To step a new thread to the next machine instead of opening the menu, bind Composer: Cycle Host in Keybindings. It has no default shortcut. Use mod+shift+e for effort, mod+shift+a for access mode, mod+shift+x for the workspace, and mod+shift+g for the Git branch. The workspace menu includes the current checkout, a new worktree, and the previous worktree when available. Use mod+shift+l to reuse the previous worktree directly.

In the model picker, press Left in an empty search field or Shift+Tab to reach the provider list. Use Up/Down to move and Enter to choose. Right returns to model search. mod+shift+up and mod+shift+down switch providers directly and clear the search. These provider shortcuts can also be changed in Settings.

These shortcuts run inside the focused web or desktop client. mod uses Command on macOS and Ctrl on Windows and Linux, including GNOME, KDE Plasma, Niri, and Hyprland. If a custom desktop shortcut takes the same keys, choose another binding in Settings.

Copy pull request references#

With a PR open in the right panel or on the Pull Requests page, use mod+shift+c to copy its URL and mod+shift+k to copy its number with a # prefix. Both shortcuts can be changed in Settings. Search for “Copy Link or Thread ID” or “Copy Number”. They copy the selected PR and leave terminal input alone.

Find in a diff#

Click into a diff in the Diff panel or a pull request's Code tab, then press mod+f to search every file in it, including folded files and unchanged lines hidden between changes. Enter and Shift+Enter move between matches, and a match in a folded file opens it. Escape closes the search. This shortcut is not configurable. A very large uncommitted diff loads its files as you scroll, and find only searches the files loaded so far.

iPad#

With a hardware keyboard, use Cmd+1 through Cmd+9 to open the first nine displayed threads. The shortcuts follow the current list filters and order. Cmd+K opens the command palette to search commands, projects, and threads. Use the arrow keys and Return to choose a result, or Cmd+1 through Cmd+9 to choose directly. Escape or Cmd+K closes the palette. Start a search with > to show only actions.

In a new thread, Cmd+Shift+H moves the draft to the next machine.

In the composer, Return sends and Shift+Return inserts a new line. Cmd+Return also sends. To make Return insert a new line instead, change the Return key behavior in Settings → Keyboard.

Edit the configuration file#

Keybindings live on the environment's machine, in ~/.t3/userdata/keybindings.json by default. You can edit this file directly. It is a JSON array of rules:

[
  { "key": "mod+g", "command": "terminal.toggle" },
  { "key": "mod+shift+g", "command": "terminal.new", "when": "terminalFocus" }
]

T3 Code creates the file with its defaults and adds new defaults on later startups. New defaults do not replace commands you customized. If a new default overlaps one of your shortcuts, rule order decides which runs. Invalid rules are ignored; if the file cannot be parsed, T3 Code uses defaults.

Rule shape#

Each rule requires a key shortcut and a command ID. An optional when expression restricts when it runs.

Project scripts use script.{id}.run, such as script.test.run.

Key syntax#

Join modifiers and a key with +, such as mod+shift+d or ctrl+l. mod means Command on macOS and Control elsewhere. Other modifiers are cmd / meta, ctrl / control, alt / option, and shift.

When conditions#

Available context keys are terminalFocus, terminalOpen, previewFocus, previewOpen, modelPickerOpen, usagePageOpen, composerFocus, composerDraft, turnRunning, editableFocus, isWeb, and isDesktop. editableFocus is true while a text field, the composer, or another editor has the keyboard. isWeb is true in a browser tab. isDesktop is true in the desktop app. Unknown keys evaluate to false.

mod+1 through mod+9 jump to the first nine threads, and to models while the model picker is open. The thread jumps do not run while the model picker is open. Those defaults use isDesktop so they do not steal the browser's tab-switch shortcuts. Remove that condition in Settings if you want the same jumps in a browser.

Combine keys with ! for not, && for and, || for or, and parentheses:

{ "key": "mod+j", "command": "terminal.toggle", "when": "terminalOpen && !terminalFocus" }

Find in the current thread#

chat.find searches conversation messages and proposed plans in the active thread. Entering a query searches the entire thread, including older messages. Thread search requires server support; update an older server to enable it. Select Retry if a search fails. It defaults to mod+f outside terminals and previews. Press Enter or Shift+Enter to move between matches, and Escape to close find.

Precedence#

The last rule whose key and condition both match wins, even if it belongs to a different command. Put a more specific rule after a general one when they share a shortcut.

Commands with special behavior#

thread.stop interrupts the running turn in the focused thread. It has no default shortcut; assign one in Settings → Keybindings.

thread.undo (mod+z by default) reverses the actions shown in the notice at the bottom of the sidebar, such as unpin, settle, snooze, archive, or discarding a draft. Consecutive actions of the same kind undo together. The notice remains available for five seconds after the latest action. The default shortcut skips text fields and terminals so native undo keeps working there.

navigation.back (mod+[ by default) and navigation.forward (mod+]) move through the pages you have visited, like a browser's back and forward buttons.

chat.new may ask you to choose a project when there is more than one. chat.newLocal skips that chooser. Both use your new-thread defaults. chat.newWithoutProject (mod+alt+n) starts a thread without a project.

Reserved shortcuts#

In the desktop app, mod+w closes the focused terminal or the active right-panel tab. When nothing remains to close, it closes the window. In a browser, mod+w closes the browser tab; rebind rightPanel.close and terminal.close to an available shortcut such as alt+w.

mod+shift+t reopens the last closed tab across the app, including files, diffs, pull requests, browsers, and devices, in the order you closed them. A browser opens in a fresh session without its old page history. Incognito tabs can reopen until you reload or quit the app. This shortcut does not undo deleted work. Browsers also use it to reopen browser tabs; choose another binding in Settings if the browser takes it first.

Many defaults include !terminalFocus so they do not intercept terminal input. Keep that condition when remapping them if you want the same behavior.

Desktop quit shortcut#

Use Cmd+Q on macOS or Ctrl+Q on Windows and Linux. In the default Hold mode, hold for 1.2 seconds or press twice within 500 milliseconds. Holding requires keyboard repeat; if repeat is disabled, use two presses or the application menu.

Change Settings → General → Confirmations → Quit shortcut to Direct for a single press or Double press for two presses only. Choosing Quit from the application menu always quits immediately.

Source: T3 Code documentation ↗

Reference

Keyboard focus#

The command palette keeps focus while open. Closing it returns focus to the composer. While the palette or model picker is open, number shortcuts select its entries instead of switching threads. Model shortcuts work in Settings as well as the composer. See Keybindings to customize these shortcuts.

If you return to typing while a terminal is starting, the composer keeps focus when the terminal becomes ready. Opening or switching to a terminal explicitly still focuses it.

Source: T3 Code documentation ↗

Reference

Usage & limits#

Open Usage from the sidebar or the command palette, or press mod+u on web and desktop when the terminal is not focused. Customize usage.open in Settings → Keybindings.

Understand your usage#

Usage combines Codex, Claude Code, Grok Build, OpenCode, Antigravity, Pi, and Cursor history from your connected environments. It shows token use, cache savings, model breakdowns, and estimated API-equivalent cost, split by token type and by speed. These estimates are not your subscription bill. Premium is what Fast and Ultrafast requests cost above standard rates. Cost that cannot be split, such as a provider-reported cost for a model without public rates, shows as Other. Select a model under Breakdown to see its trend, cache hit rate, and cost per million tokens.

Totals depend on the history available on each server. Grok turns without a saved completed-turn record are missing from the totals.

OpenCode reads its SQLite database and older JSON history. Antigravity reads local conversation databases, including T3-managed profiles. Set OPENCODE_DATA_DIR or ANTIGRAVITY_DATA_DIR on the server to read a different data directory; comma-separated paths read multiple directories.

Cursor reads account usage from Cursor's dashboard API using the CLI login saved on the server. This includes headless T3 sessions and desktop usage across machines; the same account counts once across connected environments. Without an accessible CLI login, T3 shows a notice instead of incomplete local totals. T3 does not estimate missing tokens from conversation text. On macOS, choose Enable Cursor usage on Usage to allow T3 to read your existing CLI login from Keychain. You can turn it off in Settings → Providers → Usage providers. macOS may ask you to allow access on the server Mac.

Usage includes each configured account's history, including disabled accounts. Custom homes follow the account's home setting or its CODEX_HOME, CLAUDE_CONFIG_DIR, or GROK_HOME environment variable. Pi reads ~/.pi/agent/sessions, or the sessions directory under PI_CODING_AGENT_DIR. Set PI_CODING_AGENT_SESSION_DIR to read a different session directory. To include sessions saved through --session-dir or Pi's sessionDir setting, set this environment variable to the same directory. Pi includes recorded tool and summary costs under Tools/summaries. Use absolute paths or ~/ paths in the account's environment settings; relative environment paths depend on each project's working directory and cannot be reliably discovered by Usage. Accounts sharing a history directory count once.

When your app and server support different providers, usage totals may cover only the providers your app understands. Update the app to include newly supported providers.

On web and desktop, use the environment dropdown to filter costs, tokens, and limits. All environments are selected by default. The dropdown shows which environments are still scanning; results appear as each one responds, and figures still updating are dimmed. Cursor shows its last saved totals first, then updates them when Cursor's API responds.

If recent work is missing or a new model shows no cost, refresh to rescan session history and update model pricing.

Set custom model prices#

On web or desktop, open the environment dropdown on Usage, then choose Model prices to add, edit, or reset a model's estimated price. Apply to starts with your current Usage filter; choose all environments or select individual destinations. Enter the exact model ID and USD rates per million input and output tokens. You can enter any model ID, including models without public pricing. When a model on Usage has no known price, select it under Breakdown and choose Set price to open this table with that model added.

Cache read and cache write rates are optional and use the input rate when blank. Enter 0 for tokens that are free. Saved prices replace automatic pricing for all of that environment's history and are shared with clients connected to it. When environments have different prices, cells show Mixed. Edit rates directly in the table, then choose Save changes to apply all edited rows. Untouched cells keep each environment's rate. Select one environment to inspect its prices. Reset to automatic marks a model's override for removal when you save; you can undo it before saving.

To count one model as another, such as a preview model under its released name, enter the target model ID under Map to. The mapped model no longer appears on Usage: its tokens and cost move to the target model and use the target's price. Clear Map to or reset the row to show the model on its own again.

Each destination reports whether the change saved. Offline or unavailable environments are marked Not saved. Reconnect them and choose Retry failed saves to finish the same change without writing again to environments that already saved. Changes are not queued after you close the dialog.

Track subscription limits#

Usage → Limits pools every subscription account it can see per provider, so with several Codex or Claude accounts across your environments and hubs you read one number per window rather than a list. Each window card shows how much of the pool is left and a bar with one segment per account, kept in the same column across windows. Accounts are ordered by their 5-hour reset, soonest first, or by the first available window when no account reports a 5-hour limit. A gap means the account does not report that window. When the provider reports reset times, the card also says when the next reset lands and how much it hands back. The hatched part of a segment is what that reset restores. Tap a segment or account row for the account's plan, where it is signed in, and its reset time. On web, you can hover too. Codex and Claude accounts with banked reset credits show a ticket count and the Use reset action in the account details. Claude resets are not available when the server runs on macOS, where Claude keeps its login in the Keychain. On narrow screens, numbered rows below the bar show each account's quota, countdown, and credits. Tap a row to open its details.

The same account signed in on more than one environment, or reported by a hub as well, counts once. Filter with the environment dropdown to see what a single machine has.

Opening Limits checks the selected connected environments automatically. Each client waits at least five minutes between automatic checks of an environment, including after a failed check. If a window still looks stale, refresh Limits to re-check every provider and hub.

Pick /usage-limits from the composer's command menu, or send it as a message, to check the current model's limits without leaving the conversation. The result opens above the composer and closes when you dismiss it or send your next message. It uses the same snapshot as Usage → Limits, so it does not run the agent or refresh anything. The command is offered only for providers that appear under Usage → Limits.

OpenCode Go reports its session, weekly, and monthly allowance when OpenCode runs locally in the environment. T3 cannot report limits for external OpenCode servers because their credentials belong to the remote server. Limits need an OpenCode Go API key. A Console sign-in alone does not report them. Add your Go API key as OPENCODE_API_KEY in the OpenCode instance's Environment variables, then refresh provider status. Cursor reports its monthly allowance, including separate Auto and API usage, using the CLI login or CURSOR_AUTH_TOKEN. On macOS, this includes the default Keychain login after you enable Cursor usage. Keychain login is used for limits only with Cursor's default API endpoint. If you configure a custom Cursor endpoint, use an explicit token or file-based CLI login for limits.

Grok reports the remaining subscription allowance and reset time for its current billing period after signing in with grok login. Explicit XAI_API_KEY connections and custom authentication or endpoint configurations do not report subscription limits.

API-key accounts may not report subscription limits. This also applies to Claude connections using a proxy through ANTHROPIC_AUTH_TOKEN.

Connect a CLIProxyAPI hub#

To see pooled accounts, open Settings → Providers → Usage providers → Add hub. Choose the environment that will connect to the hub and enter its URL and management key.

The accounts appear under Usage → Limits. Codex accounts show banked reset credits; select an account and choose Use reset to redeem one. No hub plugin is required.

This connection supplies usage information; configure the provider separately to send agent requests through the hub. Remove the hub from the same settings section when you no longer need it.

Subscription usage widget#

Add Subscription usage from your iOS or Android widget gallery to see remaining Codex and Claude quotas. Tap it to open Usage → Limits; on Android this works while T3 is running in the background, otherwise open the app from the launcher. On iOS, use Edit Widget to choose Session, Weekly, or both for each provider. Reopen T3 to refresh expired readings.

Keyboard shortcuts#

On web and desktop, open Usage from the command palette. While on Usage, press C, T, or L for Cost, Tokens, or Limits while not typing in a field. Use Ctrl+Shift+1/2/3/4 (Cmd+Shift+1/2/3/4 on macOS) for the past 24 hours, 7 days, 30 days, or 90 days. Period shortcuts do nothing on Limits. Press Escape to return to the previous page. Customize these shortcuts in Settings → Keybindings.

Source: T3 Code documentation ↗

Reference

Updates & compatibility#

The app you use and the server running your agents can be on different machines. When a server is behind your web or desktop app, an update notice appears in the conversation and Settings → Connections. Update the machine named in that notice.

Update everything at once#

The update button at the bottom of the sidebar updates every connected machine in one step. It updates outdated providers, then servers that are behind, then the desktop app you are using, which restarts last. Servers move to the version your desktop app is installing, or to your web app's version. A background service stays on its current release channel. A remote desktop app installs the latest release from its own channel. Hover the button to see what it will update.

Server updates appear only after that version is published to npm. Remote desktop apps do not wait for npm. Servers that need a manual update are not included. Use the notice or Settings → Connections for those.

The confirmation counts the running threads that the restarts will interrupt, and how many can resume afterwards. See Continue threads after restarts below.

Before you update#

Server updates restart the connection and can interrupt active agents and terminal commands. Saved threads, settings, and project files remain.

Settings → General → Continue threads after restarts is on by default. It resumes supported active threads after an update, crash, or machine restart. Changes are saved to connected environments that support this setting; update older servers first. If a supported environment was offline or has a different value, use Apply to all in Settings after it connects. T3 Code must start again on that machine; the setting does not enable automatic startup. Terminal commands may still be interrupted, and threads without saved provider resume state need a new message. A thread is not resumed while it waits for your approval, answer, or secret, or while it is archived, snoozed, or settled. After three automatic resumes in a row, the thread waits for your next message.

Updates from the previous orchestration system preserve conversation transcripts but cannot carry every kind of runtime history forward. Read Threads from older T3 Code versions before continuing an important older thread.

When versions don't match#

A client and server must speak the same orchestration protocol. If they do not, the connection is refused rather than running half-upgraded:

• An app newer than the server is blocked before connecting, with a notice telling you to update T3 Code on the machine named in the notice.

• A server newer than your app refuses the connection with an update message.

Update the side the notice names, then reconnect.

Update a connected server#

The offered action depends on how the server runs:

On the host, run:

t3 update <client-version>

Replace <client-version> with the version shown in the notice. The command asks before restarting the background service; if you decline, run t3 service restart when you are ready. For a server you started by hand, stop it and start it again afterwards with your usual options such as --host or --tailscale-serve.

If you run the server with npx rather than an installed t3, there is nothing to update on the host: stop the server and relaunch it as npx t3@<client-version> with the same subcommand and options.

If an update fails#

Keep the client open until it reconnects or reports a failure. A failed service update can roll back to the previous version. If the update still fails:

1. Retry the offered action once.

2. Check that you updated the server's machine, not only the device you are using.

3. For a command-line server, stop it and relaunch the exact version shown in the notice.

Update providers#

Settings → Providers shows provider updates for the selected environment. Update all updates every outdated provider on every connected environment at once. Hover it to see which providers it will update. Providers that only offer a manual update command are not included.

Mobile updates#

To update an environment from your phone, open Settings → Environments and select it. Check for updates finds the latest release on that environment's current release channel. Keep the app open while the environment updates and reconnects. Hosts that cannot update remotely show instructions for updating on the machine instead.

The same page lets you refresh provider status and update supported providers. These controls require a connected environment and permission to operate it. Provider update checks and restart continuation preferences are in Settings → Maintenance. If provider update checks are disabled, enable them there before refreshing to find newer versions.

Install App Store or Google Play releases as usual. The mobile app can also download updates in the background and apply them when you next leave the app. It saves drafts and queued messages before restarting. If you keep the app open for a long time, it may ask to install immediately; choosing Later leaves the update queued for the next suitable moment.

Source: T3 Code documentation ↗

Reference

Migrating older threads#

On your first V2 launch, T3 Code copies the V1 database, state.sqlite, into statev2.sqlite in the same data directory and migrates the copy. Your threads appear automatically, with full transcripts imported as needed. You do not need to run an import command.

V1 continues using its original database while V2 uses the copy. The database import can run while V1 is open. Opening V2 again resumes your V2 history. The copy happens only once: later conversations and changes in either version do not sync to the other. Settings, attachments, and workspace files remain shared.

The V2 desktop app uses a separate browser profile, so browser cookies and caches do not carry over from V1. You may need to sign in again to websites opened inside the app. On its first launch, the V2 desktop app copies stashed prompts, unsent drafts, layout, and theme from V1. Anything you change in V2 afterwards stays in V2.

The migrated thread keeps its title, project, provider and model selection, permission and interaction modes, branch or worktree, archive state, settlement state, snooze and pin state, and linked pull request. T3 Code also brings over user and assistant messages, their timestamps, and supported attachments. Large histories may appear in stages while the server imports transcripts.

The migration does not recreate the old provider's live session. It also does not convert old run records, checkpoints and diffs, tool activity, approval history, or proposed plan history into the new format. These items may be absent from a migrated timeline even though the conversation text is present.

Continuing a migrated thread#

The first new message starts a fresh provider session. T3 Code selects intact user and assistant messages using the same handoff budget as a provider switch. Omitted text remains in the thread and can be retrieved by the agent. The migration retains its separate 32,000-character recovery excerpt; neither that excerpt nor the handoff replaces the full imported transcript.

Before continuing a long or important thread, read the recent transcript and include any older requirements the agent still needs in your next message. Starting a new thread and pasting a short handoff is also a good choice when the old conversation contains conflicting instructions.

Keeping a recovery copy#

T3 Code does not currently have a whole-thread export command. Before a major server update, stop the server and copy its userdata directory to a safe location. The default is ~/.t3/userdata; a server started with --home-dir <path> uses <path>/userdata.

If a migrated transcript is missing from the app, keep that copy unchanged. You can inspect the old transcript without starting a server against it:

sqlite3 -readonly /path/to/recovery-copy/state.sqlite

At the SQLite prompt, list recent legacy threads:

.headers on
.mode tabs
SELECT thread_id, title, updated_at
FROM projection_threads
ORDER BY updated_at DESC;

Then print one transcript, replacing <thread-id> with the value from the first query:

SELECT role, text, created_at
FROM projection_thread_messages
WHERE thread_id = '<thread-id>'
  AND role IN ('user', 'assistant')
ORDER BY created_at, message_id;

Open only the copied database. Do not edit it or point a newer or older server at your recovery copy. If the affected environment is remote, make and inspect the copy on the machine that runs that environment.

Source: T3 Code documentation ↗

Reference

Troubleshooting#

A provider cannot start#

Check Settings → Providers on the environment where the thread runs. Confirm the provider is enabled, installed, and authenticated there. If T3 Code cannot find its executable, set Binary path. Check the provider card for a recommended version or compatibility warning.

Read the guide for your provider for account, runtime, and permission details.

Setup is still connecting#

The welcome wizard shows Still connecting when it cannot confirm the workspace. Choose Reload to try again. If it shows Could not read settings, use Retry after storage becomes available. See first-run setup.

Another device cannot connect#

Make sure the environment's server is running and reachable from that device. Follow the connection method you chose: T3 Connect, a LAN or private network, or desktop-managed SSH.

See remote access troubleshooting, background service troubleshooting, and updates and compatibility.

A shortcut does something unexpected#

On web and desktop, check Settings → Keybindings for the defaults in your version. mod means Command on macOS and Ctrl on Windows and Linux. A desktop shortcut can take the same keys; choose another binding when that happens.

Read keyboard shortcuts for rule precedence, focus behavior, composer controls, and iPad differences.

Usage limits or an update error#

Check usage and limits and your provider's account guide for subscription limits. For failed app or server updates, use the recovery steps in updating T3 Code.

Still need help?#

Read T3 Code's contribution and support policy before opening an issue. Include the exact error and relevant version information. Review diagnostics before sharing; startup reports can include values from the app.

Guide based on T3 Code’s user documentation and glossary.

Reference

Privacy & usage data#

The T3 Code server sends product usage events to PostHog, associated with a hashed account or installation identifier. Events include the provider, model, reasoning effort, permission mode, turn result, duration, and main-agent token totals when available.

Events do not include prompts, responses, file contents, authentication tokens, conversation IDs, raw provider events, or child-agent output. Child-agent token use is excluded from the totals.

To disable collection, set T3CODE_TELEMETRY_ENABLED=false in the server's environment before starting it. This stops product events from being recorded or sent.

The desktop app reads the variable from your shell profile (for example ~/.zshrc) on macOS and Linux, so export it there and restart the app. On Windows, set it as a user environment variable.

Export diagnostics to your own receiver#

To send traces, metrics, or logs to an OpenTelemetry receiver, open Settings > General > Diagnostics, select an environment, and enter each signal's OTLP HTTP endpoint under OpenTelemetry export (for example http://localhost:4318/v1/traces). Save, then restart that environment's server. The receiver must be reachable from the server's machine. Test sends an empty export from the server to check an endpoint before or after you save it; saved endpoints are checked when the section opens. Checks send authentication headers only to the signal's currently running endpoint and do not follow redirects. To check a new endpoint that requires authentication, save it and restart the server first.

T3CODE_OTLP_*_URL and standard OTEL_EXPORTER_OTLP_* environment variables override the saved settings. For endpoints saved here or set with T3CODE_OTLP_*_URL, set T3CODE_OTLP_HEADERS for receivers that need authentication and T3CODE_OTLP_PROTOCOL=http/protobuf for receivers that do not accept JSON. An endpoint set with OTEL_EXPORTER_OTLP_* takes its headers and protocol from OTEL_EXPORTER_OTLP_HEADERS and OTEL_EXPORTER_OTLP_PROTOCOL instead.

Source: T3 Code documentation ↗

Reference

Open-source licenses#

T3 Code includes third-party software and adapted assets. To read their license and attribution notices:

• On web and desktop, open Settings → General, find Open source licenses under About, and select View licenses.

• On mobile, open Settings → About T3 Code → Open source licenses.

The page lists the version when available, license identifier, and the parts of T3 Code that include or use the item. This also covers optional device tools that T3 Code installs on demand instead of bundling. Select a row to read the complete notice text. Use the search field to find a package, version, license, or app component.

Source: T3 Code documentation ↗