calyx

README

Calyx

A terminal multiplexer for AI coding agents.
Run Claude, Gemini, and Copilot sessions side-by-side, organized by project and branch.

Quick Start · Features · Keybindings · Configuration

---

 +-----------+-----------------------------------+
 | Projects  |  Agent  | Diff | Plan             |
 |           |                                   |
 |  myapp/   |  > Hello! I'll help you with...   |
 |    main   |                                   |
 |    feat/  |  $ Running tests...               |
 |      s1   |                                   |
 |      s2   |                                   |
 +-----------+-----------------------------------+
 | ?:help  q:detach  ␣n:new         Sessions 2/3 |
 +-----------------------------------------------+

Features

• Multiple agents -- Claude, Gemini, and Copilot in parallel sessions
• Project organization -- Group sessions by project and git branch
• Git worktree isolation -- Each branch gets its own worktree automatically
• Agent passthrough -- Full terminal passthrough to interact with agents directly
• Diff view -- Syntax-highlighted diff of agent changes with search and inline comments
• Plan view -- Rendered markdown of agent plans
• Customizable keybindings -- Override any binding via JSON config

Quick Start

Prerequisites

• Go 1.24+
• tmux
• At least one agent CLI: claude, gemini, or copilot

Install

go install github.com/happsie/calyx/cmd/calyx@latest

Or build from source:

git clone https://github.com/happsie/calyx.git
cd calyx
go build -o calyx ./cmd/calyx
./calyx

Keybindings

Calyx uses a leader key system inspired by vim and tmux. Navigation uses familiar vim motions (j/k, g/G, ctrl+d/ctrl+u), while application commands use leader sequences to avoid conflicts with vim keys.

The Leader Key

The leader key (default: Space) acts as a prefix for application commands. Press the leader key, then press the command key within 1 second:

Space → n    Create new session
Space → x    Stop current session
Space → d    Delete session (in sidebar)

This keeps single-key vim motions clean and conflict-free, while giving you quick access to every app command through two-key sequences.

Global

Key	Action
q	Detach (sessions keep running)
ctrl+q / ctrl+c	Force quit and stop all sessions
?	Toggle help
tab	Toggle focus between sidebar and main pane
1 / 2 / 3	Switch to Agent / Diff / Plan view
Space n	New session
Space x	Stop session
Space r	Restart session
Space t	Toggle terminal split
Space m	Toggle NAV / SELECT mode (mouse on/off)

Sidebar

Key	Action
j / k / ↓ / ↑	Move down / up
g / G	Jump to top / bottom
enter	Select item
Space d	Delete session

Agent View

Key	Action
i	Enter input mode (passthrough to agent)
Esc	Exit input mode
ctrl+t	Toggle focus between agent and terminal
j / k / ↓ / ↑	Scroll down / up
g / G	Jump to top / bottom
ctrl+d / ctrl+u	Page down / up

Diff View

Key	Action
j / k / ↓ / ↑	Cursor down / up
g / G	Jump to top / bottom
ctrl+d / ctrl+u	Page down / up
h / l / ← / →	Switch between old / new columns
H / L	Switch between old / new columns (alternate)
/	Search
n / N	Next / previous match
Space c	Add comment at cursor
Space C	Edit existing comment
ctrl+s / S	Send comments to agent
e	Open file in editor
R	Refresh diff

Plan View

Key	Action
j / k / ↓ / ↑	Cursor down / up
g / G	Jump to top / bottom
ctrl+d / ctrl+u	Page down / up
/	Search
n / N	Next / previous match
e	Open file in editor
R	Refresh plan

Customization

All keybindings are customizable via ~/.config/calyx/keybindings.json. You only need to include the bindings you want to override -- defaults are merged automatically.

Example: change the leader key to backslash and remap new session to Space s:

{
  "leader_key": "\\",
  "bindings": [
    {"key": "<leader>s", "action": "new_session", "scope": "global"}
  ]
}

In the config file, use <leader> as a placeholder that expands to your configured leader key. See default_keybindings.json for the full list of actions and scopes.

Configuration

Path	Purpose
~/.config/calyx/config.yaml	General settings (default agent, editor, theme)
~/.config/calyx/keybindings.json	Custom keybindings
~/.local/share/calyx/state.json	Persisted session state

License

MIT