Use t3code as the supported interface. Do not read T3 credentials or construct bearer tokens directly.
Verify readiness
Run:
t3code --json doctor
Treat data.ok: false as a blocker. Ask the user to start T3 Code when t3Server.ok is false.
Resolve before writing
Inspect the current workspace and matching project:
t3code --json projects resolve --cwd .
The default workspaceMode is repo, which resolves nested folders to their Git root. Use --workspace-mode folder only when the exact subfolder must be a separate T3 project.
A linked Git worktree, such as the one T3 created for your own thread, resolves to the main checkout's project; data.workspace.mainWorktreeRoot shows that checkout. With --checkout current, the new thread works in the same linked worktree. With --checkout worktree, T3 prepares a new worktree from the linked worktree's current branch.
Create a handover thread
Pass prompts over stdin to avoid shell quoting and command-length problems:
printf '%s' "$HANDOVER_PROMPT" | t3code --json handover --stdin
On PowerShell:
$handoverPrompt | t3code --json handover --stdin
--cwd defaults to the process's current working directory. Select thread controls when needed with --provider, --model, --speed, --thinking-effort, --permission, --mode build|plan, and --checkout current|worktree.
Unless command flags or CLI config explicitly override it, a new thread inherits the T3 project's complete saved model selection, including provider-specific options. For a missing project, the CLI uses the detected T3 version's default model (gpt-5.4 on 0.0.28 and gpt-5.6-sol on 0.0.29 and later).
The permission default is full access (full-access). The CLI sends it on the new thread, the first turn, and the atomic worktree bootstrap. An explicit --permission or runtimeMode CLI setting remains authoritative.
With the default --checkout t3, resolve the checkout mode in the same order as T3 Code:
- the project's
defaultThreadEnvModesetting; - the checked-in workspace
t3.jsonvalue; - the current installation's global
defaultThreadEnvModesetting.
Use --project-policy existing when creating a project is not authorized. The default is create.
Use --dry-run --open none to inspect the proposed project and thread commands without changing T3 state.
Optional front-end integration
The CLI can be called from a trusted application backend to power a Send to T3 Code button. This pattern was initially built for the Delano viewer. The optional integrations/ example in this repository includes a React split button and Node bridge; it is not required to install or operate the CLI.
Keep the repository root server-owned, pass CLI options as process arguments, and send the prompt over stdin. A browser should call the protected backend endpoint rather than attempt to launch the local CLI itself.
Interpret results
Read data.project.id, data.thread.id, data.projectCreated, and data.opened. A successful current stable desktop reveal can report opened.exactThread: false; the thread is still created in the resolved project.
On { "ok": false }, report error.code, error.message, and error.cause when present. The cause carries T3's own reason, for example why it rejected a worktree bootstrap. Read the whole envelope instead of filtering it with grep, and do not retry write commands blindly: each attempt creates a new thread id. THREAD_START_FAILED already attempts to delete the newly-created thread; error.details.cleanup reports deleted, not-created, or server-managed.
Current compatibility boundary
T3 0.0.28 and later support new-worktree handovers through the atomic bootstrap contract. Worktree creation follows the current installation's explicit newWorktreesStartFromOrigin setting. When it is absent, use the installed version's default: false on 0.0.28 and true on 0.0.29 and later. WORKTREE_REQUIRES_BRANCH means the selected folder is not a Git repository on a branch; retry with --checkout current only with explicit user or caller authority.
Use t3code --json request get <path> only as a read-only escape hatch. Write the path without its leading slash, for example api/orchestration/shell: Git Bash rewrites /api/... into a Windows file path before the CLI sees it.