T3ex Config Help

Configure T3 Code

T3 Code reads configuration from three places. Two are hand-editable; one is owned by the app.

A dev-mode server (vp run dev) uses ~/.t3/dev/ instead of ~/.t3/userdata/.

The published docs say keybindings live at ~/.t3/keybindings.json. That is wrong — the code joins the filename to the state directory, so the real path is ~/.t3/userdata/keybindings.json. Editing the documented path does nothing.

After any edit, check your work:

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

This matters more than usual here: T3 Code silently ignores invalid rules and invalid files. A typo means your shortcut quietly never fires, with only a warning in the server log.

Project scripts — the "actions" in the scripts menu

Scripts are the buttons in T3 Code's scripts menu. They run in a T3 Code terminal at the project root, and they are checked into the repo so the whole team gets them.

{
  "$schema": "https://t3.codes/schema/t3.json",
  "iconPath": "assets/logo.svg",
  "scripts": [
    {
      "name": "Dev server",
      "command": "pnpm dev",
      "icon": "play",
      "previewUrl": "http://localhost:3000",
      "autoOpenPreview": true
    },
    {
      "name": "Setup Worktree",
      "command": "pnpm install && ln -sf $T3CODE_PROJECT_ROOT/.env .env",
      "icon": "configure",
      "runOnWorktreeCreate": true
    }
  ]
}

Limits: 50 scripts, iconPath at most 512 characters.

Two environment variables

Scripts get these injected:

• T3CODE_PROJECT_ROOT — the project's main directory, always set
• T3CODE_WORKTREE_PATH — the worktree path, only when running in a worktree

This distinction is the point. A script's working directory is the worktree when one exists, so T3CODE_PROJECT_ROOT is how you reach back to the main checkout — which is how you symlink a gitignored .env into a fresh worktree.

Gotchas that cost real time

• Only the first runOnWorktreeCreate script runs. Marking a second one has no effect and no warning. Combine them into one setup script with &&.
• previewUrl is desktop-only. In a browser tab it is ignored and you open the URL yourself.
• autoOpenPreview without previewUrl does nothing.
• Scripts are shared with everyone who opens the repo. Don't put machine-specific paths or secrets in a command.

Keyboard shortcuts

~/.t3/userdata/keybindings.json is a JSON array. Your file replaces the defaults wholesale, so copy the defaults first if you only want to change one thing.

[
  { "key": "mod+j", "command": "terminal.toggle" },
  { "key": "mod+shift+d", "command": "terminal.splitVertical", "when": "terminalFocus" },
  { "key": "mod+1", "command": "script.browser.run" }
]

key and command are required; when is optional. Maximum 256 rules.

Modifiers: mod (⌘ on macOS, Ctrl elsewhere), cmd/meta, ctrl/control, shift, alt/option.

Commands:

sidebar.toggle          rightPanel.toggle       commandPalette.toggle
terminal.toggle         terminal.split          terminal.splitVertical
terminal.new            terminal.close          diff.toggle
preview.toggle          preview.refresh         preview.focusUrl
preview.zoomIn          preview.zoomOut         preview.resetZoom
chat.new                chat.newLocal           editor.openFavorite
modelPicker.toggle      modelPicker.jump.1-9
thread.previous         thread.next             thread.jump.1-9
script.{id}.run

when contexts: terminalFocus, terminalOpen, previewFocus, previewOpen, modelPickerOpen. Operators: !, &&, ||, parentheses. Unknown context names evaluate to false, so a typo disables the binding rather than erroring.

Precedence: rules are evaluated in array order, and for a given key press the last matching rule wins — across all commands, not just within one. If a shortcut isn't working, look for a later rule that shadows it.

Binding a key to your own script

script.{id}.run needs the script's id, which is not in t3.json — T3 Code assigns it when the script is imported, as a lowercase slug of the name ("Browser" → browser). Read the real ids from the state database:

sqlite3 ~/.t3/userdata/state.sqlite \
  "SELECT title, scripts_json FROM projection_projects WHERE scripts_json != '[]';"

The id must match ^[a-z0-9][a-z0-9-]*$ and be at most 24 characters. validate.py cross-checks the ids you reference against the ones that actually exist.

App settings

~/.t3/userdata/settings.json holds app behavior and provider configuration:

• enableAssistantStreaming, enableProviderUpdateChecks
• automaticGitFetchInterval, newWorktreesStartFromOrigin
• defaultThreadEnvMode — local or worktree, for new threads
• addProjectBaseDirectory — where the "add project" picker starts
• textGenerationModelSelection — the model used for commit messages and titles
• providers / providerInstances — per-driver config for codex, claudeAgent, cursor, grok, opencode, including binary paths and custom models
• observability

Change these in the UI, not the file. The server owns this file and rewrites it; a hand edit made while T3 Code is running will be overwritten without warning. Read it to answer questions, and to confirm a settings change landed.

Note this file configures which providers T3 Code can drive. It does not configure the agents themselves — Codex still reads ~/.codex/config.toml, and MCP servers are configured per-provider, not in T3 Code.

Answering "why isn't my config working?"

Work down this list:

1. Run validate.py — it catches most of it.
2. Check the path. ~/.t3/keybindings.json (documented) is not the real one.
3. For a shortcut, look for a later rule with the same key — last match wins.
4. For a when clause, confirm every context name is in the list above.
5. For a script, restart or reopen the project so t3.json is re-read.
6. Check the server log for parse warnings: ~/.t3/userdata/logs/server.log.