Getting Started

Cocxy Terminal is a native macOS terminal built for AI agent workflows. Zero telemetry, GPU-accelerated rendering, and first-class support for Claude Code, Codex, Gemini CLI, Aider, and more.

System Requirements

• macOS 14.0 (Sonoma) or later
• Apple Silicon or Intel Mac
• ~60 MB disk space

Install via Homebrew (recommended)

brew tap salp2403/tap && brew install --cask cocxy

To update later:

brew update && brew upgrade --cask cocxy

Install via DMG

1. Download the latest DMG from GitHub Releases
2. Open the DMG and drag Cocxy Terminal to /Applications
3. Launch from Spotlight or Launchpad

First Launch

On first launch, Cocxy creates its configuration directory at ~/.config/cocxy/ with sensible defaults. A welcome overlay introduces the key features. You can dismiss it with Esc and bring it back from the Help menu.

Concepts

Workspaces

The vertical sidebar on the left is your workspace. Each entry is a tab with its own terminal session. Tabs show the current directory, git branch, and agent state in real time.

Agent Detection

Cocxy automatically detects AI agents running in your terminal. When you launch claude, codex, aider, or gemini, the tab indicator changes to show the agent's state: launching, working, waiting for input, finished, or error.

Splits

Any tab can be split horizontally or vertically to show multiple terminal sessions or panels (browser, markdown preview) side by side.

Zero Telemetry

Cocxy never sends data to external servers. No analytics, no crash reporting, no tracking of any kind. Your terminal sessions stay on your machine.

Configuration

Cocxy is configured via TOML files in ~/.config/cocxy/. Changes are detected automatically within one second.

config.toml

# ~/.config/cocxy/config.toml

[general]
shell = "/bin/zsh"
working-directory = "~"
confirm-close-process = true

[appearance]
theme = "catppuccin-mocha"
font-family = "JetBrainsMono Nerd Font"
font-size = 14.0
tab-position = "left"            # "left", "top", "hidden"
window-padding = 8.0
background-opacity = 1.0         # 0.1 - 1.0
background-blur-radius = 0.0     # 0 - 100

[terminal]
scrollback-lines = 10000
cursor-style = "bar"             # "block", "bar", "underline"
cursor-blink = true
copy-on-select = true
clipboard-paste-protection = true

[agent-detection]
enabled = true
osc-notifications = true
pattern-matching = true
timing-heuristics = true
idle-timeout-seconds = 5

[notifications]
macos-notifications = true
sound = true
badge-on-tab = true
show-dock-badge = true

[quick-terminal]
enabled = true
hotkey = "cmd+grave"
position = "top"                 # "top", "bottom", "left", "right"
height-percentage = 40
hide-on-deactivate = true

[keybindings]
new-tab = "cmd+t"
close-tab = "cmd+w"
next-tab = "cmd+shift+]"
prev-tab = "cmd+shift+["
split-vertical = "cmd+d"
split-horizontal = "cmd+shift+d"
goto-attention = "cmd+shift+u"

[sessions]
auto-save = true
auto-save-interval = 30
restore-on-launch = true

Keyboard Shortcuts

Tabs

Splits

Panels & Overlays

Terminal

Agent Detection

Cocxy uses a 4-layer detection engine to identify AI agents running in your terminal. Each layer cross-validates with the others for high-confidence results:

1. Hook Events (highest priority) — Claude Code hook integration streams 12 event types in real time: tool calls, responses, session lifecycle.
2. OSC Sequences — Shell integration markers (OSC 133, OSC 7, OSC 99) for working directory and prompt detection.
3. Pattern Matching — Regex patterns matched against terminal output to detect agent launch commands and prompts.
4. Timing Heuristics (fallback) — Detects idle timeouts and sustained output patterns when the other layers don't match.

Agent States

Claude Code

Claude Code has first-class integration via hooks. Cocxy receives real-time events (session start/end, tool use, errors) for accurate state tracking. The tab sidebar shows the current tool being used (e.g., "Read: main.swift").

Detection patterns: ^claude\b, ^claude-code\b, npx claude

Codex CLI

Detection patterns: ^codex\b

Aider

Aider has a longer idle timeout (10s) because it takes longer to respond.

Detection patterns: ^aider\b, ^python.*aider

Gemini CLI

Gemini CLI has an 8-second idle timeout for slower initial responses.

Detection patterns: ^gemini\b

Custom Agents

Add your own agents by editing ~/.config/cocxy/agents.toml:

[my-agent]
display-name = "My Agent"
osc-supported = false
launch-patterns = ['^my-agent\b']
waiting-patterns = ['^> ']
error-patterns = ['Error:']
finished-indicators = ['^\$\s*$']
idle-timeout-override = 8

Browser

Cocxy includes a built-in browser panel for viewing dev servers, documentation, and web apps alongside your terminal.

Opening the Browser

• Cmd+Shift+B — Slide-in panel (overlay mode)
• Command Palette → "Open Browser" — Opens in a split pane

By default, the browser opens http://localhost:3000. The URL bar supports full navigation with back, forward, and reload controls.

Profiles

Browser profiles isolate cookies, storage, and history. Create profiles for different projects or environments. Each profile gets its own WebKit data store.

Bookmarks

Organize bookmarks in folders with nested hierarchy support. Access via Cmd+Opt+Shift+B.

History

Full-text search across all visited URLs and page titles. History is stored locally in SQLite with FTS5 indexing. Access via Cmd+Opt+B.

DevTools

Cocxy includes a lightweight DevTools panel with three tabs:

• Console — Captures console.log, warn, error, and info output
• Network — Monitors HTTP requests via the Performance API
• DOM — Inspectable DOM tree view

Remote Workspaces

Connect to remote servers via SSH with persistent connections, port forwarding, SFTP file browsing, and key management. Open with Cmd+Shift+R.

Connection Profiles

Create reusable profiles with host, user, port, identity file, and port forwarding rules. Profiles are stored as JSON in ~/.config/cocxy/remotes/.

SSH Multiplexing

Cocxy uses OpenSSH ControlMaster for connection multiplexing. A single persistent TCP connection is shared across all sessions to the same host, eliminating re-authentication overhead.

Port Forwarding

Three forwarding modes are supported:

• Local (-L) — Forward a local port to a remote service
• Remote (-R) — Forward a remote port to a local service
• Dynamic (-D) — SOCKS proxy for tunneling all traffic

SFTP Browser

Browse remote filesystems, download files, upload files, and create directories — all from the Remote Workspaces panel.

Key Management

Discover, generate, and manage SSH keys. Supports ED25519, RSA, ECDSA, and DSA key types. Keys can be loaded into the SSH agent directly from the UI.

Auto-Reconnect

When enabled on a profile, Cocxy automatically reconnects with exponential backoff (1s, 2s, 4s, 8s, up to 30s) for up to 5 attempts.

Persistent Sessions (tmux)

Remote sessions backed by tmux survive SSH disconnects. When you reconnect, your sessions are waiting exactly where you left them. Zero installation required on the server — Cocxy uses the tmux that's already there.

• Auto-detection — Cocxy checks for tmux (preferred) or screen on the remote host
• Create sessions — Start a new persistent session from the Sessions panel
• Reconnect — After an SSH drop, your tmux sessions are still alive. Reconnect and re-attach
• Session UI — Visual panel showing all remote sessions with status, window count, and controls
• CLI — cocxy remote-list, cocxy remote-connect <name>, cocxy remote-status

Per-Project Configuration

Create a .cocxy.toml file in any project directory to override global settings. Cocxy detects it automatically when you cd into the directory and applies the overrides to the active tab.

Supported Overrides

• font-size — Override font size for this project
• background-opacity / background-blur-radius — Per-project transparency
• window-padding-x / window-padding-y — Terminal padding
• [agent-detection] extra-launch-patterns — Custom agent detection patterns for project-specific tools
• [keybindings] — Project-specific keyboard shortcuts

Example .cocxy.toml

# Project-specific overrides
font-size = 13
background-opacity = 0.95

[agent-detection]
extra-launch-patterns = ["^python manage.py", "^cargo run"]

[keybindings]
"cmd+shift+t" = "split-vertical"

Hot Reload

Changes to .cocxy.toml are detected and applied in real time — no restart needed. Use cocxy config-project to view the active overrides for the current tab.

AppleScript Automation

Cocxy exposes a full AppleScript vocabulary for automation and integration with Shortcuts, Automator, Raycast, and other macOS tools.

Vocabulary

Examples

-- Create a new tab and run a command
tell application "Cocxy Terminal"
    make new tab with properties {command:"ssh deploy@prod"}
    set name of tab 1 to "Production"
end tell

-- Count tabs
tell application "Cocxy Terminal" to count tabs

-- From the command line
osascript -e 'tell application "Cocxy Terminal" to make new tab'

Plugin System

Extend Cocxy with custom plugins that respond to terminal events. Plugins are stored in ~/.config/cocxy/plugins/ and managed via the CLI.

Plugin Structure

~/.config/cocxy/plugins/
  my-plugin/
    manifest.toml          # Required: plugin metadata
    on-session-start.sh    # Optional: runs when a session starts
    on-agent-detected.sh   # Optional: runs when an agent is detected
    on-command-complete.sh  # Optional: runs when a command finishes
    README.md              # Optional: documentation

manifest.toml

name = "My Plugin"
version = "1.0.0"
author = "Your Name"
description = "What this plugin does"
events = ["session-start", "agent-detected", "command-complete"]

Available Events

Security

Plugin scripts run in a sandboxed environment with a clean PATH, a 10-second timeout, and no access to Cocxy internals beyond the environment variables passed to them. Scripts execute as the current user — no privilege escalation.

CLI Commands

cocxy plugin-list               # List installed plugins
cocxy plugin-enable my-plugin   # Enable a plugin
cocxy plugin-disable my-plugin  # Disable a plugin

Splits

Split any tab into multiple panes. Each split runs its own terminal session or panel (browser, markdown preview).

• Cmd+D — Split horizontally (side by side)
• Cmd+Shift+D — Split vertically (top/bottom)
• Cmd+Opt+Arrow — Navigate between splits
• Cmd+Shift+W — Close focused split (LIFO order, last terminal is protected)

Quick Terminal

A dropdown terminal panel accessible from anywhere on your Mac via a global hotkey.

[quick-terminal]
enabled = true
hotkey = "cmd+grave"        # Cmd+` (backtick)
position = "top"            # top, bottom, left, right
height-percentage = 40
hide-on-deactivate = true

Press Cmd+` to toggle the Quick Terminal. It slides in from the configured edge and stays on top of other windows.

Notifications

Cocxy notifies you when agents need attention:

• Tab badge — Colored dot on the tab sidebar indicating agent state
• Dock badge — Unread count on the Dock icon
• macOS notification — System notification when the app is in the background
• Notification panel — In-app history of all notifications (Cmd+Shift+I)
• Smart Routing — Jump to the tab that needs attention (Cmd+Shift+U)

Command Palette

Press Cmd+Shift+P to open the Command Palette. Fuzzy search through all available actions, then press Enter to execute.

Actions include: new tab, close tab, toggle browser, toggle remote workspaces, switch theme, open dashboard, and more.

Sessions

Cocxy saves your workspace state (tabs, working directories, active tab) and restores it on next launch.

[sessions]
auto-save = true
auto-save-interval = 30     # seconds
restore-on-launch = true

Sessions are saved to ~/Library/Application Support/dev.cocxy.terminal/sessions/.

CLI Companion

The cocxy CLI provides 65 commands for scripting and automation via a local Unix domain socket.

# Tab management
cocxy new-tab --dir ~/projects/my-app
cocxy list-tabs
cocxy tab duplicate
cocxy tab pin

# Agent hooks
cocxy hooks install          # Configure Claude Code integration

# Window and session management
cocxy window list
cocxy session save my-workspace
cocxy session restore my-workspace

# Panels and dashboards
cocxy dashboard toggle
cocxy timeline export <tab-id> --format json

# Remote workspaces
cocxy remote list
cocxy remote connect prod-web
cocxy remote status

# Plugins
cocxy plugin list
cocxy plugin enable my-plugin

# Configuration and themes
cocxy theme set catppuccin-mocha
cocxy config list
cocxy config reload

# Output and notifications
cocxy capture-pane
cocxy notification list

# Run cocxy help for the full list of 65 commands

The CLI is automatically installed at /opt/homebrew/bin/cocxy when you install via Homebrew, or at ~/.local/bin/cocxy via the app bundle.

Themes

Cocxy ships with a curated set of themes and supports custom themes via Ghostty-compatible TOML files.

Built-in Themes

• Catppuccin Mocha (default)
• Catppuccin Latte (light)
• One Dark
• Dracula
• Nord
• Gruvbox Dark
• Tokyo Night
• Solarized Dark

Set your theme in config.toml:

[appearance]
theme = "one-dark"

Cocxy automatically switches between dark and light themes based on macOS appearance settings.

agents.toml Reference

Agent detection patterns are configured in ~/.config/cocxy/agents.toml. The file is auto-generated on first launch with built-in agent definitions.

Patterns use NSRegularExpression syntax. Use single-quoted TOML strings so backslashes are literal: '^claude\b'.

Troubleshooting

Backspace doesn't work

Cocxy sets TERM=xterm-256color by default. If your shell or SSH server expects a different terminal type, add to your shell config:

export TERM=xterm-256color

Agent detection not working

Verify detection is enabled in config.toml:

[agent-detection]
enabled = true

Check that agents.toml exists at ~/.config/cocxy/agents.toml. Delete it and restart Cocxy to regenerate defaults.

Font not rendering correctly

Ensure the font is installed system-wide. Cocxy recommends Nerd Fonts for icon support:

brew install --cask font-jetbrains-mono-nerd-font

brew upgrade not finding new version

Run brew update first to sync the tap, then upgrade:

brew update && brew upgrade --cask cocxy

Reset to defaults

Delete the config directory to reset all settings:

rm -rf ~/.config/cocxy
# Restart Cocxy — defaults will be regenerated