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

# Desktop App Guide

> Install and use the T3 Code desktop application for native performance and system integration

## Overview

The T3 Code desktop application provides a native experience with deep system integration, auto-updates, and optimized performance. Built with Electron, it offers the same web interface with additional native capabilities.

## Installation

### Download

Download the latest version for your platform:

* **macOS**: `.dmg` installer
* **Windows**: `.exe` installer
* **Linux**: `.AppImage` or `.deb`

<Note>
  The desktop app is currently in Alpha. Check the releases page for the latest stable build.
</Note>

### First Launch

<Steps>
  <Step title="Open the Application">
    Launch T3 Code from your Applications folder or Start menu
  </Step>

  <Step title="Grant Permissions">
    Allow necessary permissions for file system access and terminal integration
  </Step>

  <Step title="Server Starts Automatically">
    The embedded server starts on `localhost:8080` by default
  </Step>
</Steps>

## Desktop-Specific Features

### Auto-Updates

The desktop app checks for updates automatically:

* **Available**: Amber rocket icon pulses in sidebar
* **Downloading**: Blue icon with progress
* **Ready**: Green icon - click to install

<Card title="Update Actions" icon="rocket">
  Click the rocket icon in the sidebar header to:

  * Download available updates
  * Install downloaded updates (requires restart)
  * Check current version
</Card>

### System Integration

#### Menu Bar

Native application menu provides:

* File operations (New Project, New Thread)
* Edit actions (Copy, Paste, Select All)
* View controls (Toggle Sidebar, Toggle Terminal)
* Window management
* Help and documentation links

#### Keyboard Shortcuts

Platform-native shortcuts work throughout the app:

**macOS**:

* `Cmd+N` - New thread in current project
* `Cmd+Shift+N` - New thread (worktree mode)
* `Cmd+T` - Toggle terminal
* `Cmd+D` - Toggle diff panel

**Windows/Linux**:

* `Ctrl+N` - New thread in current project
* `Ctrl+Shift+N` - New thread (worktree mode)
* `Ctrl+T` - Toggle terminal
* `Ctrl+D` - Toggle diff panel

### Context Menus

Right-click for native context menus:

* **Project context menu**: Delete project, copy path
* **Thread context menu**: Rename, mark unread, copy ID, delete
* **Editor context menu**: Standard text operations

### File System Access

#### Project Folder Picker

Click "Browse for folder" when adding a project to use the native file picker:

<Steps>
  <Step title="Click Browse">
    In the "Add project" dialog, click "Browse for folder"
  </Step>

  <Step title="Navigate">
    Use the native file dialog to find your project
  </Step>

  <Step title="Select">
    Choose the project root folder
  </Step>

  <Step title="Confirm">
    Project is added automatically
  </Step>
</Steps>

#### Drag and Drop

Drag folders directly onto the app window:

* Drop on sidebar to add as new project
* Drop on composer to reference files

### Terminal Integration

The embedded terminal has full native capabilities:

* **Shell**: Uses your system default shell (bash, zsh, PowerShell)
* **Environment**: Inherits PATH and environment variables
* **Persistence**: Terminal state persists between sessions
* **Multiple terminals**: Split and create new terminal instances

### External Links

Links open in your default browser:

* PR links from GitHub
* Documentation references
* Error messages with URLs

## Configuration

### Server Settings

The desktop app runs the server in "desktop" mode by default:

```json theme={null}
{
  "mode": "desktop",
  "host": "127.0.0.1",
  "port": 8080,
  "noBrowser": true
}
```

These settings ensure:

* Server binds to localhost only (security)
* No external browser is launched
* Port conflicts are handled automatically

### State Directory

Application data is stored in platform-specific locations:

**macOS**:

```
~/Library/Application Support/T3 Code (Alpha)/
```

**Windows**:

```
%APPDATA%\T3 Code (Alpha)\
```

**Linux**:

```
~/.config/T3 Code (Alpha)/
```

Contains:

* SQLite database (threads, messages, projects)
* Keybindings configuration
* Application preferences
* Update cache

### Custom Keybindings

Edit `keybindings.json` in your state directory:

```json theme={null}
{
  "chat.new": "ctrl+n",
  "chat.newLocal": "ctrl+shift+n",
  "terminal.toggle": "ctrl+t",
  "diff.toggle": "ctrl+d"
}
```

Restart the app to apply changes.

## Platform-Specific Notes

### macOS

<Tabs>
  <Tab title="Installation">
    * Download the `.dmg` file
    * Drag T3 Code to Applications folder
    * Right-click and "Open" on first launch (Gatekeeper)
  </Tab>

  <Tab title="Permissions">
    Grant permissions in System Preferences:

    * Full Disk Access (for project file access)
    * Accessibility (for keyboard shortcuts)
  </Tab>

  <Tab title="Codesigning">
    The app is codesigned with an Apple Developer certificate. If you see a warning, go to System Preferences → Security & Privacy and click "Open Anyway".
  </Tab>
</Tabs>

### Windows

<Tabs>
  <Tab title="Installation">
    * Download the `.exe` installer
    * Run as Administrator if prompted
    * Choose installation directory
    * Creates Start Menu shortcut automatically
  </Tab>

  <Tab title="SmartScreen">
    If Windows Defender SmartScreen blocks the app:

    * Click "More info"
    * Click "Run anyway"
  </Tab>

  <Tab title="Antivirus">
    Some antivirus software may flag Electron apps. Add T3 Code to your exclusions list if needed.
  </Tab>
</Tabs>

### Linux

<Tabs>
  <Tab title="AppImage">
    * Download the `.AppImage` file
    * Make it executable: `chmod +x T3-Code-*.AppImage`
    * Run directly: `./T3-Code-*.AppImage`
  </Tab>

  <Tab title="Debian Package">
    * Download the `.deb` file
    * Install: `sudo dpkg -i t3-code_*.deb`
    * Launch: `t3-code` from terminal or app launcher
  </Tab>

  <Tab title="Dependencies">
    Ensure you have required libraries:

    * libgtk-3-0
    * libnotify4
    * libnss3
    * libxss1
  </Tab>
</Tabs>

## Performance Optimization

### GPU Acceleration

By default, GPU acceleration is enabled. To disable (if experiencing rendering issues):

**macOS/Linux**:

```bash theme={null}
T3_CODE_DISABLE_GPU=1 t3-code
```

**Windows**:

```powershell theme={null}
$env:T3_CODE_DISABLE_GPU="1"; Start-Process t3-code
```

### Memory Usage

The app typically uses 200-400MB of RAM. If memory usage grows:

1. Close unused threads
2. Clear diff panel
3. Restart the application

### Disk Space

The state directory grows with conversation history:

* Database: \~10MB per 100 threads
* Checkpoints: Varies by project size
* Update cache: \~200MB temporarily during updates

Clean up by deleting old threads or clearing the database.

## Troubleshooting

### App Won't Start

<Steps>
  <Step title="Check Logs">
    Look for crash reports in:

    * macOS: `~/Library/Logs/T3 Code (Alpha)/`
    * Windows: `%APPDATA%\T3 Code (Alpha)\logs\`
    * Linux: `~/.config/T3 Code (Alpha)/logs/`
  </Step>

  <Step title="Clear State">
    Rename the state directory to reset:

    * Renames existing to `.old`
    * Fresh start on next launch
  </Step>

  <Step title="Reinstall">
    Uninstall and reinstall the application
  </Step>
</Steps>

### Server Connection Failed

If the UI shows "Connection failed":

1. Check if another process is using port 8080
2. Verify Codex is installed and in PATH
3. Look at server logs in the state directory
4. Restart the application

### Updates Not Working

<Warning>
  Auto-updates require network access and write permissions to the installation directory.
</Warning>

If updates fail:

1. Check internet connectivity
2. Verify no firewall blocks
3. Download and install manually
4. Check file system permissions

### Terminal Not Working

If the integrated terminal doesn't open:

1. Verify shell is available in PATH
2. Check terminal permissions
3. Try different shell (Settings → Terminal)
4. Restart application

## Development Mode

Run the desktop app in development:

```bash theme={null}
cd apps/desktop
bun run dev
```

This launches:

* Electron in development mode
* Hot-reload enabled
* DevTools open by default
* Server in development mode

## Comparison: Desktop vs Web

| Feature          | Desktop App | Web Interface |
| ---------------- | ----------- | ------------- |
| Auto-updates     | ✅ Yes       | ❌ Manual      |
| Native menus     | ✅ Yes       | ❌ No          |
| File picker      | ✅ Native    | 🔶 Text input |
| Shortcuts        | ✅ System    | 🔶 Browser    |
| Offline          | 🔶 Partial  | ❌ No          |
| Install required | ✅ Yes       | ❌ No          |
| Cross-device     | ❌ No        | ✅ Yes         |

## Next Steps

* Configure advanced features in [CLI Usage](/guides/cli-usage)
* Organize work with [Project Management](/guides/project-management)
* Master version control in [Git Workflow](/guides/git-workflow)