Ködade CLI

Keep your coding agents, shells, and remote projects in one terminal workspace. Ködade CLI remembers your panes, shows which agents need attention, and gives you the same controls at the keyboard or from a script.

• Find the next action. Press ctrl+b, then space to search commands, launch an agent, switch projects, or open settings.
• Work across machines. Keep local and saved SSH workspaces together, with independent focus and reconnects for each attached client.
• Automate with a clear target. Start, read, prompt, and wait for a specific agent. Exact conversation references prevent an accidental resume into the wrong conversation.
• Make it yours. Add local extensions, selected-text actions, command shortcuts, workspace variables, and Git worktrees.

A Rust binary with a persistent local daemon. No account or hosted service. Ködade CLI also works independently of the Ködade desktop app.

Status

v0.3.0 supports macOS and Linux on arm64 and x86_64. Distribution uses Homebrew and standalone GitHub releases with checksums. Native Windows binaries and Windows installation support remain deferred.

What’s in v0.3.0

The release brings the everyday workspace flows together:

• Local and saved SSH machines in one workspace, with independent reconnects.
• A command center (prefix space) and attention history (prefix A).
• Guarded agent launch/prompt/wait automation and live integration reloads.
• Local extensions with selected-text context, URL handlers, event hooks, and terminal panes.
• Configured command shortcuts, workspace environments, and existing worktree open.
• Exact native conversation restore and opt-in terminal history after a cold restart.
• An offline agent automation guide, available with kodade-cli agent guide.
• Terminal images, PNG paste, and a focused view for narrow terminals.
• OSC 8 links open their exact target from live output or local history; terminal frames stay atomic where synchronized output is supported.
• Local copies use the platform clipboard when available and retain OSC 52 for SSH, remote panes, and terminals without a native clipboard tool.
• Live daemon upgrade for an already-running v0.3.0 Unix session, preserving its pane processes while attached clients reconnect.
• Negotiated keyboard input and theme-aware terminal color queries, preserved through reconnects and live upgrades.
• Verified stable/preview updates for standalone installations.

Moving from v0.2.1

A v0.2.1 daemon cannot perform a live handoff: it does not understand the v0.3.0 upgrade request. Installing the new binary does not stop that daemon or its panes. Keep the existing session open, then start a separate v0.3.0 session with a new name, for example kodade-cli -s v03. Move work only when you are ready; do not kill the v0.2.1 session to migrate it.

Once a session is already running v0.3.0 on macOS or Linux, run kodade-cli -s SESSION session upgrade to replace its daemon without restarting its panes. The operation rolls back if the replacement cannot prepare itself. Attached Ködade clients reconnect with their saved view; queued input is not replayed.

See the competitive delivery ledger for reviewed evidence and known terminal compatibility limits.

Install

With Homebrew (macOS and Linux):

brew tap kodade/tap
brew trust kodade/tap   # Homebrew 6 and later; not needed on older versions
brew install kodade-cli

Later releases arrive with brew upgrade. The formula lives in Kodade/homebrew-tap and is updated by the release workflow.

Without Homebrew, install a prebuilt binary with:

curl -fsSL https://raw.githubusercontent.com/Kodade/kodade-cli/main/install.sh | sh

Or build from source:

cargo build
cargo run -p kodade-cli

The installer supports macOS and Linux on arm64 and x86_64.

Updates

kodade-cli update --check prints the installed and available version from the stable channel. Use kodade-cli update --channel preview --check to select and check preview releases; kodade-cli update --show-channel prints the saved choice. The selected channel is stored separately from workspace settings.

Recognized Homebrew and system-package paths receive package-manager upgrade guidance. Use the package manager for any other managed installation. Standalone installations download the published platform archive, verify its SHA256SUMS entry, and atomically replace the executable. --install-to PATH is available for an explicit standalone destination.

Quick usage

Run kodade-cli to open the current directory in the default session; it starts the daemon when needed. It reuses a workspace with the same canonical root, or creates one named after the directory with its first shell starting there. Existing workspace names, panes, and shell directories are preserved. Launches from symlinks reuse the same workspace; different roots with the same folder name remain separate. Each attached terminal keeps its own workspace selection.

Use kodade-cli -s SESSION to resume a named session, or kodade-cli -s default to resume the default session without directory selection. Explicit --socket, --remote, and inherited KODADE_SESSION/KODADE_SOCKET context also retain resume behavior. Detach with the prefix followed by d.

If an older running v0.3.0 daemon lacks directory selection, run kodade-cli -s default session upgrade after installing the updated binary. This preserves running panes. The client reports this requirement before entering the TUI.

For scripts, new, run, and new-tab/workspace commands also start a missing local daemon. kodade-cli doctor (alias status, with --json for scripts) checks your configuration, shell, optional tools, and daemon without starting a session. kodade-cli config init writes a small editable configuration and preserves any existing file. Startup errors return within ten seconds and point to the daemon log beside its socket.

The default prefix is ctrl+b. After the prefix, the default actions are:

Key	Action
space / A	Command center / attention history
% / "	Split right / down
x / c	Close pane / new tab
n	Navigate mode
tab / p	Next / previous tab
z / d	Zoom pane / detach
r / W	Rename / new workspace (W prompts for NAME [PATH])
G	New git-worktree workspace (prompts for a branch)
w / g	Workspace picker / goto palette (fuzzy; type to filter, enter jumps)
alt+w	Next workspace (cycle without the picker)
b / [	Cycle sidebar (full → compact → hidden) / copy mode
PageUp / PageDown	Scroll the focused pane's local history by one page / back toward live output
h j k l or arrows	Focus left, down, up, right
H J K L	Resize left, down, up, right
1–9	Jump to that tab
X / T	Close / rename tab
D / R	Close / rename workspace
alt+h alt+j alt+k alt+l	Swap the pane with its neighbour
o / O / ;	Next / previous / last pane
! / =	Break pane to a new tab / equalize the layout
q	Flash big pane ids (tmux display-panes)
alt+r	Resize mode (hjkl 1 cell, HJKL 5, esc exits)
s / ctrl+r	Settings menu / reload config and theme
]	Paste the internal buffer (last paste, copy-mode yank, or mouse selection)
m	Toggle mouse capture (hands the mouse back to the host terminal)
N	Jump to the most recent unread agent notification

The status bar shows session · workspace · tab on the left and configurable widgets on the right ([zoom], a ● N blocked counter, hostname, time — set status.right). Pane borders carry #id name — state plus the cwd basename, and the host terminal title tracks the active workspace/tab. See docs/CONFIG.md.

Mouse is enabled by default: click panes, tabs, and sidebar rows to focus; drag pane borders to resize; scroll over a pane to scroll; right-click a pane, tab, or workspace for its menu; the pane menu can break a pane out to its own tab or equalize the layout, and the tab menu can reorder tabs. In navigate mode, j/k move through the sidebar and enter selects a row (folding/unfolding a workspace, or activating a tab/pane); q or esc exits.

Below 70 columns, compact view shows the focused pane at full width while keeping every split and process alive. Click [<] / [>] to cycle panes or [Switch] to search workspaces, tabs, and panes; keyboard shortcuts keep working. Widening restores the split layout. This preference belongs to each attached client, so a second wide terminal keeps its own view. Set sidebar.compact_view = "on" or "off" to override automatic switching.

The sidebar has three shapes cycled by prefix b: the full list, a compact 3-column rail of workspace state dots, and a hidden 1-column gutter. It is configurable via [sidebar] (width, collapsed, auto_hide_below, compact_view, agents_panel) and auto-hides on narrow terminals. Every workspace can be folded (enter in navigate, * expands all; remembered per session), an agents panel below the workspaces lists agent panes by urgency, and each workspace carries a color swatch (right-click → Color…, or an auto-hashed fallback). See docs/CONFIG.md.

Dragging inside a pane selects text and copies it on release (the local platform clipboard when available, otherwise OSC 52 so it works over SSH); double-click selects a word, triple-click a line, and ctrl/cmd-click opens the URL under the pointer with ui.link_command. OSC 8 labels use their exact target, including in local history. Panes running a mouse-aware program (vim, lazygit, htop) get the events themselves unless mouse.passthrough = false. Hold shift while wheeling to inspect Ködade CLI's local history; once history is open, wheel down returns to live output before wheel events return to the application. prefix PageUp and prefix PageDown provide the same local history controls without taking ordinary PageUp/PageDown from the application. Alternate-screen applications have no local history while their alternate screen is active. prefix m turns capture off when you want the terminal's own selection. See docs/CONFIG.md.

Copy mode (prefix [) freezes the pane's full scrollback and navigates it with vi motions over the whole history, not just the visible screen. The status bar shows copy · LINE/TOTAL · / search · v V select · y copy · e editor · esc. Wheel over that copied pane scrolls the copy-mode viewport; wheel over another pane keeps that pane's normal local-history behavior.

Key	Action
h j k l / arrows	Move by cell / line
w b / W B / E	Word / WORD motions (e is the editor, so word-end is E)
0 ^ $	Line start / first non-blank / line end
gg / G	Top / bottom of the buffer
{ / }	Previous / next blank line
ctrl+u ctrl+d	Half page up / down
ctrl+b ctrl+f / PageUp PageDown	Page up / down
H M L	Cursor to viewport top / middle / bottom
v / V / ctrl+v	Char / line / block selection anchor
/ ? then n N	Search forward / back (case-insensitive), step matches
y	Copy the selection (or current line) to the local clipboard, with OSC 52 fallback
e	Open the buffer in $EDITOR (fallback vi) in a new split
esc	Clear search, then the selection, then exit; q exits

Copying uses the local platform clipboard when available. It falls back to OSC 52 for SSH, remote panes, and unavailable clipboard tools; payloads are limited to 100 KB. The buffer is refetched (throttled) while the pane keeps producing output. Copy mode draws plain text — the frozen cell colors of the live screen are not reproduced there.

Paste is bracketed so a program can tell it from typing. Pasted text is sanitized by default (paste.sanitize): CRLF is normalized, embedded escape sequences — including a smuggled OSC 52 or CSI — are dropped, and control bytes other than tab and newline are stripped. Large pastes are chunked and paced. The last paste (or yank) is kept in a buffer that ] re-sends.

When an agent transitions into blocked or done, the daemon notifies every attached client: a status-bar toast in the state's color, a terminal bell, and optionally a host-terminal desktop notification (notify.toast = "system") or a sound command (notify.sound). prefix N jumps to the pane of the most recent unread notification. Notifications are configurable and can be turned off entirely; see docs/CONFIG.md.

Bindings accept a chord or an array of chords, in any modifier order (split_right = ["%", "ctrl+alt+v"]). A ctrl/alt chord that is not written as prefix+… is global: it fires without the prefix. prefix ctrl+r reloads config.toml and the theme in place, and prefix s opens a settings menu that writes your choices back to config.toml without disturbing comments. See docs/CONFIG.md for all bindings and configuration.

Sessions survive a daemon restart: the layout (workspaces, tabs, pane trees, names, cwds, and zoom) is saved under ~/.local/state/kodade-cli/sessions/ (macOS: ~/Library/Application Support/…) and rebuilt with fresh panes on the next cold start; a corrupt file degrades to a clean start and kodade-cli ls marks a restored session (restored). Set [session] resume_agents = true to resume panes that reported an exact native conversation identity; panes without one restore as shells. [session] pane_history = true additionally retains a bounded local screen replay after a cold restart; it is off by default and does not imply that the original process survived.

The CLI's dark theme uses charcoal backgrounds and off-white text with the Ködade orange accent #E7A33B and a purple-free ANSI palette. theme = "auto" (the default) picks kodade-dark or kodade-light from the terminal background; tokyo-night and custom themes are also available. See the Themes section for the schema.

Run kodade-cli --help for the full command list and kodade-cli --version for the installed version. kodade-cli agent guide prints the bundled automation guide, including targeting, guarded prompts, waits, remote endpoints, and exit codes. The scripting commands are:

• kodade-cli ls — list sessions, workspaces, tabs, panes, and states.
• kodade-cli new -w NAME [PATH] — create a workspace with an optional root directory and print its id (selects the workspace if the name already exists).
• kodade-cli run [-w NAME] [-t TAB] [--name NAME] -- CMD ARGS… — run a command in a new pane through the login shell and print the new pane id.
• kodade-cli split [--down] [-p PANE] [-- CMD…] — split the focused (or given) pane and print the new pane id.
• kodade-cli new-tab [-w NAME] [--name NAME] — open a new tab and print its pane id.
• kodade-cli pane ls|read|send-keys|kill|focus|zoom|swap|move|resize|wait-output — inspect and drive panes.
• kodade-cli pane read PANE [--lines N] [--scrollback] — print a pane's text (visible screen by default; --scrollback includes the full history, --lines N keeps only the last N lines).
• kodade-cli tab ls|new|close|rename|select — tabs of the active workspace (TAB is a name or an id).
• kodade-cli workspace ls|new|close|rename|select|color WS HEX|off — workspaces (WS is a name or an id); workspace new NAME [PATH] --env KEY=VALUE persists explicit environment for every future pane in that workspace. and color sets the sidebar swatch.
• kodade-cli session ls|path|kill [NAME]|rename NAME — every session on this machine; ls probes each socket and marks it (restored) or (dead), and path prints the daemon socket path (--remote prints the host's). With --remote every session verb runs on the host.
• kodade-cli layout export [FILE]|apply FILE — save and restore a layout. apply runs the commands saved in the file (through the login shell, in each pane's saved directory), so only apply layout files you trust.
• kodade-cli worktree add BRANCH [--from REF|--base REF] [--path PATH] [-w NAME] — git worktree add a branch on the workspace's repo and open a repo:branch workspace rooted in it (prints the new workspace id). worktree list shows every branch workspace with its root and parent; worktree remove WS|BRANCH [--keep] closes it and removes the worktree unless --keep. worktree open PATH [-w NAME] opens an existing linked checkout after verifying its owning repository; it never copies or deletes that checkout.
• kodade-cli events [--json] — stream session events until interrupted.
• kodade-cli completion zsh|bash|fish — print a completion script.
• kodade-cli agent ls — list recognized agents and states.
• kodade-cli agent start [-w WS] [-t TAB] [--name NAME] -- CMD… — start an agent in a new pane; it never types into an existing shell.
• kodade-cli agent read TARGET [--scrollback] [--lines N] [--json] — read a recognized agent by pane id, unique agent name or pane title, or current.
• kodade-cli agent prompt TARGET TEXT [--wait|--until STATE] [--timeout S] — sanitize and bracket-paste a prompt, then submit it after rejecting blocked and non-agent targets. Waiting requires fresh activity before accepting a settled state, so stale idle/done values cannot produce a false success. Each prompt is an ordered, 64 KiB-max PTY submission.
• kodade-cli agent send-keys TARGET KEYS… / agent focus TARGET — drive or select a recognized agent by the same target syntax.
• kodade-cli agent attach TARGET — focus a recognized agent and attach the TUI.
• kodade-cli agent rename TARGET NAME — rename a recognized agent pane.
• kodade-cli agent explain TARGET — print an agent's state, reason, and the bottom-8-line window it matched.
• kodade-cli agent wait TARGET --state STATE [--timeout S] — block until an agent reaches a state; exits 0 when it does and 2 on timeout.
• kodade-cli agent report PANE STATE — report an agent state to the daemon.
• kodade-cli agent update-manifests — opt-in refresh of agent-detection manifests from GitHub.
• kodade-cli send PANE TEXT — send text followed by a newline (--no-newline is also supported).
• kodade-cli kill-session — stop the current session.
• kodade-cli config init|path|show|validate — create a starter config, print its path or effective TOML, or validate it (non-zero on problems).
• kodade-cli doctor [--json] — diagnose configuration, installed tools, and daemon health; status is an alias.

Text and names may start with - (kodade-cli send 1 -y), and -- forces the next value through verbatim when it collides with a flag (kodade-cli send 1 -- --no-newline).

-w and -t accept either a name or a numeric id. A workspace can have a root directory (new -w NAME PATH or the prefix W prompt); new panes, splits, and tabs start in the focused pane's live working directory, falling back to the workspace root, so agents keep landing in the right repo.

ls, agent ls, agent explain, pane ls, tab ls, workspace ls, and session ls also accept --json, which prints the matching protocol snapshots for scripts.

Scripts wait on agents instead of polling by hand:

# Block until pane 3 needs you, then read the last five lines it printed.
kodade-cli agent wait 3 --state blocked && kodade-cli pane read 3 | tail -5

# The full session snapshot, for jq.
kodade-cli ls --json | jq '.panes[] | {id: .id, state: .state}'

# React to every state change as it happens.
kodade-cli events --json | jq -r 'select(.AgentStateChanged) | .AgentStateChanged.pane'

pane wait-output PANE --match TEXT waits for text on a pane's visible screen; --scrollback searches the durable history too. --regex treats TEXT as a regular expression (invalid patterns fail before polling). Both waits work on panes in background tabs and workspaces.

pane send-keys accepts tmux-style key names — Enter, Escape, Tab, Space, BSpace, arrows, Home, End, PageUp, PageDown, Insert, Delete, F1–F12, C-c (control) and M-x (alt) — and sends anything else as literal text: kodade-cli pane send-keys 3 "npm test" Enter. A capitalized word that is not a known key name is rejected rather than typed, so a typo like Entr fails loudly; use --literal to send such text verbatim (kodade-cli pane send-keys 3 --literal "Hello there").

session rename NAME moves the live session's socket, so the same daemon and panes answer under the new name. Shells that were already running keep the old KODADE_SESSION / KODADE_SOCKET values, and attaching with the old name starts a new empty session.

Panes a session spawns get KODADE_PANE, KODADE_SESSION, KODADE_SOCKET, and KODADE_BIN in their environment, which is everything a custom agent needs to report its own state. Commands inherit that session and socket automatically; explicit -s, --remote, or --socket PATH selects another endpoint. Session names are limited to 64 bytes and exclude path separators and control characters. The socket protocol itself — framing, every message, the Subscribe event stream, and the schema query — is documented in docs/SOCKET-API.md.

Two agents on two branches

From a workspace rooted in a git repo, prefix G (or worktree add) spins up an isolated worktree per branch so two agents never step on each other:

kodade-cli new -w repo ~/src/repo      # workspace rooted in the repo (on main)
kodade-cli worktree add feat-a         # → workspace repo:feat-a in a new worktree
kodade-cli worktree add feat-b --from main
# run an agent in each branch's workspace
kodade-cli run -w repo:feat-a -- claude
kodade-cli run -w repo:feat-b -- codex

The sidebar nests each worktree under repo with its branch (⎇ feat-a), and repo shows its own branch dimmed after the name. worktree remove feat-a closes the workspace and deletes the worktree directory.

Remote

kodade-cli --remote USER@HOST attaches to a daemon on another host over an SSH-forwarded socket, so you can drive agent panes on a build box or server from your laptop. The same flag works with the scripting subcommands (kodade-cli --remote HOST -s work agent ls) and with -s NAME to pick a session. --remote HOST session ls lists the host's sessions (prefixed with host:).

Requirements and behavior:

• kodade-cli must be installed on the remote host and on your PATH there. If it is missing, the command prints the install one-liner and exits. (Auto-install is a later phase.)
• Auth is your existing SSH setup — config, agent, and keys. Ködade never sees or proxies credentials.
• The daemon is started on the host automatically if it is not already running, and it keeps your session alive between connections. Dropping the link and re-running --remote reattaches to the same session; a control-master connection lingers ~60 s (ControlPersist) so reconnecting is fast.
• Set ServerAliveInterval in your ~/.ssh/config for the host if you attach over flaky links, so a dead connection is noticed promptly.
• Copy mode and the clipboard run on your local machine, so yanking from a remote pane copies to your local clipboard as usual.

Requires OpenSSH with Unix-domain forwarding (-L localsock:remotesock), which is standard on current macOS and Linux.

kodade-cli integrate list shows the available integrations. kodade-cli integrate <agent> prints the hook settings and --write installs them: claude-code and gemini-cli merge hooks into their settings.json; codex merges marked lifecycle hooks into ~/.codex/hooks.json without replacing its separate notify setting. See docs/AGENT-DETECTION.md for details.

See docs/CONFIG.md, docs/AGENT-DETECTION.md, docs/SOCKET-API.md, docs/DEVELOPMENT.md, and docs/RELEASING.md for reference and contributor details. The product direction is in docs/PRD.md.

Terminal images

Kitty and Ghostty can display images emitted by panes. Images stay inside pane borders, survive detach, and follow scrolling. Press prefix I to paste a clipboard PNG, or run kodade-cli pane paste-image 3 screenshot.png; remote panes receive an uploaded file on their own host. See graphics support and limits.

License

Apache License 2.0 — see LICENSE and NOTICE.

Saved SSH machines appear together in the sidebar, with independent reconnects and endpoint-scoped agent alerts. See Machines.