CaudexCaudex

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

macOSWindows/LinuxAction
⌘BCtrl+BToggle Panel
⌘JCtrl+JToggle Claude/Git Panel
⌘⇧GCtrl+Shift+GToggle Diff View
⌘,Ctrl+,Open Settings
⌘FCtrl+FSession Search
⌘⇧CCtrl+Shift+CCompact Context
⌘MCtrl+MOpen Memory (CLAUDE.md)
⌘⇧DCtrl+Shift+DRun Doctor
ESCESCClose / Go Back

Tab Operations

macOSWindows/LinuxAction
⌘TCtrl+TNew Tab
⌘WCtrl+WClose Tab
⌘1-9Ctrl+1-9Switch to Tab #
⌘⌥←/→Ctrl+Alt+←/→Previous / Next Tab
⌘⇧[/]Ctrl+Shift+[/]Previous / Next Tab (Alt)
⌘⇧ACtrl+Shift+ATab Overview

Split Operations

macOSWindows/LinuxAction
⌘DCtrl+DAdd Terminal Split
⌘\Ctrl+\Toggle Split Layout
⌘⌥↑Ctrl+Alt+↑Previous Split
⌘⌥↓Ctrl+Alt+↓Next Split

File Operations

macOSWindows/LinuxAction
⌘⇧ICtrl+Shift+ISelect Image File
⌘⇧SCtrl+Shift+SScreen Capture

Navigation

macOSWindows/LinuxAction
⌘[Ctrl+[Navigate Back

Terminal

macOSWindows/LinuxAction
⇧EnterShift+EnterInsert 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.

LightDarkSystem

Font Settings

Customize the terminal font family and size for optimal readability.

Font familyFont size

Panel Defaults

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

Auto-open panelDefault panel tab

Terminal Settings

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

Cursor styleScrollback linesBell

Notifications

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

Push notificationsSound 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)

Once enabled, the server starts on 127.0.0.1 and displays the port and access token.

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:

ngrok config add-authtoken YOUR_NGROK_TOKEN

Start the tunnel

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

ngrok http PORT

# Example: if Caudex is on port 8080

ngrok http 8080

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

Quick-access buttons above the keyboard

Git Integration

Commit, push, and view diffs on mobile

PWA Support

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

ServiceBest forCommand
ngrokQuick setup, temporary accessngrok http PORT
TailscalePersonal devices, always-on VPNtailscale funnel PORT
Cloudflare TunnelPermanent setup, custom domaincloudflared 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

Used for: Sidebar updates (Sessions, Todos), tab status sync (working/waiting/finishing indicators)

2. StatusLine Configuration

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

ScenarioBehavior
statusLine not setCaudex adds its configuration
statusLine already setChains via pipe (preserves your command)

// If you have an existing statusLine:

"command": "your-script.sh"

// Caudex automatically changes to:

"command": "tee ~/.caudex/status-data.json | your-script.sh"

Used for: Header display (Context %, Cost, Model, Tokens)

3. Automatic Backup

Before modifying settings, Caudex creates a backup:

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

4. Data Storage Locations

PathContents
~/.caudex/config.jsonApp settings
~/.caudex/status-data.jsonLatest 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:

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