three invisible signals
Your shell tells kolu what's happening.
Every kolu terminal runs your shell: your prompt, your plugins, your aliases, your dotfiles, replayed exactly as a normal terminal would. On top of that, kolu adds a thin layer of shell integration, so a terminal can say things about itself that a stream of bytes cannot.
The layer is the same trick VS Code, Ghostty and Kitty use. Your shell prints invisible escape sequences (OSC sequences, in terminal jargon) that never render on screen but tell the terminal’s owner what is going on inside. kolu’s terminal daemon reads them on the host the terminal runs on.
The three signals
| signal | your shell prints it | kolu uses it for |
|---|---|---|
| Working directory (OSC 7) | at every prompt | the directory and git branch on the dock and tile, repo grouping, and restoring a terminal into the directory it was in |
| Title (OSC 0/2) | your directory at the prompt, the command while one runs, and whatever a full-screen app sets | tile and dock titles, and the nudge that the foreground process may have changed |
| Command marks (OSC 633;E) | the exact command line, the moment you run it | agent detection for shimmed CLIs, as a sensor only |
The command mark carries the most, but only as a sensor. It is how kolu knows an
agent installed through npm is codex and not the node the operating system
reports.
It is deliberately not what sleep, wake and session restore type back into a fresh shell. Anyone whose text you display can print that escape sequence, so the mark can name a process but never supply a command. A resume replays the live agent process’s own allowlisted arguments and its session file’s identity instead. A terminal whose agent launch was never marked still detects and resumes fine: the mark is a convenience for shimmed CLIs, not a requirement.
How it gets into your shell
kolu never edits your dotfiles. Each terminal starts from a small wrapper that first replays your own startup files untouched, then appends kolu’s hooks. So anything your dotfiles set (prompt frameworks, direnv, zoxide, PATH edits) runs first and wins any fight over appearance.
- In zsh, the hooks ride the shell’s native
preexecandprecmdhook arrays, which are designed to be shared. kolu’s entries sit alongside starship’s or atuin’s without either noticing the other. - In bash, which has no native hooks, the command mark rides
PS0, a prompt string bash expands at the exact moment it accepts a command. It is deliberately not theDEBUGtrap: that trap is a single global slot, which popular history tools (atuin, and anything built on bash-preexec) take over for themselves.PS0has no contenders, so kolu’s marks and your history tooling coexist.
The slot matters most for the first command of a shell, which is where agents get launched.
Limits
- bash before 4.4 (macOS’s stock
/bin/bashis 3.2) has noPS0, so there are no command marks. Directory and title still work. The bash a Nix or Homebrew environment puts first onPATHis modern and fully covered. - fish and other shells get no wrapper. kolu still sets the environment up front, but directory, title and command signals only flow if the shell or its plugins emit them. Agent detection falls back to process names.
- An agent launched as the terminal’s root process (
kaval-tui create -- codex, or an agent-created terminal) needs none of this. There is no shell in that terminal, and kolu remembers the exact spawn command instead.
Nothing in this layer leaves your machines. The sequences travel inside the terminal’s own byte stream to kaval, the daemon that owns the terminal on that host, and become part of the same session record your terminals already live in.