t3code-sdk

DO NOT USE IT. THIS IS JUST ME JUST DOING EXPERIMENTATION. THIS IS ALSO NOT AFFILIATED TO THE T3CODE.

Unofficial, Node-first TypeScript SDK for controlling a T3 Code backend.

Early experimental development. The API is not stable yet.

Why

T3 Code already provides a strong backend for agent sessions, projects, worktrees, approvals, terminals, Git, and multiple providers. This SDK makes that backend usable from bots, CI, automations, and custom applications without importing T3 Code's UI runtime.

Current status

Implemented:

• environment discovery

• one-time bootstrap token exchange and bearer authentication

• access-token suppliers, refresh hooks, and single retry on 401/403

• project and thread snapshots

• project and thread creation and deletion

• turns, interrupts, and approval responses

• a high-level threads.run() that correlates a turn to its outcome and interrupts on abort

• caller-supplied deterministic command, project, thread, and message ids

• image attachments as native model input

• typed Effect RPC transport over WebSocket

• shell and thread subscriptions that reconnect, resume from the last seen sequence, and drop replayed items

• threads.stream(): the same run as a normalized AsyncGenerator of events (dispatched, working, title, text deltas, activity, completed)

• threads.wait(): re-attach to an in-flight turn after a restart using its threadId, messageId, and createdAt

• proactive token refresh ahead of expires_in, plus retry on 401/403

• session(), live capabilities(), and a WebSocket health() probe

• raw HTTP and orchestration command escape hatches

• exact, integrity-checked upstream contract pinning

• live compatibility CI: scripts/live-smoke.mjs runs against released t3 versions in the compat workflow matrix

• a vendored contract snapshot trimmed to the SDK's transitive import closure, with a narrow orchestration-only RPC group

Next:

• optional managed t3 serve process lifecycle
• approval and user-input handling inside run()/stream()

Usage

Start a T3 Code backend with t3 serve. It prints a connection string and one-time token.

import { T3Code } from "@shivamhwp/t3code-sdk";

await using t3 = await T3Code.connect({
  baseUrl: "http://localhost:3773",
  bootstrapToken: process.env.T3_BOOTSTRAP_TOKEN!,
  scopes: ["orchestration:read", "orchestration:operate"],
  client: { label: "my automation", deviceType: "bot" },
});

const projects = await t3.projects.list();
const created = await t3.projects.create({
  workspaceRoot: "/path/to/repo",
});

const thread = await t3.threads.create({
  projectId: created.id,
  title: "Fix the login bug",
  modelSelection: { instanceId: "codex", model: "gpt-5.6-sol" },
});

const result = await t3.threads.run(
  { threadId: thread.id, prompt: "Fix the login bug and run the tests." },
  { onWorking: () => console.log("working…"), onTitle: (title) => console.log(title) },
);
console.log(result.response);

for await (const item of t3.subscribeShell()) {
  console.log(item); // reconnects and resumes automatically
}

An existing bearer token from t3 auth session issue --token-only can be supplied as accessToken instead — either a string or an async supplier, with an optional refreshAccessToken hook for rotation.

Upstream pinning

The SDK does not clone, fork, or track T3 Code's moving main branch. upstream/t3code.lock.json records one exact upstream commit, Effect version, source paths, and an aggregate integrity hash.

The pinned packages/contracts snapshot is committed under upstream/contracts and bundled into the SDK. T3 Code's client-runtime is not shipped or imported.

Update intentionally:

bun run sync:upstream <t3code-commit>
bun run check
bun run test
bun run build

Verify the committed snapshot without changing it:

bun run sync:upstream:check

TypeScript consumers

Node 22.16+ and TypeScript 5.2+ are required. Use "lib": ["esnext"] (or add "esnext.disposable") for await using, install @types/node, and keep "skipLibCheck": true — the pinned effect beta's own declarations do not pass a full lib check. Verified against a strict nodenext consumer.

Development

bun install
bun run check
bun run test
bun run build