Getting started

clackatoo is a terminal workspace: a terminal emulator that grows into a place to work, with an agent harness built in. Its first priority is to be very fast and very light.

The daemon owns the terminals #

Most terminal emulators are one program: close the window and your shells die with it. In clackatoo, a background daemon owns every terminal. That means the pseudo-terminal each program runs on (its PTY), the program itself, and the grid of characters its output builds.

Everything else is a client of the daemon and talks to it over one protocol: the window, the clackatoo command, and later agents. Clients can be on another machine, reaching the daemon through ssh. Because the daemon owns the terminals:

• closing a window closes nothing, and reopening it brings everything back;
• a script can do anything a window can, because it uses the same requests;
• an agent is just another client. It can start terminals, type into them and read their screens.

The daemon is one thread waiting on every PTY and connection at once. A program's output goes straight from its PTY into the grid on that thread, with no locks and no handoff between threads.

What exists today #

The daemon; a window that shows workspaces of tabs and split panes, with Vim-like modes for scrolling, selecting, copying and searching, and a command line for opening panes; and a command-line client that can start terminals, type into them, show their screens and close them. Both clients work with a daemon on another machine. The quick start walks through both.

clackatoo runs on Linux.

Build it #

clackatoo is a Cargo workspace. Build the clackatoo command in release mode:

cargo build --release -p clackatoo

The binary is target/release/clackatoo.

Open a window #

clackatoo --font "JetBrains Mono"

That opens a window on your shell, starting the daemon in the background if it isn't running. Leave out --font for your system's monospace font, or choose one for good with clackatoo config font "JetBrains Mono". Close the window and the shell keeps running; open another and you're back.

Ctrl+; switches to normal mode, where you scroll, select and search history with Vim's keys, and i switches back. From normal mode, :| Enter splits the pane with a new terminal on its right, :- below it, and :Terminal opens one in a new tab. Ctrl+H, Ctrl+J, Ctrl+K and Ctrl+L move between panes, and :1, :2 and so on between tabs. The window has all its keys.

Start the daemon yourself #

clackatoo daemon

To watch the daemon's log, run it in the foreground instead. It logs to stderr; set RUST_LOG=debug for more detail. Only one daemon runs per user: a second one refuses to start. Stopping the daemon (Ctrl-C, or clackatoo stop) hangs up every terminal it owns.

Drive a terminal #

From another terminal, start one. new prints the new terminal's ID:

$ clackatoo new
1

It runs your $SHELL in the current directory, at 80×24. Type a command into it and press Enter with run:

clackatoo run 1 ls --color=always

See what it shows with capture. Add --ansi to keep the colours:

clackatoo capture 1 --ansi

send types text without pressing Enter, which is how you drive full-screen programs:

clackatoo run 1 htop
clackatoo send 1 q

List terminals, and close one when you're done:

clackatoo list
clackatoo close 1

Closing a terminal hangs up its program, as closing a terminal window would. A terminal whose program exits stays listed, with its exit status and last screen, until you close it.

From another machine #

With clackatoo built on both machines, and ssh able to log in to the other one without asking for anything:

clackatoo --remote desktop

That opens a window on desktop's workspaces, starting the daemon there if it isn't running. Every command takes --remote too, as in clackatoo list --remote desktop. If ssh's commands on the other machine can't find clackatoo, another machine explains how to point at it.