Project Scripts

Configure and run custom project scripts in T3 Code

Project scripts allow you to define custom commands that can be executed from the T3 Code interface and bound to keyboard shortcuts. These are perfect for common development tasks like running tests, building, linting, and starting dev servers.

Overview

Project scripts are configured per-project and can:

• Execute any shell command
• Be triggered via keyboard shortcuts (see Keybindings)
• Run automatically when creating new worktrees
• Display with custom icons in the UI

Script Configuration

Scripts are configured through the T3 Code UI in project settings. Each script has the following properties:

Script Properties

id · string · required

Unique identifier for the script.

• Must be 1-24 characters
• Start with lowercase letter or digit
• Can contain lowercase letters, digits, and hyphens
• Used in keybinding commands: script.{id}.run

Examples: test, build, dev, lint-fix

name · string · required

Display name shown in the UI.

This is what users see in the interface. Can contain spaces and special characters.

Examples: Run Tests, Build Production, Start Dev Server

command · string · required

The shell command to execute.

This can be any valid shell command. It runs in the project’s workspace root.

Examples:

• npm test
• bun run build
• cargo test --all
• python -m pytest

icon · 'play' | 'test' | 'lint' | 'configure' | 'build' | 'debug' · required

Icon displayed in the UI.

Choose an icon that best represents the script’s purpose:

• play - General execution, start commands
• test - Test runners
• lint - Linters, formatters
• configure - Setup, configuration scripts
• build - Build commands
• debug - Debugging tools

runOnWorktreeCreate · boolean · required

Whether to automatically run this script when creating a new worktree.

Useful for setup scripts that need to run in fresh worktrees (e.g., installing dependencies).

Default: false

Creating Scripts via UI

1. Open Project Settings

   Navigate to your project and click the settings icon.

2. Add New Script

   Click “Add Script” in the Scripts section.

3. Configure Script

   Fill in the script details:

   • ID (for keybindings)
   • Display name
   • Command to execute
   • Icon
   • Auto-run on worktree creation (optional)
4. Save

   Click Save to persist the script configuration.

Example Scripts

Testing

Node.js (npm)

{
  "id": "test",
  "name": "Run Tests",
  "command": "npm test",
  "icon": "test",
  "runOnWorktreeCreate": false
}

Building

Production Build

{
  "id": "build",
  "name": "Build Production",
  "command": "npm run build",
  "icon": "build",
  "runOnWorktreeCreate": false
}

Linting and Formatting

ESLint

{
  "id": "lint",
  "name": "Lint Code",
  "command": "npm run lint",
  "icon": "lint",
  "runOnWorktreeCreate": false
}

Development Servers

Next.js

{
  "id": "dev",
  "name": "Start Dev Server",
  "command": "npm run dev",
  "icon": "play",
  "runOnWorktreeCreate": false
}

Setup and Installation

Node Dependencies

{
  "id": "install",
  "name": "Install Dependencies",
  "command": "npm install",
  "icon": "configure",
  "runOnWorktreeCreate": true
}

Binding Scripts to Keybindings

Once you’ve created a script, you can bind it to a keyboard shortcut using the script.{id}.run command format.

In your ~/.t3/keybindings.json:

[
  { "key": "mod+shift+t", "command": "script.test.run" },
  { "key": "mod+shift+b", "command": "script.build.run" },
  { "key": "mod+shift+l", "command": "script.lint.run" },
  { "key": "f5", "command": "script.dev.run" }
]

The script ID in the keybinding must exactly match the ID configured in your project settings.

See the Keybindings documentation for more details.

Script Execution Context

Working Directory

Scripts execute in the project’s workspace root directory. For worktree-based threads, scripts run in the worktree directory.

Environment Variables

Scripts inherit the environment from the T3 Code server process. This includes:

• System environment variables
• Shell profile variables (if the server was started from a shell)
• Any custom environment variables set when launching T3 Code

Shell

Scripts are executed using the system’s default shell:

• /bin/sh on Unix-like systems
• cmd.exe on Windows (when not using WSL)

Shell-specific features (like bash arrays or zsh plugins) may not work unless you explicitly invoke that shell in your command.

Example: bash -c 'your command here'

Output and Logging

Script output (stdout and stderr) is displayed in the T3 Code terminal. You can:

• View real-time output
• See exit codes
• Cancel running scripts

Best Practices

Use descriptive IDs

Choose IDs that clearly indicate what the script does:

✅ test, build, lint-fix
❌ s1, script2, x

Keep commands simple

If your command is complex, consider moving it to a shell script:

{
  "id": "deploy",
  "name": "Deploy to Staging",
  "command": "./scripts/deploy.sh staging",
  "icon": "play",
  "runOnWorktreeCreate": false
}

Use runOnWorktreeCreate wisely

Only enable auto-run for scripts that are:

• Fast (< 30 seconds)
• Idempotent (safe to run multiple times)
• Required for the worktree to function

Good candidates:

• npm install
• git submodule update

Bad candidates:

• Long-running dev servers
• Database migrations
• Deployment scripts

Test scripts before adding keybindings

Run scripts manually from the UI first to ensure they work correctly before binding them to shortcuts.

Use package.json scripts

Instead of duplicating commands, reference scripts defined in your package.json:

package.json

{
  "scripts": {
    "test:unit": "jest",
    "test:e2e": "playwright test",
    "test:all": "npm run test:unit && npm run test:e2e"
  }
}

T3 Code script

{
  "id": "test-all",
  "name": "Run All Tests",
  "command": "npm run test:all",
  "icon": "test",
  "runOnWorktreeCreate": false
}

Common Use Cases

Full Stack Project

[
  {
    "id": "install",
    "name": "Install Dependencies",
    "command": "npm install",
    "icon": "configure",
    "runOnWorktreeCreate": true
  },
  {
    "id": "dev",
    "name": "Start Dev Server",
    "command": "npm run dev",
    "icon": "play",
    "runOnWorktreeCreate": false
  },
  {
    "id": "test",
    "name": "Run Tests",
    "command": "npm test",
    "icon": "test",
    "runOnWorktreeCreate": false
  },
  {
    "id": "lint",
    "name": "Lint Code",
    "command": "npm run lint",
    "icon": "lint",
    "runOnWorktreeCreate": false
  },
  {
    "id": "build",
    "name": "Build Production",
    "command": "npm run build",
    "icon": "build",
    "runOnWorktreeCreate": false
  }
]

Python Data Science Project

[
  {
    "id": "setup",
    "name": "Setup Environment",
    "command": "python -m venv venv && source venv/bin/activate && pip install -r requirements.txt",
    "icon": "configure",
    "runOnWorktreeCreate": true
  },
  {
    "id": "test",
    "name": "Run Tests",
    "command": "pytest",
    "icon": "test",
    "runOnWorktreeCreate": false
  },
  {
    "id": "notebook",
    "name": "Start Jupyter",
    "command": "jupyter notebook",
    "icon": "play",
    "runOnWorktreeCreate": false
  },
  {
    "id": "lint",
    "name": "Lint with Black",
    "command": "black .",
    "icon": "lint",
    "runOnWorktreeCreate": false
  }
]

Rust Project

[
  {
    "id": "build",
    "name": "Build Debug",
    "command": "cargo build",
    "icon": "build",
    "runOnWorktreeCreate": false
  },
  {
    "id": "build-release",
    "name": "Build Release",
    "command": "cargo build --release",
    "icon": "build",
    "runOnWorktreeCreate": false
  },
  {
    "id": "test",
    "name": "Run Tests",
    "command": "cargo test --all",
    "icon": "test",
    "runOnWorktreeCreate": false
  },
  {
    "id": "lint",
    "name": "Run Clippy",
    "command": "cargo clippy --all-targets --all-features",
    "icon": "lint",
    "runOnWorktreeCreate": false
  },
  {
    "id": "format",
    "name": "Format Code",
    "command": "cargo fmt",
    "icon": "lint",
    "runOnWorktreeCreate": false
  }
]

Schema Reference

The ProjectScript type from the source code:

export const ProjectScript = Schema.Struct({
  id: TrimmedNonEmptyString,
  name: TrimmedNonEmptyString,
  command: TrimmedNonEmptyString,
  icon: ProjectScriptIcon, // 'play' | 'test' | 'lint' | 'configure' | 'build' | 'debug'
  runOnWorktreeCreate: Schema.Boolean,
});

Source: ~/workspace/source/packages/contracts/src/orchestration.ts:118-125

Troubleshooting

Script Not Found in Keybindings

If your keybinding command script.{id}.run isn’t working:

1. Verify the script ID matches exactly (case-sensitive)
2. Check that the script is saved in project settings
3. Ensure the ID follows naming rules (lowercase, alphanumeric, hyphens only)

Script Fails to Execute

If your script runs but fails:

1. Check the command: Test it manually in a terminal first
2. Verify working directory: Ensure paths are relative to workspace root
3. Check permissions: Scripts may need execute permissions
4. Review environment: Some tools require specific environment variables

Auto-run Scripts Not Running

If runOnWorktreeCreate scripts don’t execute:

1. Check server logs for errors
2. Verify the script command is valid
3. Ensure the worktree creation completed successfully

Limits and Constraints

Script ID length · 1-24 characters

Must match pattern: ^[a-z0-9][a-z0-9-]*$

Maximum scripts per project · No hard limit

However, performance may degrade with excessive scripts. Recommended: < 20 scripts.

Command length · No hard limit

Limited by your shell’s command length limit (typically 128KB+).

Related

Keybindings

Bind scripts to keyboard shortcuts

Server Options

Server configuration and CLI flags