# Documentation

## Getting Started

### Installation

Caudex is available for macOS, Windows, and Linux. Download the appropriate version for your platform.

macOS

- Apple Silicon (.dmg)
- Intel (.dmg)

Windows

- .exe installer
- .msi installer

Linux

- .deb (Debian/Ubuntu)
- .rpm (Fedora/RHEL)
- .AppImage

### First Launch

1. Open Caudex after installation
2. Make sure `claude` CLI is installed and available in your PATH
3. Caudex will automatically detect Claude Code and start a new session
4. Use ⌘B (Ctrl+B) to toggle the information panel

#### Prerequisites

Caudex requires Claude Code CLI to be installed. Visit [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) to install the CLI first.

## Features

### Multi-Tab Management

Manage multiple projects simultaneously. Each tab maintains its own Claude Code session, allowing you to switch between different projects seamlessly. Use ⌘1-9 (Ctrl+1-9 on Windows/Linux) to quickly jump between tabs.

#### Tips

- Double-click a tab to rename it
- Right-click for tab options menu
- Drag tabs to reorder them

### Tab Overview

Get a bird's eye view of all your sessions with Tab Overview (⌘⇧A). See status indicators for each session, quickly identify active or waiting sessions, and jump to any project with a single click.

#### Tips

- Press ⌘⇧A to open Tab Overview
- Click any card to switch to that tab
- View session status at a glance

### Session Search

Quickly find any session across all projects with Session Search (⌘F). Search through your conversation history and jump directly to the session you need.

#### Tips

- Press ⌘F to open Session Search
- Search by conversation content
- Custom tab names appear in results

### Context Monitoring

Monitor your context usage and estimated costs in real-time. The progress bar shows how much of the context window you've used, helping you manage long sessions effectively.

#### Tips

- Watch the progress bar for context usage
- Use /compact when context is high
- Clear conversation to reset context

### Information Panel

Access essential information through the sidebar panel (⌘B). View and manage Sessions, Working Directories, Git status, MCP servers, Skills, Agents, Hooks, and Permissions all in one place.

**Sessions**

Browse and resume past sessions

**Dirs**

Manage working directories

**Git**

View repository status and history

**MCP**

Manage MCP server connections

**Skills**

View installed skills

**Agents**

Monitor running agents

**Hooks**

Configure automation hooks

**Permissions**

Manage tool permissions

### Multi-Split Terminal

Split your terminal (⌘D) and toggle between horizontal/vertical layouts (⌘\) to run multiple sessions side by side. Perfect for running Claude Code alongside shell commands or comparing different approaches.

#### Tips

- ⌘D to add a split
- ⌘\ to toggle layout (horizontal/vertical)
- ⌘⌥↑/↓ to switch between splits
- Drag dividers to resize

### Quick Actions

Access commonly used functions with one click through the Quick Actions bar. Compact your conversation, clear the terminal, edit memory, copy conversation, or capture screenshots.

- Compact
- Clear
- Memory
- Copy
- File
- Image
- Screenshot

### Skills Management

Browse, install, and manage Claude Code skills through a visual interface. Skills extend Claude Code's capabilities with specialized commands and workflows.

#### Tips

- Browse available skills in the Skills tab
- Click to install or remove skills
- View skill documentation inline

### MCP Server Management

Connect and configure Model Context Protocol (MCP) servers with ease. MCP servers provide Claude Code with additional tools and capabilities like database access, API integrations, and more.

#### Tips

- View connected servers in the MCP tab
- Click to enable/disable servers
- Monitor server status in real-time

### Git Integration

View your repository status at a glance with the built-in Git panel. Monitor current branch, ahead/behind status, file changes, recent commits, and manage Git worktrees without leaving the app.

#### Tips

- View staged, unstaged, and untracked files
- Color-coded file status indicators
- Browse local and remote branches
- Visual commit graph showing branch relationships
- Manage Git worktrees - create, view, and delete worktrees
- Git Diff Viewer - View file changes with syntax highlighting
- Commit directly from GitView with the commit modal
- Open files in external editor (⌘+Click or icon)
- Auto-refreshes when repository changes

## Keyboard Shortcuts

Caudex supports comprehensive keyboard shortcuts for efficient navigation.

### Basic Operations

| macOS | Windows/Linux | Action |
| --- | --- | --- |
| `⌘B` | `Ctrl+B` | Toggle Panel |
| `⌘J` | `Ctrl+J` | Toggle Claude/Git Panel |
| `⌘⇧G` | `Ctrl+Shift+G` | Toggle Diff View |
| `⌘,` | `Ctrl+,` | Open Settings |
| `⌘F` | `Ctrl+F` | Session Search |
| `⌘⇧C` | `Ctrl+Shift+C` | Compact Context |
| `⌘M` | `Ctrl+M` | Open Memory (CLAUDE.md) |
| `⌘⇧D` | `Ctrl+Shift+D` | Run Doctor |
| `ESC` | `ESC` | Close / Go Back |

### Tab Operations

| macOS | Windows/Linux | Action |
| --- | --- | --- |
| `⌘T` | `Ctrl+T` | New Tab |
| `⌘W` | `Ctrl+W` | Close Tab |
| `⌘1-9` | `Ctrl+1-9` | Switch to Tab # |
| `⌘⌥←/→` | `Ctrl+Alt+←/→` | Previous / Next Tab |
| `⌘⇧[/]` | `Ctrl+Shift+[/]` | Previous / Next Tab (Alt) |
| `⌘⇧A` | `Ctrl+Shift+A` | Tab Overview |

### Split Operations

| macOS | Windows/Linux | Action |
| --- | --- | --- |
| `⌘D` | `Ctrl+D` | Add Terminal Split |
| `⌘\` | `Ctrl+\` | Toggle Split Layout |
| `⌘⌥↑` | `Ctrl+Alt+↑` | Previous Split |
| `⌘⌥↓` | `Ctrl+Alt+↓` | Next Split |

### File Operations

| macOS | Windows/Linux | Action |
| --- | --- | --- |
| `⌘⇧I` | `Ctrl+Shift+I` | Select Image File |
| `⌘⇧S` | `Ctrl+Shift+S` | Screen Capture |

### Navigation

| macOS | Windows/Linux | Action |
| --- | --- | --- |
| `⌘[` | `Ctrl[` | Navigate Back |

### Terminal

| macOS | Windows/Linux | Action |
| --- | --- | --- |
| `⇧Enter` | `Shift+Enter` | Insert New Line |

#### Windows / Linux

Replace `⌘` with `Ctrl` and `⌥` with `Alt`

## Configuration

Access settings with ⌘, (Ctrl+, on Windows/Linux) to customize Caudex to your preferences.

### Theme

Choose between Light, Dark, or System themes. System theme automatically matches your operating system's appearance setting.

**Options:**
- Light
- Dark
- System

### Font Settings

Customize the terminal font family and size for optimal readability.

**Settings:**
- Font family
- Font size

### Panel Defaults

Configure whether the information panel opens by default when starting a new session.

**Options:**
- Auto-open panel
- Default panel tab

### Terminal Settings

Adjust terminal behavior including cursor style, scrollback buffer, and bell notifications.

**Settings:**
- Cursor style
- Scrollback lines
- Bell

### Notifications

Get notified when Claude Code completes a task or needs your input. Choose between push notifications and sound alerts.

**Options:**
- Push notifications
- Sound alerts

## Remote Access

Remote Access lets you use Caudex from any device — phone, tablet, or another computer — via a WebSocket server running on your machine. Combined with a tunnel service like ngrok, you can access your full development environment from anywhere.

#### Beta Feature

Remote Access is currently in beta. It supports a single concurrent remote connection.

### 1. Enable Remote Access

1. Open Settings (`⌘,`)
2. Go to the **Remote Access** tab
3. Toggle **Enable Remote Access** on
4. Optionally set a fixed port (default: auto-assign)

### 2. Access from the Same Machine

Open the displayed URL in your browser to access Caudex remotely on the same machine:

`http://127.0.0.1:PORT?token=YOUR_TOKEN`

### 3. Access from Outside (ngrok)

The server only listens on localhost, so to access from another device you need a tunnel. **ngrok** is the easiest option.

#### Install ngrok

```bash
# macOS (Homebrew)
brew install ngrok
# or download from https://ngrok.com
```

#### Sign up & authenticate

Create a free account at [ngrok.com](https://ngrok.com/), then add your authtoken:

```bash
grok config add-authtoken YOUR_NGROK_TOKEN
```

#### Start the tunnel

Point ngrok to the port shown in Caudex's Remote Access settings:

```bash
grok http PORT
```

### Open from your phone / tablet

ngrok will display a public URL. Open it in your mobile browser with the token:

`https://xxxx-xx-xx-xx-xx.ngrok-free.app?token=YOUR_TOKEN`

### Mobile Features

The remote interface is optimized for touch devices:

- Responsive Tabs
- Swipe-friendly tab navigation
- Shortcut Bar for quick-access buttons above the keyboard
- Git Integration to commit, push, and view diffs on mobile
- PWA Support to add to home screen for app-like experience

### Security

- The server binds to `127.0.0.1` only — never exposed directly to the network
- Token-based authentication is required for every connection
- Only one remote connection is allowed at a time
- ngrok provides HTTPS/WSS encryption automatically

#### Keep your token secret

Anyone with your ngrok URL and access token can control your Caudex session. Do not share the token publicly. Stop the ngrok tunnel when you're done.

### Alternative Tunnel Services

| Service | Best for | Command |
| --- | --- | --- |
| ngrok | Quick setup, temporary access | ngrok http PORT |
| Tailscale | Personal devices, always-on VPN | tailscale funnel PORT |
| Cloudflare Tunnel | Permanent setup, custom domain | cloudflared tunnel --url localhost:PORT |

## Configuration Notes

#### Overview

Caudex automatically modifies `~/.claude/settings.json` on first launch to enable full functionality. Your existing settings are preserved.

### 1. Hooks Configuration

Caudex adds hooks to the following events:
- SessionStart
- SessionEnd
- Stop
- Notification
- PermissionRequest
- UserPromptSubmit

#### Impact on existing settings

- Existing hooks are preserved
- Caudex hooks are added alongside your existing ones
- No settings are overwritten

### 2. StatusLine Configuration

Caudex configures the statusLine to receive real-time data from Claude Code.

### 3. Automatic Backup

Before modifying settings, Caudex creates a backup:

`~/.claude/settings.json.caudex-backup`

### 4. Data Storage Locations

| Path | Contents |
| --- | --- |
| `~/.caudex/config.json` | App settings |
| `~/.caudex/status-data.json` | Latest StatusLine data |
| `~/.caudex/sessions/` | Status cache per session |
| `~/.caudex/hooks/` | Hook scripts |

### 5. Uninstalling

To completely remove Caudex:
1. Manually remove Caudex-related entries from `~/.claude/settings.json`
2. Delete the `~/.caudex/` folder

Or restore from backup:
```bash
cp ~/.claude/settings.json.caudex-backup ~/.claude/settings.json
rm -rf ~/.caudex/
```

### 6. Important Notes

- Recommended to launch Caudex when Claude Code is not running (for first launch)
- Claude Code may need to be restarted after settings changes
- When multiple Claude Code sessions are running, StatusLine shows data from the most recently active session