Project Management Guide

Organize your codebases and conversations with T3 Code’s project system

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

From the Sidebar

1. Click Add Project

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

2. Enter Path

   Type or paste the absolute path to your project directory

3. Browse (Desktop)

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

4. 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.

1. Delete All Threads

   Right-click each thread and select “Delete”

2. Right-Click Project

   Right-click the project name in the sidebar

3. Select Delete

   Choose “Delete” from the context menu

4. 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:

1. 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
2. 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

Test Runner

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)

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

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

Worktree Mode

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

1. Create

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

2. Conversation

   Back-and-forth with AI, making changes

3. Complete

   Thread shows green “Completed” badge when done

4. Archive

   Delete old threads to keep the list clean

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:

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

AI Can’t Find Files

If the AI reports missing files:

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

Scripts Not Running

If project scripts fail:

1. Check command syntax is correct
2. Verify required tools are in PATH
3. Look at terminal output for errors
4. 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