# t3code-extensions
Add-ons for [T3 Code](https://github.com/pingdotgg/t3code) 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](https://github.com/steveyegge/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`:
```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:
```bash
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`](https://www.skills.sh) CLI. No install step of its
own — `npx` runs it directly:
```bash
npx skills add maddada/t3code-extensions --skill t3ex-find-thread --skill t3ex-fork-thread
```
From a local clone, point it at the directory instead:
```bash
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:
```bash
-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:
```bash
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:
```bash
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:
```bash
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".
```bash
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:
```bash
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
```bash
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](https://github.com/zed-industries/zed)
and [gpui-component](https://github.com/longbridge/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.
```bash
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](./docs/DECISIONS.md).