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

Tab Operations

Split Operations

File Operations

Navigation

Terminal

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

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

Sign up & authenticate

Create a free account at ngrok.com, then add your authtoken:

grok config add-authtoken YOUR_NGROK_TOKEN

Start the tunnel

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

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

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

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:

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