The clackatoo command

9 min read

clackatoo [--font <FAMILY>] [--font-size <POINTS>] [--renderer <API>] [--remote <HOST>]
clackatoo <COMMAND> [OPTIONS]

With no command, clackatoo opens the window, starting the daemon first if none is running. With --remote, the daemon is on another machine.

On failure, every command prints clackatoo: <what went wrong> to stderr and exits with status 1.

daemon #

clackatoo daemon [--scrollback-compaction <WHEN>]

Runs the daemon in the foreground until interrupted. Its log goes to stderr, at the level RUST_LOG sets (default info). Terminals live exactly as long as the daemon does: when it stops, their programs are hung up. Upgrading it doesn't stop it.

CLACKATOO_AGENT sets the agent chats talk to: a command speaking ACP, split at spaces. By default it's Claude Code's adapter, run with npx.

CLACKATOO_UDP_PORTS sets the UDP ports connections from other machines may move onto: a port, a range such as 60000-61000 (the default), or off.

The daemon keeps its files in a per-user runtime directory: $XDG_RUNTIME_DIR/clackatoo/, or /tmp/clackatoo-<uid>/ if XDG_RUNTIME_DIR is unset.

Anyone who can connect to the socket can run commands as you, so the directory must be accessible only by you. The daemon creates it with mode 0700, and refuses to start if it exists with any group or other permissions, or belongs to someone else.

Unix socket paths are limited to about 100 bytes. A very long XDG_RUNTIME_DIR makes the daemon fail with "path must be shorter than SUN_LEN".

A daemon the window starts runs in the background, with its log in daemon.log in the runtime directory.

upgrade #

clackatoo upgrade

Moves the running daemon onto this build of clackatoo without stopping it. Its terminals, the programs in them, their history and the workspaces all carry on. Run it after building or installing a new clackatoo.

The daemon replaces its own program with this one, keeping its process, so the programs in its terminals stay its children. It hands its state over as it goes: everything on screen and in history, the cursor and modes, workspaces and tabs. Every connection drops for a moment. Windows on this machine reconnect by themselves; windows on other machines say the connection was lost, and Enter reconnects them. Recordings stop.

Before handing anything over, the daemon checks that the new program is a clackatoo that can take over from it. If it isn't, or starting it fails, the daemon carries on as it was, and upgrade says why; the daemon's log has the details. A daemon won't upgrade to an older build. Daemons from before protocol 11 can't upgrade at all: upgrade says so, and clackatoo stop is the way to replace them, closing their terminals.

stop #

clackatoo stop

Stops the daemon, closing every terminal and hanging up their programs. It works on a daemon from any build of clackatoo, which matters because a build refuses to talk to a daemon speaking another version of the protocol: other commands then fail with "the daemon is from another version of clackatoo", and suggest clackatoo upgrade where the daemon can upgrade. If no daemon is running, stop says so and succeeds.

config #

clackatoo config [<NAME> [<VALUE>]] [--unset <NAME>]

Shows or changes the window's settings in client/startup.toml:

• With no arguments, prints every setting as the file would hold it, with those the file doesn't set commented out at their defaults.
• With a name, prints that setting's value, without quotes, so scripts can use it.
• With a name and a value, sets it. The value is checked first: clackatoo config renderer metal fails, saying which values renderer takes.
• With --unset, removes the setting, so it takes its default.

Changes keep the rest of the file, comments included, as it was, and the file is replaced all at once, so a window starting at the same moment reads either the old file or the new one.

language #

clackatoo language list
clackatoo language install <NAME>... | --all

The languages files are parsed and coloured in. Each is a pack in ~/.local/share/clackatoo/languages (or $XDG_DATA_HOME/clackatoo/languages).

• list lists the languages clackatoo knows where to get, with where each comes from, marking those installed, then any other packs installed.
• install downloads each language's grammar and highlight queries, with curl, from the grammar's own repository, at the version clackatoo was tried with, and checks each file is exactly what was tried. --all installs every language list lists. Installing one again replaces it.

Files opened after a language is installed are parsed in it. A file that was already open is parsed once a window attaches to it again, as when the window is next opened.

bridge #

clackatoo bridge [--replace]

Passes everything on its standard input to the daemon, and everything the daemon sends to its standard output, starting the daemon first if none is running. It exits when either side hangs up. --remote runs it on the other machine through ssh; see another machine.

Client commands #

The other commands talk to a running daemon. Each accepts:

Terminals are named by the number new prints and list shows. Numbers are never reused while the daemon runs.

list #

clackatoo list

One line per terminal: its ID, the PID of its program (- for a chat, which has none), its size, its status (running, exited (<code>) or killed (signal <n>)), and the window title its program set.

new #

clackatoo new [--size <COLSxROWS>] [--cwd <DIR>] [--record <FILE>] [-- <COMMAND>...]

Starts a terminal and prints its ID.

What a program sees in its environment is described in terminal emulation.

edit #

clackatoo edit <PATH>

Edits the file at PATH, from the current directory, in a new tab of the workspace last used, or in a new workspace if there are none. A file already being edited gets another pane on it. The window doesn't switch to the new tab yet.

run #

clackatoo run <TERMINAL> <WORDS>...

Types the words, joined with spaces, into the terminal, then presses Enter (a carriage return, \r).

send #

clackatoo send <TERMINAL> <TEXT>

Types TEXT exactly as given, without pressing Enter. To send control keys, use your shell's escapes: \e (Escape) or \r (Enter) in fish, $'\e' in bash. Fails if the terminal's program has exited.

capture #

clackatoo capture <TERMINAL> [--ansi]

Prints what the terminal is showing: one line per row, without trailing spaces or trailing blank lines. With --ansi, colours and attributes are kept as escape sequences, so printing the result in another terminal reproduces the screen. A terminal whose program has exited still shows its last screen.

resize #

clackatoo resize <TERMINAL> <COLSxROWS>

Changes the terminal's size, such as clackatoo resize 1 120x40. Its program is told (the kernel sends it SIGWINCH), and lines on the screen are rewrapped to the new width. A recording started with new --record stops here, because a recording has a single size.

close #

clackatoo close <TERMINAL>

Closes the terminal and forgets it. Its program is hung up (sent SIGHUP by the kernel), as when a terminal window closes.

ping #

clackatoo ping [--count <N>] [--interval <MS>]

Times how long the daemon takes to answer, and how long a key takes to come back from a program, which is most useful with --remote. It starts a terminal of its own running cat, and for each round:

1. waits, then times a request that does nothing, which is what the connection costs;
2. waits again, then times a key, from sending it to the update that shows cat's echo, which is what typing costs.

With --remote, each round also says whether it went over UDP or through ssh. To the same machine, where the network costs next to nothing:

$ clackatoo ping --remote localhost --count 5
connected to localhost in 146.1 ms
PING localhost: a request, then a key echoed by cat
round 1: request 0.168 ms, key echo 0.216 ms (over UDP)
round 2: request 0.147 ms, key echo 0.226 ms (over UDP)
round 3: request 0.158 ms, key echo 0.187 ms (over UDP)
round 4: request 0.147 ms, key echo 0.187 ms (over UDP)
round 5: request 0.151 ms, key echo 0.178 ms (over UDP)

--- localhost ping statistics ---
request   min 0.147 ms, median 0.151 ms, p90 0.168 ms, max 0.168 ms
key echo  min 0.178 ms, median 0.187 ms, p90 0.226 ms, max 0.226 ms

The connection time includes ssh logging in. When it's done, ping closes its terminal.

Edit this page