Project Management Guide

Overview

Projects in T3 Code represent your codebases. Each project has a workspace root directory, default AI model, custom scripts, and associated threads (conversations). Effective project organization helps you manage multiple codebases and keep related work together.

Creating Projects

Click Add Project

At the bottom of the sidebar, click “Add project”

Enter Path

Type or paste the absolute path to your project directory

Browse (Desktop)

In the desktop app, click “Browse for folder” to use the native picker

Confirm

Press Enter or click “Add” to create the project

Auto-Bootstrap

When starting the server, automatically create a project for the current directory:

# Navigate to your project
cd ~/code/my-app

# Start server (auto-bootstrap enabled by default in web mode)
t3

# Explicitly enable
t3 --auto-bootstrap-project-from-cwd

# Disable
t3 --auto-bootstrap-project-from-cwd=false

The project is named after the directory and appears in the sidebar.

Via API

Programmatically create projects:

import { newProjectId, newCommandId } from '@t3tools/shared';

await api.orchestration.dispatchCommand({
  type: 'project.create',
  commandId: newCommandId(),
  projectId: newProjectId(),
  title: 'My App',
  workspaceRoot: '/Users/me/code/my-app',
  defaultModel: 'codex-gpt-4o',
  createdAt: new Date().toISOString(),
});

Project Structure

Properties

Each project has:

ID: Unique identifier (proj_...)
Title: Display name (defaults to directory name)
Workspace Root: Absolute path to project directory
Default Model: AI model for new threads (codex-gpt-4o, claude-sonnet-4, etc.)
Scripts: Custom commands for this project
Threads: Conversations associated with this project

Workspace Root

The workspace root is the project’s base directory:

AI can read/write files within this directory (and worktrees)
File paths in conversations are relative to this root
Git operations use this as the repository root
Terminal shells start in this directory

The workspace root should point to your repository root for best Git integration.

Managing Projects

Viewing Projects

Projects appear in the sidebar with:

Favicon: Auto-detected from project (Next.js, Vite, etc.)
Name: Project title
Thread List: Expandable list of conversations
New Thread Button: Quick action to start a conversation

Renaming Projects

Currently, project titles default to the directory name. To customize:

await api.orchestration.dispatchCommand({
  type: 'project.meta.update',
  commandId: newCommandId(),
  projectId: 'proj_abc123',
  title: 'My App (Production)',
});

Changing Default Model

Set the model for new threads in this project:

await api.orchestration.dispatchCommand({
  type: 'project.meta.update',
  commandId: newCommandId(),
  projectId: 'proj_abc123',
  defaultModel: 'claude-sonnet-4',
});

Existing threads keep their original model.

Deleting Projects

You must delete all threads in a project before deleting the project itself.

Delete All Threads

Right-click each thread and select “Delete”

Right-Click Project

Right-click the project name in the sidebar

Select Delete

Choose “Delete” from the context menu

Confirm

Confirm the deletion in the dialog

Deleting a project:

✅ Removes project from sidebar
✅ Deletes project metadata from database
❌ Does NOT delete files from disk
❌ Does NOT delete Git repositories

Project Scripts

Custom scripts are project-specific commands that run in the project’s context.

Creating Scripts

Scripts are managed via the project.meta.update orchestration command:

Define Script Configuration

Create a ProjectScript object with:

id: Unique identifier (1-24 chars, lowercase alphanumeric + hyphens)
name: Display name (e.g., “Run Tests”)
command: Shell command (e.g., npm test)
icon: Visual indicator (play, test, lint, build, debug, configure)
runOnWorktreeCreate: Auto-run when creating worktrees

Dispatch Update Command

Send a project.meta.update command with the updated scripts array

Example script configuration:

const script: ProjectScript = {
  id: 'script_run-tests',
  name: 'Run Tests',
  command: 'npm test',
  icon: 'test',
  runOnWorktreeCreate: true,
};

Script Context

Scripts run with:

Working directory: Project root or thread worktree
Environment: Inherits system PATH and variables
Terminal: Output shown in integrated terminal
Exit handling: Non-zero exits show error state

Keybindings

Assign keyboard shortcuts to scripts:

{
  "project-script:script_run-tests": "ctrl+shift+t",
  "project-script:script_run-build": "ctrl+shift+b"
}

Edit keybindings.json in your state directory.

Use Cases

name: "Run Tests"
command: "npm test"
icon: test
runOnWorktreeCreate: true

Auto-Run Scripts

Scripts with runOnWorktreeCreate: true execute automatically when creating a worktree for a thread. This is useful for:

Installing dependencies
Running builds
Setting up database schemas
Generating types

The script runs in a background terminal and you can monitor progress.

Threads and Projects

Creating Threads

Start a new conversation in a project:

Default (Local)
Worktree Mode

Creates a thread that works in the project’s workspace root:

// Keybinding: varies by platform
// Button: Pen icon next to project

Creates a thread with an isolated Git worktree:

// Keybinding: varies by platform  
// Manual: Set thread envMode to 'worktree'

Thread Organization

Threads are listed under their project:

Most recent first: Sorted by creation date
Status indicators: Working, completed, approval pending
Relative timestamps: “5m ago”, “2h ago”, “3d ago”
PR badges: If thread has an open/merged pull request

Thread Lifecycle

Create

New thread appears at the top of the project’s list

Conversation

Back-and-forth with AI, making changes

Complete

Thread shows green “Completed” badge when done

Multi-Project Workflows

Monorepo Setup

For monorepos, create one project per package:

# Main project
Project: my-monorepo
Root: ~/code/my-monorepo

# Sub-projects (optional)
Project: my-monorepo/web
Root: ~/code/my-monorepo/apps/web

Project: my-monorepo/api  
Root: ~/code/my-monorepo/apps/api

This lets you:

Scope AI context to specific packages
Use different models for different concerns
Organize threads by component

Frontend + Backend

Separate projects for client and server:

Project: MyApp Frontend
Root: ~/code/myapp-web
Model: codex-gpt-4o

Project: MyApp Backend
Root: ~/code/myapp-api  
Model: codex-o1-preview

Benefits:

Clearer thread organization
Tailored AI models
Independent Git workflows

Client Projects

Organize by client or engagement:

Project: Acme Corp - Dashboard
Project: Acme Corp - API
Project: TechStart - Mobile App
Project: Personal - Blog

Best Practices

Project Organization Tips

One repo, one project: Keep projects aligned with repositories
Clear naming: Use descriptive titles for easy identification
Clean up regularly: Delete completed threads to reduce clutter
Use scripts: Automate common tasks with project scripts
Model selection: Choose models based on project complexity

Model Selection Guide

Codex GPT-4o: Fast, general-purpose, cost-effective
Codex o1: Complex reasoning, architecture decisions
Codex o1-mini: Faster reasoning, simpler problems
Claude Sonnet: Large context, long conversations
Claude Opus: Maximum capability, critical work

When to Create New Projects

Create a new project when: ✅ Starting a new codebase ✅ Working in a different repository ✅ Needing different default settings ✅ Organizing by client or product ❌ Don’t create new projects for:

Different features in same repo
Temporary experiments (use threads)
Different branches (use worktrees)

Troubleshooting

Project Not Appearing

If a project doesn’t show in the sidebar:

Check the path is correct and accessible
Verify you have read/write permissions
Look for errors in the server logs
Try refreshing the page

AI Can’t Find Files

If the AI reports missing files:

Confirm files exist in workspace root
Check file paths are relative to workspace root
Verify permissions allow AI to read files
Try absolute paths as a workaround

Scripts Not Running

If project scripts fail:

Check command syntax is correct
Verify required tools are in PATH
Look at terminal output for errors
Test command manually in terminal

Next Steps

Master Git Workflow for version control integration
Learn CLI Usage for advanced configuration
Explore Web Interface for daily use

Get Started

Core Concepts

Usage Guides

Configuration

Development

​Overview

​Creating Projects

​From the Sidebar

​Auto-Bootstrap

​Via API

​Project Structure

​Properties

​Workspace Root

​Managing Projects

​Viewing Projects

​Renaming Projects

​Changing Default Model

​Deleting Projects

​Project Scripts

​Creating Scripts

​Script Context

​Keybindings

​Use Cases

​Auto-Run Scripts

​Threads and Projects

​Creating Threads

​Thread Organization

​Thread Lifecycle

​Multi-Project Workflows

​Monorepo Setup

​Frontend + Backend

​Client Projects

​Best Practices

Project Organization Tips

​Model Selection Guide

​When to Create New Projects

​Troubleshooting

​Project Not Appearing

​AI Can’t Find Files

​Scripts Not Running

​Next Steps

Build docs developers (and LLMs) love

Overview

Creating Projects

From the Sidebar

Auto-Bootstrap

Via API

Project Structure

Properties

Workspace Root

Managing Projects

Viewing Projects

Renaming Projects

Changing Default Model

Deleting Projects

Project Scripts

Creating Scripts

Script Context

Keybindings

Use Cases

Auto-Run Scripts

Threads and Projects

Creating Threads

Thread Organization

Thread Lifecycle

Multi-Project Workflows

Monorepo Setup

Frontend + Backend

Client Projects

Best Practices

Model Selection Guide

When to Create New Projects

Troubleshooting

Project Not Appearing

AI Can’t Find Files

Scripts Not Running

Next Steps