Shell integration

An ordinary terminal has no idea what’s going on inside it. It sees bytes. “Is something running?”, “what command is that?”, “did it fail?” — none of that is in the stream. Shell integration fixes that: TYBA injects a handful of hooks into the session’s shell, and the shell starts reporting where it is — prompt started, command started, command finished with this exit code, the directory changed. Settings → Code → Shell integration. It ships on.

​

What you get

Without it, an idle session and a session that’s been compiling for three minutes look identical.

​

It doesn’t touch your dotfiles

TYBA writes the integration files into a temporary directory that’s yours alone — created with 0700 permissions, verified on every use (right owner, nobody else gets in) — and points that session’s shell there, via an environment variable. Its files start by sourcing yours, and only then install the hooks. The consequence: your configuration runs in full, in its usual order, and TYBA comes in last. If it fails, your shell carries on — the hooks were written not to take the session down, not even under set -e. It’s the same pattern VS Code and iTerm2 use. Uninstalling TYBA leaves no residue anywhere: there is no residue to leave.

​

Where it works

TYBA uses the system’s $SHELL — there’s no configurable default shell. If you want the hooks, the way there is having zsh or bash as your shell.

​

This is not what gives agent sessions their status

They’re two different channels, and it’s worth not mixing them up: The agent reports on its own: the tool about to run becomes Running, the end of a turn becomes Idle, a request for an answer becomes AwaitingInput. It’s the same channel as the approvals inbox, and it exists independently of your shell — see how TYBA talks to the agent. What shell integration does give agents is something else: detecting an agent running inside an ordinary shell. You typed claude in a shell pane — TYBA finds that out from the command line the shell reports, and it’s the integration doing the reporting.

​

Turning it off

Settings → Code → Shell integration, toggle off. It applies to new sessions — the hooks go in when the shell is born, so sessions already open stay as they are until you open another. A legitimate reason to turn it off: your shell has an exotic config and something started behaving strangely — a duplicated prompt, PROMPT_COMMAND fighting back, a plugin that doesn’t like company. Turning it off is the two-line test for whether TYBA is to blame. What you lose:

​

See also