From 5c9fe87278a476de3519f673f659f86b7da197d2 Mon Sep 17 00:00:00 2001 From: zachspartofaday <234074810+zachspartofaday@users.noreply.github.com> Date: Mon, 26 Oct 2026 01:47:35 -0400 Subject: [PATCH 1/4] docs(skills): guide T3 sessions across environments --- .agents/skills/t3-sessions/SKILL.md | 59 +++++++++++ .agents/skills/t3-sessions/agents/openai.yaml | 4 + .agents/skills/t3-sessions/references/cli.md | 98 +++++++++++++++++++ 3 files changed, 161 insertions(+) create mode 100644 .agents/skills/t3-sessions/SKILL.md create mode 100644 .agents/skills/t3-sessions/agents/openai.yaml create mode 100644 .agents/skills/t3-sessions/references/cli.md diff --git a/.agents/skills/t3-sessions/SKILL.md b/.agents/skills/t3-sessions/SKILL.md new file mode 100644 index 000000000000..6202027ae6a2 --- /dev/null +++ b/.agents/skills/t3-sessions/SKILL.md @@ -0,0 +1,59 @@ +--- +name: t3-sessions +description: Find, read, message, and start T3 Code conversations, including sessions on another environment through an existing SSH connection. Use for T3 session communication, not ordinary coding or generic subagent requests. +--- + +# T3 sessions + +T3 tools address the environment serving them. Seeing another environment in +the client does not make its threads reachable through the current MCP server; +a local `thread_not_found` does not establish that a remote thread is gone. + +## Choose the destination + +Identify the destination environment, project and exact thread ID. Keep any +`mcp:` prefix. Use an available, authorized MCP connection to that destination +and its current tool schemas. Do not invent an environment-routing parameter. + +For another host without a destination MCP connection, use its supported +`t3 thread` CLI over an existing authorized SSH route, as the account owning +that T3 environment. Confirm the executable and T3 home, including any custom +`--base-dir`. Read [CLI and SSH commands](references/cli.md) before using this +route. The same CLI works locally for agents outside T3. + +[Outside agents](https://github.com/pingdotgg/t3code/blob/main/docs/user/outside-agents.md) +describes supported MCP setup. Missing access, authentication or a running +server is a prerequisite to report; do not extract credentials, hand-build +tokens, write the live database or restart a service to reach a thread. + +## Read, message or start + +- Inspect the destination thread's state and recent messages before answering + about it or sending. Resolve ambiguous recipients before a mutation. Sending + or launching must be authorized by the user's task; reading a reference does + not authorize a message. +- Start a top-level conversation only when a new or separate session was + requested. A subagent request uses the host's delegation workflow. CLI-created + conversations have no delegated-task lifecycle or automatic parent result + delivery. +- Select the destination project and intended workspace before launch. Use the + supported worktree option for independent code work. Its base ref must exist + on the destination; local dirty files and caller context do not transfer. +- CLI launches use destination defaults, not the caller's settings. Preserve + requested provider, model, options and permission limits. If the destination + interface cannot represent or verify them, report the gap before launch. + Host access does not override the calling session's restrictions. + +## Receive and continue + +Retain the destination, thread/run IDs and observed status. Use the returned +thread link when available. Acceptance is not completion: inspect the result +for the requested run, including failed or waiting-for-input states. + +After an uncertain send or launch, inspect the destination before retrying. +The CLI exposes no retry key. If you cannot establish whether it succeeded, +report the uncertainty instead of duplicating work. + +Before following up, inspect the latest messages and respect a user's takeover +or stop request. Stopping automatic messages does not stop a running agent; +use an available, authorized stop control if that is what the user requested. diff --git a/.agents/skills/t3-sessions/agents/openai.yaml b/.agents/skills/t3-sessions/agents/openai.yaml new file mode 100644 index 000000000000..33d055ee9b0a --- /dev/null +++ b/.agents/skills/t3-sessions/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "T3 Sessions" + short_description: "Read, message and start T3 sessions across environments" + default_prompt: "Use $t3-sessions to find and inspect the requested T3 conversation on its destination environment." diff --git a/.agents/skills/t3-sessions/references/cli.md b/.agents/skills/t3-sessions/references/cli.md new file mode 100644 index 000000000000..065be8991355 --- /dev/null +++ b/.agents/skills/t3-sessions/references/cli.md @@ -0,0 +1,98 @@ +# T3 CLI across environments + +These examples use SSH to run the CLI on the destination. For a local +environment, run the same CLI commands directly. Replace `T3_HOST` with an +existing SSH destination for the account owning T3, and replace the executable, +T3 home, project path and IDs with checked destination values. Shell-quote +replacement arguments for the destination shell; the examples use POSIX shells. + +Use the installed launcher for that environment. Desktop installations provide +`~/.t3/bin/t3`; another `t3` on a noninteractive PATH may belong to a different +installation. Keep `--base-dir` consistent on every command. It names the T3 +home, not its `userdata` subdirectory or the project directory. + +## Discover and inspect + +Check the destination's installed capabilities before choosing commands or flags: + +```sh +ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread --help' +ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread start --help' +ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread list --base-dir "/absolute/path/to/t3-home" --json --project "/absolute/path/to/project"' +ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread show --base-dir "/absolute/path/to/t3-home" --json --messages 4 "THREAD_ID"' +``` + +The project must already be registered on that environment. A project ID or a +path inside the project works. Use the exact thread ID from the destination, +including any `mcp:` prefix. `show --json` includes thread state and recent +messages; inspect its workspace, model and modes as relevant to the task. + +## Send and retrieve the reply + +Pass literal message text through stdin. A quoted heredoc keeps shell syntax in +the prompt from being evaluated by the sending shell: + +```sh +ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread send --base-dir "/absolute/path/to/t3-home" --json "THREAD_ID" -' <<'T3_MESSAGE' +Request REQUEST_ID from SOURCE_SESSION: please report the current result of TASK. +Reply in this conversation. +T3_MESSAGE +``` + +Replace the example message with the authorized request and a recognizable +correlation label. Retain the returned thread/run IDs. CLI `send` queues a new +turn behind a busy one; it does not steer or interrupt it. + +Read the result from the same destination: + +```sh +ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread show --base-dir "/absolute/path/to/t3-home" --json --messages 4 "THREAD_ID"' +``` + +Match message `runId` values to the request, rather than assuming the latest +assistant message answers it. Increase `--messages` if another turn has since +run. For efficient paged history or richer run inspection, use destination MCP +tools when available; `--messages` limits printed output, not history retrieval. + +When sending or starting, add `--wait` if you want that command to wait for its +run and print the reply. Use an interruptible execution session for long waits. +Exit 1 means the run failed or stopped; exit 2 means it needs an answer in the +app. With `--json`, inspect the returned status, IDs, reply and error. IDs are +printed after the wait finishes, so a disconnected wait can leave an uncertain +outcome. Without `--wait`, acceptance returns promptly and results can be read +later; it does not create an automatic completion callback. + +## Start a requested conversation + +Choose a destination project and give it a recognizable title and task label. +For independent code work, let T3 create and bind a worktree before the agent +starts: + +```sh +ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread start --base-dir "/absolute/path/to/t3-home" --json --title "Requested task REQUEST_ID" --worktree "BASE_REF" --branch "NEW_BRANCH" --provider "PROVIDER_INSTANCE" --model "MODEL_SLUG" "/absolute/path/to/project" -' <<'T3_TASK' +Request REQUEST_ID from SOURCE_SESSION. +Task: DESCRIBE_REQUESTED_WORK +Scope and allowed actions: DESCRIBE_BOUNDARIES +Acceptance and reply: DESCRIBE_EXPECTED_RESULT +T3_TASK +``` + +Replace the example brief and every symbolic argument with the actual request +and checked destination values. `--provider` and `--model` go together; omit +both only when destination defaults are acceptable. Omit `--worktree` and +`--branch` when sharing the project folder is intended. `--branch` requires +`--worktree`, and the base ref and committed inputs must exist remotely. + +Read the new thread with `show --json` to confirm its workspace, model and modes +and obtain its link. It does not expose model options such as reasoning effort; +verify required options through supported project/configuration controls before +launch. The CLI's `start --json` result contains IDs, not a link. +Current CLI help does not expose model-option or permission-mode flags, or a +stop command. Check installed help for changes; do not invent flags or silently +drop requested settings. Use verified suitable defaults or an authorized +destination MCP interface when those controls are needed. + +If SSH disconnects or a response is lost, reconcile `list` and `show` using +the title, request label and messages before repeating a mutation. Neither +`start` nor `send` exposes an idempotency flag. A reverse message needs its own +authorized destination connection; otherwise read the reply where it was sent. From dc83357b32d57172974f71c2223398d99bf48b8e Mon Sep 17 00:00:00 2001 From: zachspartofaday <234074810+zachspartofaday@users.noreply.github.com> Date: Mon, 26 Oct 2026 01:49:38 -0400 Subject: [PATCH 2/4] docs(skills): clarify CLI options and uncertain outcomes --- .agents/skills/t3-sessions/SKILL.md | 2 +- .agents/skills/t3-sessions/references/cli.md | 24 ++++++++++++-------- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/.agents/skills/t3-sessions/SKILL.md b/.agents/skills/t3-sessions/SKILL.md index 6202027ae6a2..e7d3db5c0536 100644 --- a/.agents/skills/t3-sessions/SKILL.md +++ b/.agents/skills/t3-sessions/SKILL.md @@ -24,7 +24,7 @@ route. The same CLI works locally for agents outside T3. [Outside agents](https://github.com/pingdotgg/t3code/blob/main/docs/user/outside-agents.md) describes supported MCP setup. Missing access, authentication or a running server is a prerequisite to report; do not extract credentials, hand-build -tokens, write the live database or restart a service to reach a thread. +tokens, edit the live database directly or restart a service to reach a thread. ## Read, message or start diff --git a/.agents/skills/t3-sessions/references/cli.md b/.agents/skills/t3-sessions/references/cli.md index 065be8991355..c1f94d93e1a7 100644 --- a/.agents/skills/t3-sessions/references/cli.md +++ b/.agents/skills/t3-sessions/references/cli.md @@ -56,11 +56,13 @@ tools when available; `--messages` limits printed output, not history retrieval. When sending or starting, add `--wait` if you want that command to wait for its run and print the reply. Use an interruptible execution session for long waits. -Exit 1 means the run failed or stopped; exit 2 means it needs an answer in the -app. With `--json`, inspect the returned status, IDs, reply and error. IDs are -printed after the wait finishes, so a disconnected wait can leave an uncertain -outcome. Without `--wait`, acceptance returns promptly and results can be read -later; it does not create an automatic completion callback. +For a returned run result, exit 1 means it failed or stopped; exit 2 means it +needs an answer in the app. Command, transport and result-retrieval errors also +fail the command, so exit 1 alone does not prove the run failed. Inspect stderr +and any JSON status, IDs, reply and error; reconcile an unknown outcome before +retrying. IDs are printed after the wait finishes, so a disconnected wait can +leave no receipt. Without `--wait`, acceptance returns promptly and results can +be read later; it does not create an automatic completion callback. ## Start a requested conversation @@ -78,10 +80,14 @@ T3_TASK ``` Replace the example brief and every symbolic argument with the actual request -and checked destination values. `--provider` and `--model` go together; omit -both only when destination defaults are acceptable. Omit `--worktree` and -`--branch` when sharing the project folder is intended. `--branch` requires -`--worktree`, and the base ref and committed inputs must exist remotely. +and checked destination values. `--provider` and `--model` go together and +replace the entire model selection; they do not inherit saved model options. +To retain project options, verify the complete destination default selection +and omit both flags. If the requested selection cannot be expressed by the CLI, +use an authorized destination MCP interface or report the gap before launch. +Omit `--worktree` and `--branch` when sharing the project folder is intended. +`--branch` requires `--worktree`, and the base ref and committed inputs must +exist remotely. Read the new thread with `show --json` to confirm its workspace, model and modes and obtain its link. It does not expose model options such as reasoning effort; From 5ae15ba1e04ea943a63692ada45590f207b72bd2 Mon Sep 17 00:00:00 2001 From: zachspartofaday <234074810+zachspartofaday@users.noreply.github.com> Date: Mon, 26 Oct 2026 01:54:20 -0400 Subject: [PATCH 3/4] docs(skills): emphasize cross-environment session management --- .../{t3-sessions => t3-cross-environment}/SKILL.md | 14 ++++++++++---- .../skills/t3-cross-environment/agents/openai.yaml | 4 ++++ .../references/cli.md | 11 ++++++----- .agents/skills/t3-sessions/agents/openai.yaml | 4 ---- 4 files changed, 20 insertions(+), 13 deletions(-) rename .agents/skills/{t3-sessions => t3-cross-environment}/SKILL.md (80%) create mode 100644 .agents/skills/t3-cross-environment/agents/openai.yaml rename .agents/skills/{t3-sessions => t3-cross-environment}/references/cli.md (92%) delete mode 100644 .agents/skills/t3-sessions/agents/openai.yaml diff --git a/.agents/skills/t3-sessions/SKILL.md b/.agents/skills/t3-cross-environment/SKILL.md similarity index 80% rename from .agents/skills/t3-sessions/SKILL.md rename to .agents/skills/t3-cross-environment/SKILL.md index e7d3db5c0536..5b758918745d 100644 --- a/.agents/skills/t3-sessions/SKILL.md +++ b/.agents/skills/t3-cross-environment/SKILL.md @@ -1,9 +1,15 @@ --- -name: t3-sessions -description: Find, read, message, and start T3 Code conversations, including sessions on another environment through an existing SSH connection. Use for T3 session communication, not ordinary coding or generic subagent requests. +name: t3-cross-environment +description: Manage T3 Code sessions across devices and environments. Use to find and inspect remote threads, exchange messages, retrieve replies, and start requested sessions or worktrees through destination MCP or an existing SSH connection. --- -# T3 sessions +# T3 cross-environment session management + +Use this skill to manage T3 sessions on another device or environment: find +conversations, inspect their state, exchange messages, read results and start +new sessions when requested. For example, a Linux host can coordinate work +in a Mac-hosted conversation. Each environment is a running T3 server with its +own projects and threads; separate environments can also run on the same device. T3 tools address the environment serving them. Seeing another environment in the client does not make its threads reachable through the current MCP server; @@ -19,7 +25,7 @@ For another host without a destination MCP connection, use its supported `t3 thread` CLI over an existing authorized SSH route, as the account owning that T3 environment. Confirm the executable and T3 home, including any custom `--base-dir`. Read [CLI and SSH commands](references/cli.md) before using this -route. The same CLI works locally for agents outside T3. +route. [Outside agents](https://github.com/pingdotgg/t3code/blob/main/docs/user/outside-agents.md) describes supported MCP setup. Missing access, authentication or a running diff --git a/.agents/skills/t3-cross-environment/agents/openai.yaml b/.agents/skills/t3-cross-environment/agents/openai.yaml new file mode 100644 index 000000000000..70fbcee88595 --- /dev/null +++ b/.agents/skills/t3-cross-environment/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "T3 Cross-Environment Management" + short_description: "Manage T3 sessions across devices and environments" + default_prompt: "Use $t3-cross-environment to manage the requested T3 sessions on another device or environment." diff --git a/.agents/skills/t3-sessions/references/cli.md b/.agents/skills/t3-cross-environment/references/cli.md similarity index 92% rename from .agents/skills/t3-sessions/references/cli.md rename to .agents/skills/t3-cross-environment/references/cli.md index c1f94d93e1a7..a1587b2d175e 100644 --- a/.agents/skills/t3-sessions/references/cli.md +++ b/.agents/skills/t3-cross-environment/references/cli.md @@ -1,10 +1,11 @@ # T3 CLI across environments -These examples use SSH to run the CLI on the destination. For a local -environment, run the same CLI commands directly. Replace `T3_HOST` with an -existing SSH destination for the account owning T3, and replace the executable, -T3 home, project path and IDs with checked destination values. Shell-quote -replacement arguments for the destination shell; the examples use POSIX shells. +These examples use SSH to run the CLI on the destination device, where the +session lives or will be started. If already executing on that device, omit +the SSH wrapper. Replace `T3_HOST` with an existing SSH destination for the +account owning T3, and replace the executable, T3 home, project path and IDs +with checked destination values. Shell-quote replacement arguments for the +destination shell; the examples use POSIX shells. Use the installed launcher for that environment. Desktop installations provide `~/.t3/bin/t3`; another `t3` on a noninteractive PATH may belong to a different diff --git a/.agents/skills/t3-sessions/agents/openai.yaml b/.agents/skills/t3-sessions/agents/openai.yaml deleted file mode 100644 index 33d055ee9b0a..000000000000 --- a/.agents/skills/t3-sessions/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "T3 Sessions" - short_description: "Read, message and start T3 sessions across environments" - default_prompt: "Use $t3-sessions to find and inspect the requested T3 conversation on its destination environment." From 50269375d62c639b0268b080368c18fb5a128c41 Mon Sep 17 00:00:00 2001 From: zachspartofaday <234074810+zachspartofaday@users.noreply.github.com> Date: Mon, 26 Oct 2026 02:30:42 -0400 Subject: [PATCH 4/4] docs(skills): distinguish CLI wait receipts by output mode --- .agents/skills/t3-cross-environment/references/cli.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.agents/skills/t3-cross-environment/references/cli.md b/.agents/skills/t3-cross-environment/references/cli.md index a1587b2d175e..0677d2bc3405 100644 --- a/.agents/skills/t3-cross-environment/references/cli.md +++ b/.agents/skills/t3-cross-environment/references/cli.md @@ -61,9 +61,11 @@ For a returned run result, exit 1 means it failed or stopped; exit 2 means it needs an answer in the app. Command, transport and result-retrieval errors also fail the command, so exit 1 alone does not prove the run failed. Inspect stderr and any JSON status, IDs, reply and error; reconcile an unknown outcome before -retrying. IDs are printed after the wait finishes, so a disconnected wait can -leave no receipt. Without `--wait`, acceptance returns promptly and results can -be read later; it does not create an automatic completion callback. +retrying. Text-mode `start --wait` prints the thread ID to stderr before waiting; +text-mode `send --wait` prints no IDs. With `--json`, `threadId` and `runId` are +printed only in the final result, so a disconnected JSON wait can leave no run +ID or final result. Without `--wait`, acceptance returns promptly and results +can be read later; it does not create an automatic completion callback. ## Start a requested conversation