Cockpit reference

Install

Cockpit ships for macOS, Windows, and Linux. macOS builds are signed and notarized, and every platform that supports it gets in-app updates. Grab a build from the download page — .dmg, .exe, .deb and .rpm (x64 and arm64), each with a published SHA-256.

Cockpit is a terminal first: it needs no account, no cloud and nothing else installed to be useful. Agents run as ordinary processes in its tabs, so the harness you already use (Claude Code, Codex CLI, Pi, OpenCode) is the one that runs here.

Working on another machine is SSH plus cockpit-server, described in Remote hosts & VPS. That is unrelated to the Remote Pi relay: the mesh, the phone app and the 24/7 daemons belong to the Remote Pi project and are not part of Cockpit.

The cockpit CLI

Cockpit materializes a small binary at ~/.cockpit/bin/cockpit and puts that folder on the PATH of the terminals it spawns — and only those. So the CLI exists for anything running inside Cockpit (you, a script, an agent) and does not leak into the rest of your shell environment. It talks to the app over a local socket: a Unix socket on macOS and Linux, a loopback TCP port plus a token on Windows.

This is what makes Cockpit an agentic multiplexer: an agent in one tab can open another tab, type into it, read what it printed, run a project task, or query a database — the same verbs a human uses, with no screen scraping.

Targets & ids

The unit the CLI addresses is a tab (one terminal or agent session). A pane is the split leaf that groups tabs and is not addressable — list-panes and read-pane survive as legacy aliases.

Command reference

# open a worker tab beside you, then drive it
id=$(cockpit new-tab --cwd ~/proj --title Worker --split h)
cockpit send --tab-id "$id" --enter "npm test"

# read what it printed
cockpit read-tab Worker --lines 50

# run and follow a project task
cockpit list-tasks
cockpit read-task npm:dev --lines 80

# open a file in the viewer, query a database
cockpit open ~/.gitconfig
cockpit db query --db dev-local --sql "SELECT * FROM orders LIMIT 5"

Reading output

read-tab and read-task share a windowing model. Output is always chronological (top to bottom); the flags only pick which window you get.

Task ids are stable per workspace: npm:<script> from package.json, flutter:run / flutter:test, and json:<label> from .cockpit/tasks.json.

.ckp pane layouts

A .ckp file is a versionable YAML that describes the terminals to open in a workspace — the equivalent of a tmuxinator layout. One file is one layout, and the file name is the layout name (dev.ckp→ layout “dev”). Commit it, and a teammate gets your working geometry on clone.

There are three ways to apply one:

• GUI — right-click the .ckp file in the tree → Open layout.
• CLI — cockpit orchestrate dev.ckp from inside a tab.
• Worktree autorun — autorun: worktree in the file: the layout is applied by itself whenever you create a worktree of the workspace. The worktree is born empty, so the geometry comes out exact.

# dev.ckp — anywhere in the project; cwd is relative to this file
autorun: worktree        # optional
panes:
  - name: Frontend       # required, unique — becomes the tab's stable label
    cwd: frontend        # relative to this file, always with "/"
    command: claude      # optional: typed into the shell after the tab opens
  - name: Backend
    cwd: backend
    split: right         # tab (default) | right (side by side) | down (stacked)
    command: npm run dev
  - name: Sign
    cwd: .
    command: ./sign.sh
    platforms: [macos]   # optional: macos | windows | linux (string or list)

Fields

Root: panes (required) is the list of panes in creation order. autorun (optional) accepts only worktree; with two or more autorun files at the root, none of them runs — ambiguity is never guessed.

Replace semantics

• Opening a layout means become this layout: the file is validated first, then every tab of the workspace is closed (pinned ones included), then the panes are built with exact geometry. If any tab has work running (an agent mid-turn, a process in a terminal, a live task) the GUI asks before closing; idle tabs close silently.
• cockpit orchestrate dev.ckp replaces without asking and keeps only the tab that ran the command. Pass --append to keep the old additive behavior: panes whose name already exists are skipped and nothing is closed. The worktree autorun always appends (the worktree is born empty, so it makes no difference).
• A missing cwd or invalid YAML gives a readable error (dialog in the GUI, stderr in the CLI); nothing is applied halfway from the failing pane on.
• command is typed ~700 ms after the tab opens, so the shell has time to finish booting, with Enter at the end.

Cockpit treats .ckp as YAML for highlighting and shows the Cockpit logo as the file icon in the tree.

Task Run

Task Run executes your project's build and dev commands (npm run dev, flutter run, go run, make…) with streamed output, a visual lifecycle (play / stop / restart), interactive keys, and reload-on-save. Two sources coexist:

• Auto-detected — on opening a project, Cockpit reads the manifests (package.json scripts, pubspec.yaml) and shows tasks with no config at all.
• Declared — .cockpit/tasks.json, for customizing, adding tasks, or describing a monorepo. JSON tasks take precedence over a detected task with the same id.

Where the file lives

At the root of the workspace you open. Discovery is literal — Cockpit does not walk up the tree. For a single package, open the package folder. For a monorepo, open the root and let one .cockpit/tasks.json drive the subpackages through a per-task cwd.

The file is JSONC: comments (// and /* */) and trailing commas are allowed, just like VSCode's tasks.json. Point $schema at docs/tasks.schema.json for editor autocomplete; Cockpit ignores the field when running.

{
  "tasks": [
    {
      "label": "run",
      "cwd": "app",                 // relative to the tasks.json folder
      "command": "flutter",
      "args": ["run"],
      "kind": "watch",
      "interactiveKeys": [
        { "key": "r", "label": "Hot reload", "icon": "refresh", "primary": true },
        { "key": "R", "label": "Hot restart", "icon": "restart", "primary": true },
        { "key": "q", "label": "Quit", "icon": "stop" }
      ],
      "watch": {
        "paths": ["lib", "assets"],
        "ignore": ["build", ".dart_tool"],
        "onChange": "Hot reload",   // an interactiveKey label, or "__restart__"
        "debounceMs": 300
      },
      "progressPatterns": [
        { "begin": "Performing hot reload", "end": "Reloaded .* in .*ms" }
      ],
      "profiles": [
        { "name": "default" },
        { "name": "web", "args": ["-d", "chrome"] }
      ]
    },
    {
      "label": "api",
      "cwd": "backend",             // monorepo: another subfolder
      "command": "dart",
      "args": ["run", "bin/server.dart"],
      "kind": "watch"
    }
  ]
}

Fields

Root: tasks (required) and cwd (optional) — a default cwd for every task, which each task may override.

Databases

Connections live per workspace in .cockpit/databases.json, plus any SQLite files Cockpit auto-detects in the project. SQLite, Postgres, MySQL, SQL Server, Redis, and MongoDB open as tabs: a table view for SQL and Redis, a collection browser for MongoDB. A .dbq file is a saved query you can commit and re-run.

The same connections are reachable from the CLI, and the output is one JSON line — built to be parsed by an agent, not read by a human.

cockpit db list
cockpit db schema --db dev-local orders
cockpit db query --db dev-local --sql "SELECT * FROM orders LIMIT 5"
cockpit db run reports/daily.dbq

# non-SQL engines have their own verbs
cockpit redis --db cache --command "SCAN 0 COUNT 20"
cockpit mongo --db atlas --database shop --command '{"find":"orders","limit":5}'

# open the same thing visually for a human
cockpit redis browse --db cache
cockpit mongo browse --db atlas --database shop

Documents as tabs

Besides terminals, a Cockpit tab can be a document. Each one is a plain file in your repository, so git sees it, your agent can write it from the CLI, and nothing is locked inside the app. The Gallery panel, next to Database, has one card per document type: click it and the file is created at the workspace root and opened, on local and remote workspaces alike.

Notebook (.notebook)

A folder whose name ends in .notebook is a notebook: one .md per note, each with a shallow YAML frontmatter. Cockpit shows the folder as a single item in the tree and opens it as a notes tab. Outside the app it is an ordinary folder, so git, Obsidian and an agent in the terminal read the same files.

---
title: SSH tunnel on the host
tags: [relay, agent]
created: 2026-09-07T10:12
updated: 2026-09-07T11:40
---

Free markdown body.

The parser never throws: a file with no frontmatter, or with an unterminated ---, becomes a note whose body is the whole content. The app only rewrites the title, tags and updated lines, leaving the body and any other key untouched.

Notes are always editable, in a single mode: the markdown is painted live as you type while the markers stay visible, so the file remains plain markdown. It saves on its own about a second and a half after you stop typing (and on tab change or close), and ⌘S forces it. Pasting or dropping an image writes it to _assets/ inside the notebook. [[Note title]] in the body becomes a clickable chip, creating the note if it does not exist, and each note lists its backlinks at the bottom.

cockpit note add notes.notebook --title "SSH tunnel on the host" --tag relay   --body "The host opens the tunnel, not the client."

# read the body from stdin, and list what is there
cockpit note add notes.notebook --title "Session summary" --body - <<'NOTE'
Everything that changed today.
NOTE
cockpit note list notes.notebook

HTTP requests (.http)

A .http file is a request tab: editor on one side, response on the other. The syntax is the one the REST Client and JetBrains HTTP Client use, so files you already have work here: ### separates requests, @name = value declares a variable and {{name}} interpolates it. Run the request under the cursor with ⌘↵ and read the response as JSON, as headers or as raw text.

@base = https://api.example.com
@token = a-token-for-this-file

### list users
GET {{base}}/users
Authorization: Bearer {{token}}

### create one
POST {{base}}/users
Content-Type: application/json

{ "name": "Ada" }

The agent runs the same file through the CLI, and gets one JSON line back. A 4xx or 5xx is a normal response, so it should check status rather than the exit code.

cockpit http list api/users.http
cockpit http run api/users.http --request "list users"

Boards, diagrams and windows

• Kanban: a .kanban markdown file renders as a board, with dependencies between cards (blockedBy, plus blocked and ready filters), a title and label filter, drag and drop in list mode, markdown in comments, and a hold on the advance arrow to send a card straight to the last column.
• Mermaid: a ```mermaid fence renders as a diagram in the markdown preview, offline, in your theme. Prefer it over ASCII art when an agent explains a flow.
• Document window: open any file in its own light window from the app, or straight from the operating system. Double-click a .kanban, .notebook, .ckp, .dbq, .http or a markdown file in Finder, in Explorer or in your Linux file manager, and Cockpit opens it, forwarding the path to the instance you already have running.

Workspace environment (.env.cockpit)

A plain KEY=VALUE file named .env.cockpit at the workspace root is injected into every terminal Cockpit opens there: every root of a multi-root workspace, and remote workspaces too, where the host reads its own copy right before spawning the shell. Put the tokens your agents need there instead of pasting them into a prompt. New tabs pick up changes, and Restart reloads an existing tab in place.

OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
DATABASE_URL=postgres://user:pass@localhost/app

Redaction

Values injected from the file are replaced by *** before the output reaches the emulator, which covers the screen, the saved scrollback and cockpit read-tab at once. An agent reading another tab does not read your secrets back.

Out of scope, on purpose: a value that the program re-encodes (base64, for instance) or splits with ANSI escapes, and the file itself, which is an ordinary file that anything with your permissions can read.

Keys that are never injected

Keys that change who runs what are ignored, so a file that arrives with a repository cannot redirect the programs your shell starts:

PATH  SHELL  HOME  ZDOTDIR  BASH_ENV  ENV  PROMPT_COMMAND  IFS  LD_*  DYLD_*

On top of that, when the .env.cockpit is tracked by git (so it came with the repository, it is not yours), new terminals print a notice listing the key names it injected, never the values. The Gallery card that creates the file also keeps it out of git.

A personal and a work account, side by side

Claude Code and Codex read their whole account (credentials, settings and history) from a directory you can point somewhere else, and Cockpit injects those variables per workspace like any other. That is the recipe for separate accounts: no extra feature, one line per workspace.

CLAUDE_CONFIG_DIR=/Users/me/.claude-work
# Codex uses its own variable
CODEX_HOME=/Users/me/.codex-work

Restart the tabs (or open new ones), run claude and log in once with /login. From then on that workspace uses that account, and your other workspaces keep the default one. Use absolute paths: the variables name a directory, not a profile.

Themes

Cockpit ships nine built-in themes — cockpit, cockpit.2, violet, violet.2, midnight, rose, sun, flexoki and pantera — each with a light and a dark variant. Beyond those, a theme is a single JSON filethat paints all three layers at once: the app UI, the code viewer's syntax highlighting, and the terminal palette.

The theme file

• Import with Settings → Appearance → Theme → Import…
• Themes live in <data folder>/themes/(the same root as the “Storage” setting), one file per theme, named after its id. Copying a .json in there installs it too.
• Export produces a complete file (every token, no extends) — a good starting point for hand editing.

{
  "$schema": "https://raw.githubusercontent.com/jacobaraujo7/remote_pi/main/cockpit/docs/theme.schema.json",
  "id": "acme.aurora",
  "name": "Aurora",
  "author": "Acme",
  "version": "1.0.0",
  "extends": "cockpit",
  "variants": {
    "dark":  { "ui": {}, "syntax": {}, "terminal": {} },
    "light": { "ui": {}, "syntax": {}, "terminal": {} }
  }
}

Inheritance is the point. Every token you do not declare comes from the base, so a useful theme can be five lines long:

{
  "$schema": "https://raw.githubusercontent.com/jacobaraujo7/remote_pi/main/cockpit/docs/theme.schema.json",
  "id": "acme.violet",
  "name": "Violet",
  "variants": {
    "dark":  { "ui": { "accent": "#8B5CF6", "accentSoft": "#8B5CF633", "accentText": "#C4B5FD" } },
    "light": { "ui": { "accent": "#7C3AED", "accentSoft": "#7C3AED22", "accentText": "#5B21B6" } }
  }
}

Colors are CSS-style hex — #RGB, #RRGGBB or #RRGGBBAA, alpha last. It is not Dart's 0xAARRGGBB. On a bad import the parser points at the field path that broke (variants.dark.ui.accent), and validation runs before the copy, so an invalid file never reaches the themes folder.

Tokens

Text drawn on top of accent and erroris not a token: it is derived from the color's luminance, so a light accent automatically gets dark text.

syntax.background has a special default. The code viewer, the editor, and the terminal are all content inside a tab, so they share the field: when a theme declares neither syntax.background nor terminal.background, the three follow ui.panel of this theme, not of the base. Declare the field if your code palette needs a surface of its own.

The $schema URL lives in the repository, versioned next to the code that implements it, so the app and the schema can never drift apart. Cockpit ignores the field when reading a theme — it only serves your editor. See theme.example.json for a commented file with every group filled in.

Agent turn status

When an agent runs in a tab, Cockpit shows whether it is working, waiting for you, or idle — as a spinner, a badge, a chime, and an OS notification when the window is unfocused. Supported harnesses today: Claude Code and Codex CLI (0.147+).

How it works:

1. At boot, Cockpit materializes the internal CLI at ~/.cockpit/bin/cockpit and registers cockpit hookon the harness' lifecycle events.
2. On each event the harness runs the hook, passing a JSON payload on stdin.
3. The hook translates it into a status and sends it to the app over the local socket. (A socket rather than an escape sequence on the PTY: harnesses run hooks with no controlling terminal, and writing to /dev/tty fails with ENXIO.)
4. Routing is by the COCKPIT_PANE_ID env var, which the app injects into the tab's PTY. An agent session started outside Cockpit does not have it, so the hook is a no-op there. Nothing to configure, nothing to disable.

Both installers do an idempotent append of a marked entry (_cockpit: v1): re-running removes our old entry and re-adds it, never rewriting the list — your own hooks, and those of plugins or iTerm2, survive untouched.

Event mapping

Two asymmetries matter. On Claude, tools that block waiting for the user (AskUserQuestion, ExitPlanMode) emit no Notification; the last hook before the block is PreToolUse, so that one maps to waiting for those two — otherwise the tab would spin forever with no chime. On Codex, approval has its own event, so there is no text heuristic and no detour.

Resuming a session

Cockpit persists the session_id that arrived through the hook, and on restoring the tab it types the command that reattaches the conversation. A session id alone does not say which harness it belongs to, and the commands differ — claude --resume <id> versus codex resume <id> — so the installer registers the hook as cockpit hook --harness <name> and the layout stores the harness next to the id. Entries written by older versions pass no flag and are assumed to be Claude, which is what they all were.

Remote hosts & VPS

A remote workspace is a folder on another machine, reached over SSH. Cockpit runs a small headless cockpit-server on the host, talks to it through an SSH tunnel to a Unix socket, and nothing is ever exposed on the network: SSH is the only door. Terminals and agents keep running on the host when you disconnect, and the next connection picks them up where they were.

From the desktop app you usually need nothing on the host: Cockpit uploads the server over SSH on first connect and keeps it updated (it compares a manifest of the installed files with the bundle it ships and reinstalls when they differ). The mobile apps (iPad, Android) carry no server, so a host you want to reach from them must be prepared once, either by a desktop or with the installer below.

The desktop can only install the targets it ships, so the installer is also the way in for the other combinations:

Both paths land in the same place and recognize each other: a host prepared with the installer is reused as is by a desktop that ships the same version, and a host prepared by a desktop can be updated later with the installer. Whoever gets there first installs; the other one just connects.

Install the server

Linux x86_64 and arm64. User space, no sudo, idempotent; re-run it to update.

curl -fsSL https://remote-pi.jacobmoura.work/cockpit-server.sh | bash
# or straight from GitHub (the URL above redirects here):
curl -fsSL https://raw.githubusercontent.com/jacobaraujo7/remote_pi/main/cockpit/install-server.sh | bash

The script detects the architecture, downloads cockpit-server-<version>-linux-<arch>.zip from the GitHub release, verifies its SHA-256 and runs the install.sh shipped inside the zip. That installs to ~/.cockpit/server (the same layout the desktop app uses), links the binary into ~/.local/bin, checks every file against bundle.manifest and does a smoke start before swapping the new version in. A host without internet access can take the zip by scp and run ./cockpit-server/install.sh directly.

Start at boot

By default the app starts the server on demand and it exits when idle with no live session; terminals and agents keep the server alive while they run, so most hosts need no service. Note that if you kill the server while a Cockpit workspace is open on it, the client treats that as a dropped connection and starts it again. For a dedicated VPS you can register a systemd --user unit: the server is up right after a reboot, never exits on idle, and systemd restarts it on failure. It does not change how the app connects, and a reboot still ends the sessions that were running.

# at install time
curl -fsSL https://remote-pi.jacobmoura.work/cockpit-server.sh | bash -s -- --service

# or later (the installer links cockpit-server into ~/.local/bin)
cockpit-server service install
cockpit-server service status
cockpit-server service uninstall

The unit lives in ~/.config/systemd/user/cockpit-server.service. Starting at boot without an open SSH session requires linger; the command tries to enable it and, when that needs root, prints the one-line sudo loginctl enable-linger for you to run once. Updates restart the unit automatically. To stop it for real use systemctl --user stop cockpit-server (a plain kill is undone by systemd in two seconds).

Troubleshooting

• version_mismatch: the host runs another release than the app. Re-run the installer (mobile) or reconnect from a desktop, which reinstalls.
• cockpit-server did not start during install: the log printed above the error is the reason. A glibc older than the build expects is the usual cause on old distributions; check ldd --version.
• Socket permission: the server listens on ~/.cockpit/cockpit-server.sock as the SSH user; connect with the same user that ran the installer.
• Updating means restarting: a new server version replaces the running process, which ends the terminals and agents on that host. The desktop does it silently when its bundle differs from the host; the installer does it when you run it with a newer release. Finish long jobs first.
• Nothing after reboot: without the service the first connection starts the server (a second or two); with it, check cockpit-server service status and linger.

Sounds & notifications

Turn status drives audio too. Under Settings → Notifications you can bind a sound per event — turn done, action needed, error — pick a custom audio file for each, and set the volume. With the window focused you get the chime; unfocused, an OS notification. Since an agent started outside Cockpit never reports status, nothing fires for sessions the app is not hosting.

Language

Cockpit's interface is fully localized in English, Portuguese (Brazil) and Spanish, down to the native application menu. Switch it in Settings → General → Language; the choice is independent of the OS locale.

Links

• Cockpit product page — the tour.
• Tutorial: layouts and tasks — build a .ckp and a tasks.json from scratch.
• Tutorial: an agent team in Cockpit.
• Remote Pi docs — mesh, relay, daemons, pairing.
• Source docs & JSON schemas in the repository.
• GitHub — issues and source.