kolu
Docs

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

signalyour shell prints itkolu uses it for
Working directory (OSC 7)at every promptthe 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 setstile 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 itagent 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 preexec and precmd hook 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 the DEBUG trap: that trap is a single global slot, which popular history tools (atuin, and anything built on bash-preexec) take over for themselves. PS0 has 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/bash is 3.2) has no PS0, so there are no command marks. Directory and title still work. The bash a Nix or Homebrew environment puts first on PATH is 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.

Next