> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Click Add Project">
    At the bottom of the sidebar, click "Add project"
  </Step>

  <Step title="Enter Path">
    Type or paste the absolute path to your project directory
  </Step>

  <Step title="Browse (Desktop)">
    In the desktop app, click "Browse for folder" to use the native picker
  </Step>

  <Step title="Confirm">
    Press Enter or click "Add" to create the project
  </Step>
</Steps>

### Auto-Bootstrap

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

```bash theme={null}
# 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:

```typescript theme={null}
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

<Note>
  The workspace root should point to your repository root for best Git integration.
</Note>

## 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:

```typescript theme={null}
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:

```typescript theme={null}
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

<Warning>
  You must delete all threads in a project before deleting the project itself.
</Warning>

<Steps>
  <Step title="Delete All Threads">
    Right-click each thread and select "Delete"
  </Step>

  <Step title="Right-Click Project">
    Right-click the project name in the sidebar
  </Step>

  <Step title="Select Delete">
    Choose "Delete" from the context menu
  </Step>

  <Step title="Confirm">
    Confirm the deletion in the dialog
  </Step>
</Steps>

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:

<Steps>
  <Step title="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
  </Step>

  <Step title="Dispatch Update Command">
    Send a `project.meta.update` command with the updated scripts array
  </Step>
</Steps>

Example script configuration:

```typescript theme={null}
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:

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Test Runner theme={null}
  name: "Run Tests"
  command: "npm test"
  icon: test
  runOnWorktreeCreate: true
  ```

  ```bash Linter theme={null}
  name: "Lint Code"
  command: "npm run lint -- --fix"
  icon: lint
  runOnWorktreeCreate: false
  ```

  ```bash Build theme={null}
  name: "Build Project"
  command: "npm run build"
  icon: build  
  runOnWorktreeCreate: true
  ```

  ```bash Dev Server theme={null}
  name: "Start Dev Server"
  command: "npm run dev"
  icon: play
  runOnWorktreeCreate: false
  ```
</CodeGroup>

### 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:

<Tabs>
  <Tab title="Default (Local)">
    Creates a thread that works in the project's workspace root:

    ```typescript theme={null}
    // Keybinding: varies by platform
    // Button: Pen icon next to project
    ```
  </Tab>

  <Tab title="Worktree Mode">
    Creates a thread with an isolated Git worktree:

    ```typescript theme={null}
    // Keybinding: varies by platform  
    // Manual: Set thread envMode to 'worktree'
    ```
  </Tab>
</Tabs>

### 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

<Steps>
  <Step title="Create">
    New thread appears at the top of the project's list
  </Step>

  <Step title="Conversation">
    Back-and-forth with AI, making changes
  </Step>

  <Step title="Complete">
    Thread shows green "Completed" badge when done
  </Step>

  <Step title="Archive">
    Delete old threads to keep the list clean
  </Step>
</Steps>

## Multi-Project Workflows

### Monorepo Setup

For monorepos, create one project per package:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
Project: Acme Corp - Dashboard
Project: Acme Corp - API
Project: TechStart - Mobile App
Project: Personal - Blog
```

## Best Practices

<Card title="Project Organization Tips" icon="lightbulb">
  * **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
</Card>

### 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](/guides/git-workflow) for version control integration
* Learn [CLI Usage](/guides/cli-usage) for advanced configuration
* Explore [Web Interface](/guides/web-interface) for daily use