t3code-extensions

Add-ons for T3 Code that give it new panels and give your agents new tricks.

T3 Code itself is never modified. Everything here plugs into hooks that already exist.

What's in here

Two kinds of add-on, useful on their own or together.

Extensions are small web apps that open inside T3 Code's preview panel, so your docs, tasks, and code sit right next to the conversation instead of in another window. You add one line to your project's t3.json — or let the t3ex command write it for you — and it shows up in the scripts menu.

Skills are instructions your coding agent reads. Two of them teach it to work with your own conversation history — digging up a session you half-remember and picking that work back up. The third teaches it to set T3 Code up for you. No web app, no server, nothing to keep running.

The two history skills are built to be used in sequence:

/t3ex-find-thread the dev server on port 3001   →  finds it, hands you the id
/t3ex-fork-thread ce419dc7                      →  picks the work back up

Say you spent an hour last week getting a build working, then moved on. Later you need that context back, minus the last few messages where things went sideways. Find the thread by what you remember saying, reload it up to the point where it was still on track, and carry on — with a different model if you want a second opinion.

The third one is for changing T3 Code itself:

/t3ex-config-help add a "Dev server" button that opens localhost:3000
/t3ex-config-help bind cmd+1 to my dev script

Instead of you looking up which file to edit and what the valid values are, the agent already knows — and checks its work, because T3 Code ignores a config mistake silently rather than telling you.

Everything reads your local files only. Nothing is uploaded, and your original conversations are never modified.

Extensions

Package	What it is	Status
@t3ex/docs	Markdown and diagram workspace over a project's docs folders	ready
@t3ex/kanban	Kanban board over Beads issues	ready
@t3ex/automate	Scheduled agent runs that open as real T3 Code threads	ready
@t3ex/code	CodeMirror editor with tree, tabs, git gutters, and search	ready

Using an extension

Add it to your project's t3.json:

{
  "scripts": [
    {
      "name": "Docs",
      "command": "npx @t3ex/docs",
      "previewUrl": "http://localhost:7801",
      "autoOpenPreview": true
    }
  ]
}

Run the script from T3 Code's scripts menu. It starts the extension server in a terminal and opens the UI in the preview panel.

The t3ex CLI writes this entry for you:

npx t3ex init docs

Agent skills

This repo also ships skills for coding agents, under skills/. They are not web apps and need no pairing — they are instructions plus a script, installed into whichever agents you use.

Skill	What it does
t3ex-find-thread	Find a past T3 Code, Codex, or Claude Code conversation by what was said in it, and return its id
t3ex-fork-thread	Continue an existing T3 Code thread in a new session, under a different model, optionally cutting everything from a chosen message onward
t3ex-config-help	Configure T3 Code itself — scripts menu actions, keyboard shortcuts, app settings — and validate the result

The first two pair: t3ex-find-thread gets you the id, t3ex-fork-thread picks the work back up.

Installing with skills.sh

Install with the skills CLI. No install step of its own — npx runs it directly:

npx skills add maddada/t3code-extensions --skill t3ex-find-thread --skill t3ex-fork-thread

From a local clone, point it at the directory instead:

npx skills add ./t3code-extensions --skill t3ex-fork-thread

Drop --skill to be prompted for all of them, or add --list to see what a source offers without installing anything.

Useful flags:

-g, --global              install for all projects rather than this one
-a, --agent <agent>       target specific agents, repeatable
    --list                show what a source offers without installing
-y, --yes                 skip prompts

To put it in front of the agents that actually drive T3 Code threads:

npx skills add maddada/t3code-extensions \
  --skill t3ex-find-thread --skill t3ex-fork-thread \
  -g -a claude-code -a codex

Then npx skills list to confirm, and npx skills update to pull later changes.

Finding a thread

When you remember the topic but not the id:

/t3ex-find-thread the dev server on port 3001
/t3ex-find-thread sidebar icon --repo Maestro3

It searches T3 Code's database plus the Codex and Claude Code transcript files in one pass, newest first, and prints each hit's id and resume command. A T3 Code thread that ran on Codex exists in both stores; those are folded into a single result reporting the T3 Code id, which is the one the fork skill takes.

Forking a thread

Copy a thread id from the T3 Code sidebar and hand it to the agent:

/t3ex-fork-thread ce419dc7
/t3ex-fork-thread ce419dc7 07:58
/t3ex-fork-thread ce419dc7 through 07:58  now add a start script too

A bare time drops that message and everything after it — you are pointing at where the thread went wrong. through keeps it and drops only what follows. With no time, the whole thread loads. Times are local, exactly as the sidebar shows them.

Given a thread id alone the agent orients and waits; add an instruction and it picks the work straight up.

The thread is read from ~/.t3/userdata/state.sqlite, read-only — the original is never modified, and T3 Code can stay running. Conversation text and a one-line trace of each command and file diff are loaded; bulky captured stdout is withheld and its size reported, which takes a thread with 1.1 MB of tool activity down to roughly 39 KB.

Configuring T3 Code

Ask for what you want and let the agent find the right file and field:

/t3ex-config-help add a "Dev server" action that runs pnpm dev and opens localhost:3000
/t3ex-config-help bind cmd+shift+d to split the terminal vertically
/t3ex-config-help why isn't my mod+k shortcut working?

It covers the three places T3 Code keeps configuration — project scripts and the project icon in t3.json, shortcuts in keybindings.json, and app settings — including which of them are safe to edit by hand.

The skill ships a checker you can also run yourself:

python3 validate.py                 # ./t3.json and your keybindings.json

Worth having, because T3 Code drops invalid rules and invalid files silently: a bad icon name or a mistyped when clause means the thing just never happens, with nothing but a line in the server log. The checker also catches rules that are valid but dead — a second runOnWorktreeCreate script that will never run, or a shortcut shadowed by a later one.

CLI

Setup
  t3ex init [name...]        add extensions to this project's t3.json
  t3ex remove <name>         remove an extension from t3.json
  t3ex list                  show available extensions and their status
  t3ex status                check this project's setup

T3 Code pairing
  t3ex pair [url|token]      pair so extensions can open threads
  t3ex unpair                forget the stored credential
  t3ex whoami                show the current pairing

Config
  t3ex config list           show merged config and where each value came from
  t3ex config get <path>     read one value
  t3ex config set <path> <value>     --project shares it with your team
  t3ex config unset <path>

Other
  t3ex run <name>            run an extension outside T3 Code
  t3ex clean                 remove this project's stored state

init picks each extension's default port, skipping ports already claimed in t3.json or in use on the machine. Existing entries are updated in place rather than duplicated, and a label you renamed is kept.

Config paths use dots, with id entries in brackets:

t3ex config set docs.roots '["docs","notes"]'
t3ex config set automations[nightly].enabled true

Pairing

Pairing lets Kanban's "Start work" and Automate open real T3 Code threads. Without it, extensions still work — Kanban falls back to "Copy Prompt".

t3ex pair "http://192.168.1.4:3773/pair#token=…"

Get a pairing URL from the desktop app under Settings → Remote access → Create Link, or from the URL t3 serve prints at startup. The token is exchanged for a bearer credential scoped to orchestration:read and orchestration:operate, stored at ~/.config/t3ex/auth.json with mode 0600.

Extensions also run standalone, outside T3 Code:

npx @t3ex/docs --project ~/code/my-app

The preview panel embeds pages only in the desktop T3 Code app. In a browser tab, previewUrl is ignored and you open the URL yourself.

Config and state

Nothing is written into your repository by default.

~/.config/t3ex/            # honors XDG_CONFIG_HOME; %APPDATA%\t3ex on Windows
  auth.json                # pairing credentials (0600)
  config.json              # your settings
  projects/<key>/          # per-project state

A project may commit .t3ex/config.json to share settings with its team. Repo config is the baseline and your config overrides it. Settings changed in the UI are saved to your config; sharing is an explicit "Save to project" action.

Per-project state is keyed on the main repository root, so all worktrees of a repo share one state directory.

Development

pnpm install
pnpm test          # turbo run test
pnpm typecheck

Layout:

packages/host-kit    shared server runtime: config, project identity, file API
packages/ui          shared UI primitives
extensions/*         one publishable package per extension
cli/t3ex             the t3ex CLI
skills/*             agent skills, one folder per SKILL.md
apps/manager         T3Ex Manager — native desktop app (Rust/gpui) that manages
                     extensions, skills, and pairing; lives in the menu bar

T3Ex Manager (desktop app)

A small always-there companion app, built with gpui and gpui-component. It installs extensions and skills per project, handles T3 Code pairing, and sits in the macOS menu bar (Windows/Linux tray planned). It shells out to the same t3ex CLI and skills CLI documented above, so everything it does can also be done by hand.

cd apps/manager
cargo run          # expects ../../../custom/gpui-component; override the CLI
                   # location with T3EX_REPO if you move the checkout

skills/ is outside the pnpm workspace — the skills are plain files that the skills CLI copies, not packages. Each folder needs a SKILL.md with name and description frontmatter; skills/<name>/SKILL.md is the layout the CLI looks for.

Design decisions and their reasoning: docs/DECISIONS.md.