Shell integration

Let zsh or bash report command ends, exit codes and the working directory to kaiport, for precise AI Pilot results and the directory in the status bar.

On this page

What it is
What it improves
Check whether it's active
Enable it permanently
zsh
bash
Enable it for one session
Without shell integration
Other shells

With shell integration, your shell tells kaiport exactly where a command ends, which exit code it returned and which directory you're in. It takes a few lines in your shell's startup file on the server. Without it, kaiport recognizes the prompt heuristically – that works in most cases, but it's less precise and can't report exit codes.

What it is

Shell integration consists of invisible escape sequences that the shell prints around its prompt. kaiport reads two kinds:

Sequence	What it reports
OSC 133	Marks for the prompt (`A`), the start of a command (`C`) and the end of a command together with its exit code (`D`).
OSC 7	The current working directory, as a `file://` address.

The terminal doesn't display these sequences; you won't see them in the output.

What it improves

	With shell integration	Without
End of a command for AI Pilot	Exact: the shell reports it.	Guessed from quiet output and a line that looks like a prompt.
Exit code	AI Pilot gets it for every command; the step shows, for example, `exit 0`.	Unknown. When AI Pilot needs it, it can append `; echo "exit=$?"` to a command.
Working directory in the status bar	Shown (zsh snippet).	Not shown.

When you expand a command step in AI Pilot, it shows Detection: shell integration or Detection: heuristic. See AI Pilot in the terminal.

Notifications for long commands and the command history don't depend on shell integration. They use the prompt recognition either way.

Check whether it's active

The status bar shows the badge Shell integration as soon as kaiport has received the first mark in this session. It stays for the rest of the session.
In the header of the AI Pilot panel (⌘JCtrlJ), the plug icon turns green. Its tooltip reads Shell integration active, otherwise Set up shell integration.

Click the plug icon to open a popover. Its heading says Shell integration active or Shell integration not detected, followed by a short explanation, the snippet for zsh and two buttons: Copy snippet and Enable for this session only. The plug icon is there even if you haven't set up an AI provider yet.

Enable it permanently

Add the lines for your shell to its startup file on the server. Then open a new session, for example with Reconnect ⌘RCtrlR.

zsh

Add these lines at the end of ~/.zshrc. Copy snippet in the popover copies the same lines.

zsh

# kaiport shell integration (OSC 133 + working directory)
autoload -Uz add-zsh-hook
__kaiport_precmd() { printf '\e]133;D;%s\a\e]133;A\a' "$?"; printf '\e]7;file://%s%s\a' "$HOST" "$PWD"; }
__kaiport_preexec() { printf '\e]133;C\a'; }
add-zsh-hook precmd __kaiport_precmd
add-zsh-hook preexec __kaiport_preexec

add-zsh-hook adds the two functions next to hooks that are already there, so the snippet works together with oh-my-zsh, powerlevel10k or Starship.

bash

Add these lines at the end of ~/.bashrc:

bash

__kaiport_precmd() { printf '\e]133;D;%s\a\e]133;A\a' "$?"; }
PROMPT_COMMAND="__kaiport_precmd${PROMPT_COMMAND:+;$PROMPT_COMMAND}"

The bash version reports the end of each command and its exit code. It doesn't report the working directory, so the status bar stays without a directory unless your bash setup sends OSC 7 in some other way.

Enable it for one session

To try shell integration without changing any file:

Open the AI Pilot panel with ⌘JCtrlJ.
Click the plug icon in its header.
Click Enable for this session only.

kaiport types a one-line version of the zsh snippet into the terminal, runs it and clears the screen. The button is only available while the session is connected. This works in zsh only, and only until the session ends – after a reconnect the new shell starts without it. The line begins with a space, so zsh doesn't save it in the history if the option HIST_IGNORE_SPACE is set.

Without shell integration

kaiport keeps its own copy of the screen for every session. Without shell integration, it considers a command finished when the output has been quiet for about half a second and the cursor sits on a line that looks like a prompt:

lines that end with a typical prompt character such as $, #, %, >, ❯, ➜ or λ, or with a Powerline separator as drawn by agnoster and powerlevel10k
lines that start with a prompt symbol like ➜ or ❯, as in oh-my-zsh or Starship
patterns like user@host:~$ or [user@host dir]$
the prompt kaiport saw when the session first became idle

If a command prints nothing for about four seconds and no prompt appears, AI Pilot treats it as still running or waiting for input – a password, for example – and looks at the screen. With shell integration active, kaiport waits a moment longer for the end mark before it falls back to the heuristic.

The heuristic can get it wrong when a prompt doesn't end with a typical character, or when a program prints lines that look like a prompt. Shell integration solves both.

Other shells

kaiport doesn't care which shell sends the sequences: OSC 133 marks switch on shell integration, and an OSC 7 directory shows up in the status bar, whatever shell prints them. Ready-made snippets exist for zsh and bash only.