Skip to main content

​
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
The desktop app is currently in Alpha. Check the releases page for the latest stable build.

​
First Launch

1

Open the Application

Launch T3 Code from your Applications folder or Start menu
2

Grant Permissions

Allow necessary permissions for file system access and terminal integration
3

Server Starts Automatically

The embedded server starts on localhost:8080 by default

​
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

Update Actions

Click the rocket icon in the sidebar header to:
  • Download available updates
  • Install downloaded updates (requires restart)
  • Check current version

​
System Integration

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

Click Browse

In the “Add project” dialog, click “Browse for folder”
2

Navigate

Use the native file dialog to find your project
3

Select

Choose the project root folder
4

Confirm

Project is added automatically

​
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
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: 
{
  "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: 
{
  "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

  • Download the .dmg file
  • Drag T3 Code to Applications folder
  • Right-click and “Open” on first launch (Gatekeeper)

​
Windows

  • Download the .exe installer
  • Run as Administrator if prompted
  • Choose installation directory
  • Creates Start Menu shortcut automatically

​
Linux

  • Download the .AppImage file
  • Make it executable: chmod +x T3-Code-*.AppImage
  • Run directly: ./T3-Code-*.AppImage

​
Performance Optimization

​
GPU Acceleration

By default, GPU acceleration is enabled. To disable (if experiencing rendering issues): macOS/Linux: 
T3_CODE_DISABLE_GPU=1 t3-code
Windows: 
$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

1

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/
2

Clear State

Rename the state directory to reset:
  • Renames existing to .old
  • Fresh start on next launch
3

Reinstall

Uninstall and reinstall the application

​
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

Auto-updates require network access and write permissions to the installation directory.
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: 
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

FeatureDesktop AppWeb 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

Build docs developers (and LLMs) love

Get started for freeTalk to us