Getting Started

Cocxy Terminal is a native macOS terminal built for AI agent workflows. Zero telemetry, GPU-accelerated rendering, an inline agent code review panel, a full native Markdown workspace, and bundled local profiles for common coding-agent CLIs.

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.

Visual Tour

These screenshots were captured from Cocxy running against a local demo workspace, with the Aurora sidebar, split panes, dashboard, browser, command palette, and Preferences visible in real app state.

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 a configured local agent profile matches a launch command, hook event, OSC marker, or output pattern, 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 has no telemetry pipeline, no analytics SDK, no automatic crash upload, and no tracking. Network use exists for signed updates and explicit user actions such as browser sessions, remotes, GitHub CLI operations, plugins, or tools you run yourself. Terminal activity is not uploaded to a Cocxy backend.

Local Input Classification

The input classifier runs on this Mac before execution. It distinguishes shell-command, natural-language, dangerous-command, empty input, and unknown text so Cocxy can warn on destructive commands and offer agent routing without changing the default shell flow.

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

[input-classifier]
enabled = true
dangerous-command-warning = true
auto-route-natural-language = false
locale-detection = true
foundation-models-fallback = true

[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+shift+d"
split-horizontal = "cmd+d"
goto-attention = "cmd+shift+u"

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

Input Classifier

Cocxy classifies short prompt input locally before it is sent to a shell or routed to an agent workflow. The classifier detects shell commands such as git status, natural-language prompts such as what is the weather, and dangerous commands such as rm -rf /. Dangerous matches return dangerous-command, a confidence score, severity, and shouldWarnBeforeExecution.

Use cocxy classify "git status" or cocxy classify "what is the weather" to inspect the local JSON decision. The command prints fields such as category, confidence, languageCode, routingHint, and shouldWarnBeforeExecution without contacting a Cocxy service.

[input-classifier]
enabled = true
dangerous-command-warning = true
auto-route-natural-language = false
locale-detection = true
foundation-models-fallback = true

auto-route-natural-language defaults to false, so natural-language detection remains an explicit user choice instead of changing existing terminal behavior.

Command Signatures

Cocxy can sign and verify shared templates, macros, plugins, notebooks, and files with local Ed25519 keys. The key material stays in the macOS Keychain, trusted public keys stay in the local trusted author registry, and verification runs on this Mac before install or playback decisions.

Unsigned templates, macros, and plugins keep working by default. If a signature is present and cannot be verified, Cocxy reports an invalid signature instead of silently trusting the artifact. Verified items can show verified, unsigned items can show unsigned, and broken sidecars are treated as invalid signature.

[security]
require-signed-templates = false
require-signed-macros = false
require-signed-plugins = false
warn-on-unsigned = true
trust-on-first-use = false

cocxy keys generate --author "Your Name"
cocxy keys export-public <key-id> --output author.cocxykey
cocxy keys import author.cocxykey
cocxy sign template ./my-template
cocxy verify template ./my-template

Strict signature requirements are opt-in through [security]. Leave trust-on-first-use disabled when sharing artifacts across teams so every trusted author key is imported deliberately.

Sandbox Controls

Cocxy isolates local extension surfaces with component-level sandbox profiles instead of putting the whole terminal inside the macOS app sandbox. Plugins, Agent Mode command tools, and local MCP stdio servers get their own filesystem and process rules while the terminal keeps normal workspace access.

The Sandbox Inspector in Preferences shows active plugin capability grants and the local audit log. Revoke a grant from the inspector or use the CLI when you want a scriptable local check.

[security.sandbox]
plugins-strict = true
agents-isolated = true
mcp-isolated = true
audit-log-enabled = true
warn-on-grant = true

cocxy sandbox list-grants <plugin-id>
cocxy sandbox revoke <plugin-id> <capability>

Plugin write grants stay scoped to the plugin state directory. Agent command tools run with workspace-scoped read/write access, and MCP stdio servers inherit only the configured working directory and explicit file arguments.

Command Corrections

Cocxy can suggest local fixes after a failed shell command. It checks common typos such as gti status, aliases such as sl, command-name edit distance, shell hint text, and nearby filesystem paths such as a mistyped cd target. The instant heuristic path is local and designed for interactive latency.

Use cocxy correct "gti status" or cocxy correct "pyhton -m venv ." to inspect the JSON suggestions without opening the app socket. When the terminal overlay appears after a failed command, press Tab to accept the suggestion or Esc to dismiss it.

[command-corrections]
enabled = true
edit-distance-threshold = 2
foundation-models-enabled = true
agent-fallback = false
auto-show-on-failure = true
show-confidence-badge = true
max-suggestions-shown = 3

agent-fallback defaults to false. Turn it on only if you want the active, user-configured agent to participate in harder correction cases.

Keyboard Shortcuts

Tabs

Splits

Panels & Overlays

Terminal

Agent Detection

Cocxy uses a multi-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) — Multi-agent hook integration streams local events in real time: tool calls, responses, session lifecycle, subagent spawn, and error signals. Run cocxy setup-hooks to auto-configure hooks for compatible installed agents.
2. OSC Sequences — Shell integration markers (OSC 133, OSC 7) for working directory and command boundary detection.
3. Pattern Matching — Regex patterns matched against terminal output to detect agent launch commands, waiting prompts, completion markers, and errors.
4. Timing Heuristics (fallback) — Detects idle timeouts and sustained output patterns when the other layers don't match.

Agent States

Bundled Agent Profiles

Cocxy ships bundled local profiles for hook-capable, OSC-aware, pattern-only, and timing-fallback coding-agent CLIs. Hook-capable profiles provide the richest state because Cocxy receives local events for session start/end, tool use, subagent spawn, errors, and prompt handoff. Profiles without hooks still use OSC markers, output patterns, and timing heuristics.

Detection patterns stay local and are evaluated with NSRegularExpression against terminal output already rendered in Cocxy. You can inspect or override profile behavior from ~/.config/cocxy/agents.toml.

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

Agent Code Review Panel

A native panel to review every change an AI coding agent made during a session. Comment inline, submit feedback back to the agent, and accept or reject individual hunks — all without leaving Cocxy.

Opening the Panel

• Cmd+Opt+R — Toggle the panel for the active tab
• cocxy review — Toggle via the CLI
• Auto-trigger — The panel opens automatically when an agent session ends (configurable via [code-review] auto-show-on-session-end)

Reviewing Changes

• File tree — Shows every file the agent touched, with status icons (added, modified, deleted, renamed) and per-author chips when multiple agents edited the same session
• Unified diff — Rendered with line numbers and syntax-aware colors
• Inline comments — Click any line in the gutter, type a comment, press Enter; a comment bubble anchors under that line
• Stats toolbar — Live counts of pending comments, files changed, hunks accepted or rejected

Feedback Loop

Click Submit N Comments (or press Cmd+Enter) and the formatted feedback is sent through the agent's PTY. The agent picks up the corrections and re-runs the task. The panel refreshes automatically as the agent produces new changes.

Accept or Reject Hunks

• Accept — Stages the hunk with git apply --cached, keeping the agent's change
• Reject — Reverses the hunk with git apply --reverse, discarding it from the working tree
• All operations are serialized through a dedicated queue to prevent races

Keyboard Navigation

CLI Commands

cocxy review                     # Toggle the panel
cocxy review --refresh           # Force refresh diffs
cocxy review --submit            # Submit all pending comments to the agent
cocxy review --stats             # Print stats for the active session

Markdown Workspace

A first-class native Markdown panel that renders in a split pane next to your terminal. Written from scratch in pure Swift — no external parser dependency, no network calls.

Opening Markdown

• Drag a .md file onto any tab or split pane
• Use the Command Palette: Open Markdown
• Double-click a .md file in the file explorer sidebar

View Modes

• Cmd+1 — Source (editable plain text with syntax highlighting)
• Cmd+2 — Preview (WKWebView with Mermaid, KaTeX, callouts, footnotes)
• Cmd+3 — Split (source + preview side by side with scroll sync)

Editor

• Cmd+B — Toggle bold on the selection
• Cmd+I — Toggle italic
• Cmd+K — Wrap in a Markdown link
• Native AppKit Find bar with Cmd+F
• Debounced auto-save (150 ms) with atomic writes
• File watcher dedup by content — no reload loops when the editor saves
• All AppKit autosubstitutions disabled so Markdown syntax is never rewritten

Rendering

• GitHub Flavored Markdown (tables, task lists, strikethrough, autolinks)
• Reference-style links and setext headings
• Fifteen callout types ([!note], [!tip], [!warning], [!important], etc.)
• Footnotes with hover previews
• Highlight (==text==), superscript (^text^), subscript (~text~)
• 200+ emoji shortcodes (:rocket:, :warning:)
• Mermaid diagrams and KaTeX math (bundled offline, zero network)
• Syntax highlighting for 190+ languages via Highlight.js (bundled)
• Sortable tables with three-state (none / asc / desc) numeric-aware sort
• Inline [TOC] placeholder generates a table of contents

Sidebar and Search

• Cmd+Shift+O — Toggle the outline / files / search sidebar
• Outline — Heading tree navigation (click to jump)
• Files — Browse the workspace's Markdown files with rename, move-to-trash, reveal-in-Finder
• Search — Multi-file full-text search with debounced results

Git Integration

• Blame — Inline line-by-line authorship and commit history
• Diff — Side-by-side working-tree vs last commit view

Export and Copy

• Export to PDF via the system print dialog
• Export to standalone HTML with inlined images as base64 data URIs
• Slide exporter: split the document on horizontal rules, preserve original formatting, embed Mermaid and KaTeX inline
• Copy as Markdown, HTML, rich text (RTF), or plain text

Interactive Preview

• Clickable checkboxes — Toggle task list checkboxes directly in the preview; changes write back to the source
• Click-to-source — Double-click any block to jump to its line in the source editor
• Image lightbox — Click any image to expand
• Paste PNG or TIFF — Cmd+V pastes image data from the clipboard directly into the document
• Drag and drop — Drop an image file to insert an inline reference
• Copy table as TSV — One-click copy for pasting into spreadsheets

QuickLook Preview Extension

A system-integrated QuickLook extension that renders .md files directly in macOS Finder. Select a Markdown file in Finder and press Space.

• Same renderer as the in-app preview: Mermaid, KaTeX, callouts, footnotes, Highlight.js
• Bundled offline with zero network dependency
• Sandboxed as an .appex plugin following macOS security conventions
• Registered automatically when you install Cocxy; verify with cocxy hooks install which also checks QuickLook registration

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

SOCKS5 + HTTP CONNECT Proxy

A native proxy that tunnels traffic through a connected SSH host. System-wide macOS integration, PAC generation, per-host exclusion lists, and health monitoring with auto-failover to a backup host.

Agent Relay

Multi-channel reverse tunnels with HMAC-SHA256 authentication, per-channel ACLs, audit logs (JSON lines), token rotation, and Keychain persistence. Useful for exposing a local agent to a remote tool chain securely.

Remote Daemon

A POSIX shell daemon (no compilation required on the server) with three-level session fallback (tmux / screen / native PTY), persistent port forwards managed from the daemon, file sync watching, and 24-hour auto-cleanup for orphan sessions.

Web Terminal Embed

Expose any local Cocxy terminal over HTTP with a zero-dependency frontend. Useful for peer programming, remote assistance, or embedding a live terminal into an internal dashboard.

cocxy web-start --port 8080         # Expose the active terminal on http://localhost:8080
cocxy web-stop                       # Stop the web server
cocxy web-status                     # Show active connections and frame rate

• Tunable frame rate (default 30 fps, up to 60 fps)
• On-demand full-frame refresh from the server
• Per-terminal attach and detach
• Plugin events for connection open / close

Shell Integration

Native shell integration for zsh, bash, and fish. Installed automatically — no setup required. Designed to coexist safely with Prezto, Oh My Zsh, YADR, starship, and any custom prompt.

What It Provides

• OSC 7 — Working directory reporting with URI encoding for paths with spaces and non-ASCII characters
• OSC 133 — Semantic prompts for command boundaries, duration tracking, and exit code reporting
• Safe env injection — Cocxy's integration scripts restore your original ZDOTDIR, HOME, and XDG_CONFIG_HOME before loading your framework, so nothing about your existing setup changes

Per-Shell Behavior

• zsh — Integration via ZDOTDIR pointing at Cocxy's shim that bootstraps your real config. Works with Prezto, Oh My Zsh, and starship out of the box.
• bash — Integration via HOME pointing at a shim that sources your real .bashrc. Preserves any existing DEBUG trap and PROMPT_COMMAND.
• fish — Integration via XDG_CONFIG_HOME pointing at Cocxy's fish config that then sources yours. Uses fish's native --on-variable PWD hook, no DEBUG trap required.

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

Local Backups

Cocxy writes local backup snapshots to your Mac by default. They cover settings, notebooks, workflows, custom skills, notes, snippets, themes, and encrypted SSH host metadata when those sources exist. Nothing is uploaded.

[backup]
enabled = true
storage-directory = "~/Library/Backups/Cocxy"
daily-retention-count = 30
monthly-retention-count = 12

• Review snapshots — Open Preferences > Backups and use Refresh to scan the configured backup folder.
• Restore manually — Pick a backup, choose one artifact type, then press Restore. Restore only the selected artifact; other local files are left in place.
• Move to another Mac — Copy the backup folder, point Cocxy at that location, refresh, and restore only the artifacts you want.

CLI Companion

The cocxy CLI provides more than 100 commands for scripting and automation via a local Unix Domain Socket with per-UID authentication.

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

# Agent hooks (one command sets up every installed agent)
cocxy setup-hooks
cocxy hooks install

# Agent code review
cocxy review                     # Toggle the panel
cocxy review --refresh           # Force diff refresh
cocxy review --submit            # Send pending comments to the agent
cocxy review --stats             # Print review stats

# 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 --format json > events.json

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

# Web terminal embed
cocxy web-start --port 8080
cocxy web-status
cocxy web-stop

# Plugins
cocxy plugin-list
cocxy plugin-enable my-plugin

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

# Terminal diagnostics
cocxy core-modes                 # Dump alt-screen, cursor, semantic state
cocxy capture-pane
cocxy send --stdin               # Read multiline / escape-safe input from stdin

# Run cocxy help for the full command reference

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

Themes

Cocxy ships with a curated set of themes and supports custom themes via Cocxy-compatible TOML files. Drop a .toml theme into ~/.config/cocxy/themes/ and it appears immediately in the theme picker.

Built-in Themes

• Catppuccin Mocha (default dark)
• Catppuccin Latte (default light)
• One Dark
• Solarized Dark
• Solarized Light

Set your theme in config.toml:

[theme]
name = "catppuccin-mocha"
light-theme = "catppuccin-latte"

Cocxy automatically switches between the name (dark) and light-theme pair based on macOS appearance settings. Live hot-reload applies theme changes without recreating terminal surfaces.

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: '^my-agent\b'.

Migration from v0.x

Before upgrading across v0.x releases, review the Releases page and keep a local copy of ~/.config/cocxy/ if you rely on SSH profiles, snippets, custom themes, plugins, browser data, or saved workspaces.

Cocxy migrations are conservative: valid TOML is preserved, unknown user-defined plugin and theme files stay in place, and local-only stores remain on your Mac. New defaults are added only when the app needs a missing key to keep an existing workflow working.

cp -R ~/.config/cocxy ~/Desktop/cocxy-config-backup
brew update && brew upgrade --cask cocxy

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