awareness
kolu knows what your agents are doing.
kolu watches the foreground process of every terminal. When that process is a coding agent it knows, kolu reads that agent’s own session on disk to tell whether it is thinking, running a tool, waiting on you, or done.
There is nothing to configure. Run a supported agent in any terminal and its tile, dock row and minimap light up, whether the agent came from Settings → Agents or you installed it yourself.
| Agent | Command |
|---|---|
| Claude Code | claude |
| Codex | codex |
| Grok Build | grok |
| OpenCode | opencode |
| Pi | pi |
| Xyne | xyne |
| Oh My Pi | omp |
One state vocabulary
Every agent folds onto the same small set of states, drawn with the same glyphs everywhere kolu shows agent status. What each state asks of you, and where it shows up, is on notifications.
Some states cannot come from the session file. A multiple-choice question or a permission gate is often not written to disk while it is pending. For those agents kolu matches the prompt on the rendered screen instead, on the server, so it works for background, mobile and remote terminals too.
Before the first prompt
kolu sees the agent’s program the instant it starts. Most agents write no session until you first prompt them, and Oh My Pi not until its first reply is finished. Between those moments the terminal shows one of three states:
| State | Indicator | Meaning |
|---|---|---|
| Starting | the agent’s mark, no glow | the program is up and its screen is still being drawn |
| Ready | the agent’s mark, no glow | its screen has settled and nothing has been submitted to it |
| Working | the agent’s mark, working glow | you submitted a prompt and the agent has written nothing yet |
An agent is ready once it has printed nothing for about five seconds. Starting and Ready ask nothing of you, so neither raises a badge, a count or a needs-you entry anywhere.
Working starts from the Enter you press. A submit is a typed Enter: a newline inside a paste, or Alt + Enter, is a line of your input. If the screen settles again with nothing written, the agent is Ready once more. The session, once written, replaces all three with the agent’s real state.
How detection works
The pipeline is the same for every agent. Only the last step differs, because each agent keeps its sessions in its own store.
kolu asks each terminal for its foreground process id, matches it against the known agents, and reads that agent’s session from disk. A JSONL transcript is tailed; a SQLite database is queried, with a watch on its write-ahead log for live updates. In a shell terminal the shell prints a marker naming each command as it runs, part of kolu’s shell integration.
Two cases need more than that marker. When an agent is the terminal’s root
process, with no shell around it (kaval-tui create -- codex), kolu uses the
command the terminal was spawned with. A nixpkgs-wrapped binary runs as a
dynamic loader (ld-linux…, ld-musl…, ld.so) with the real program as its
first argument, so kolu recognizes the program the loader loads, which is how
opencode is found.
When several agents share a directory
Claude Code, Grok and Oh My Pi tie a conversation to one terminal: the first two by process id, Oh My Pi by writing a breadcrumb naming the terminal. Codex, OpenCode and Pi record no process id. The only thing on disk linking their conversations to a terminal is the working directory, which two agents in one repository share.
For those three, kolu treats “most recently updated here” as a shortlist, and
hands each terminal a conversation no other terminal holds. A terminal keeps it,
so a second Codex in the same repository cannot take the rows around it. A
conversation started inside a running agent (its /new) looks like someone
else’s, so the tile stays on the previous one until you exit the agent.
What a resume may carry
Resuming a conversation after a sleep or restart is built from three facts kolu holds, never from a command line a shell printed:
| Fact | Where it comes from |
|---|---|
| which agent | the detection adapter that matched this terminal’s foreground process |
| which conversation | the agent’s own session file, plus its process or its breadcrumb |
| which flags | the live agent process’s arguments, filtered through the agent’s allowlist |
The filter is an allowlist. Anyone whose text you display can print the escape
sequence a shell marks commands with, so a captured line never becomes a command
kolu types. Only flags the agent’s own package declares as launch shape come
back. A flag such as --model carries its value:
| The live process runs | Wake replays |
|---|---|
claude --plugin-dir P --resume <id> --dangerously-skip-permissions | claude --resume <id> --dangerously-skip-permissions |
omp -e P --resume <path> --model fable | omp --resume <path> --model fable |
ld-linux… …/opencode --standalone --session <id> --model sonnet | opencode --session <id> --model sonnet |
An environment prefix you type in the shell (FOO=1 claude) is not replayed,
because it lives in the typed line rather than the process’s arguments. Put the
variable in your shell profile or in an agents profile. The
AI_PROFILE that kolu’s own agents feature sets does come back. A terminal
kolu cannot build a resume for wakes to a bare shell, and padi’s log says so.
Claude Code
kolu finds a Claude session by checking whether
~/.claude/sessions/<foreground-pid>.json exists, then tails its JSONL
transcript. The tile shows the session’s title, model and token count, read from
the newest assistant message. Claude writes its transcript only with the first
exchange, so an unprompted Claude reads
starting, then ready.
| State | Read from |
|---|---|
| Thinking | an API call is in flight |
| Tool use | Claude is executing tools |
| Running in background | Claude ended its turn while a dynamic workflow it launched is still running |
| Awaiting input | an AskUserQuestion prompt or a tool-permission gate on the rendered screen |
| Waiting | finished responding, or interrupted with Esc |
What it cannot detect:
- Plan approval (
ExitPlanMode), whose on-screen shape has no arrow-navigation footer to anchor on. - Streaming progress. Only state transitions, not intermediate tokens.
- A wrapped invocation such as
script -q out.log claude, where the foreground process is the wrapper. A dynamic loader is the one wrapper kolu resolves. - Sub-agents. When the parent waits on a dynamic workflow, kolu does show that workflow’s name and sub-agent count.
Codex
kolu queries Codex’s threads database, the highest-numbered
~/.codex/state_<N>.sqlite, for live threads whose working directory matches the
terminal, and takes one no other terminal holds.
It then tails that thread’s rollout JSONL. Standalone and daemon-backed TUI
sessions are detected; codex exec runs and sub-agents are not.
| State | Read from |
|---|---|
| Thinking | latest lifecycle event is task_started, no open tool call |
| Tool use | a function_call is open that is not an awaiting-user tool |
| Awaiting input | every open call is request_user_input, request_permissions or request_plugin_install |
| Waiting | latest lifecycle event is task_complete or turn_aborted, even with a tool call still open |
The context count is Codex’s own last_token_usage.input_tokens, the number its
/status command shows. Codex has no todo list, so a Codex tile shows no task
progress. If an upstream release renames a column detection depends on, no
thread matches; set KOLU_CODEX_DB to pin a known-good database.
Grok
kolu prefers the entry in ~/.grok/active_sessions.json whose process id
matches the terminal. With no process id to go on it takes the most recently
updated session under ~/.grok/sessions/ that no other terminal holds. That
file only ever finds a session, never ends one, because Grok rewrites the whole
list from each session’s own point of view. Only the process going away ends a
match.
State comes from tailing that session’s events.jsonl: phase_changed for
thinking, tool use and awaiting you, turn_ended for waiting. An open
ask_user_question reads as awaiting you even mid-tool.
Resume uses grok --resume <uuid>. The flags --model and -m,
--always-approve, --no-plan, --no-subagents and --no-alt-screen (inline
TUI instead of the alternate screen) are kept on the Recent agents list and
on resume. Context tokens come from signals.json (contextTokensUsed), and
task progress stays empty. Transcript export reads chat_history.jsonl.
OpenCode
OpenCode 2.0 or later is required. kolu queries OpenCode’s SQLite database at
~/.local/share/opencode/opencode.db, the 2.x session store (session_v2 and
session_message), for live sessions whose directory matches the terminal, and
takes one no other terminal holds. The
database’s write-ahead log drives live updates.
| State | Read from |
|---|---|
| Thinking | latest message is your prompt, or an assistant message not finished with finish: "stop", and no tool running |
| Tool use | a running tool part other than question |
| Awaiting input | every running tool part is question |
| Waiting | latest assistant message is completed with finish: "stop" |
The tile shows the model from the newest assistant message, and the context
count OpenCode’s own TUI shows: the newest accounted step’s input, output,
reasoning and cache tokens. OpenCode 2.x keeps no todo list, so a tile shows no
task progress. Against a database without session_v2 no OpenCode tile lights
up, and padi’s log names the missing table. Set KOLU_OPENCODE_DB for a
database elsewhere.
Pi
kolu scans the session directory for the terminal’s working directory,
~/.pi/agent/sessions/--<directory>--/, and binds the session
no other terminal holds. State comes
from tailing that session’s JSONL transcript. A watch over the sessions tree
lights the tile the moment that file lands.
| State | Read from |
|---|---|
| Thinking | newest entry is a prompt or a tool result; pi persists an assistant message only when it completes |
| Tool use | newest assistant message ended stopReason: "toolUse" |
| Waiting | newest assistant message ended its turn (stop, length, error or aborted) |
Resume uses pi --session with the transcript’s absolute path, which still
resolves when the session store has been redirected. The flags --model,
--provider, --thinking and --name are kept on the Recent agents list
and on resume. Context tokens are the newest assistant message’s input,
cacheRead and cacheWrite added up. The title is the session’s /name.
Transcript export reads the same JSONL.
Awaiting you is not detected: pi’s permission gates and questions are dialogs
that never reach the session file. Pi has no todo primitive, so there is no task
progress. A pi --no-session run writes nothing to disk, so there is nothing to
bind to, and it never reaches Recent agents.
Pi’s session-store locations
kolu follows pi’s own precedence, reading the foreground pi process’s arguments and environment:
| Override | Where sessions land |
|---|---|
pi --session-dir <dir> | <dir> |
PI_CODING_AGENT_SESSION_DIR=<dir> | <dir> |
sessionDir in <agent dir>/settings.json | <dir> |
PI_CODING_AGENT_DIR=<dir> | <dir>/sessions — the config dir moves, sessions with it |
| (none) | ~/.pi/agent/sessions |
Only the default bottom row uses per-directory subfolders (--<directory>--).
An override in the first three rows holds the session files flat, attributed by
each file’s header, and detection follows the redirect.
A process’s environment cannot be read on a host that hides it (/proc mounted
hidepid), or on macOS, where ps redacts even same-user environments. A
PI_CODING_AGENT_SESSION_DIR redirect is then unrecoverable and only the
default tree is scanned; --session-dir flags still resolve. Set
KOLU_PI_DIR=<dir> to force kolu’s scan root, whose sessions tree is scanned.
Oh My Pi
Oh My Pi (omp) is a fork of pi with its own storage and a per-terminal
breadcrumb recording which session file that terminal is using. To find it, kolu
reads the omp process’s terminal (/proc/<pid>/fd/0 on Linux, ps on macOS)
and follows the matching breadcrumb. Two omp terminals in one repository each
show their own conversation.
State comes from tailing that session’s JSONL transcript, as with pi. A new session’s breadcrumb is written before its JSONL exists, because omp writes that only when the first reply is done, so until then the terminal reads starting, then ready, then working.
| State | Read from |
|---|---|
| Thinking | newest entry is a prompt or a tool result; omp persists an assistant message only when it completes |
| Tool use | newest assistant message ended stopReason: "toolUse" |
| Awaiting input | a tool-approval dialog (Allow tool: …) or an ask question on the rendered screen |
| Waiting | newest assistant message ended its turn (stop, length, error or aborted) |
Awaiting you is read off the screen, because omp paints a bordered dialog there
while the transcript stays on the in-flight tool call. Recognition keys on the
default theme’s border corner (╭─ Allow tool: …, ╭─ Ask …). With omp’s
symbolPreset: ascii, which draws +- corners, the tile stays on running tools
for the prompt. Plan approval is not detected: its overlay has no stable marker.
What an Oh My Pi tile shows
Resume uses omp --resume with the transcript’s absolute path, which survives a
moved store. The flags --model, --smol, --slow, --plan, --thinking,
--approval-mode and --profile are kept on the Recent agents list and on
resume. Context tokens are the newest assistant message’s input, cacheRead
and cacheWrite added up. The title is the name you set, or omp’s own.
Task progress is omp’s todo list, read from the newest todo result on the
conversation’s live branch. It is counted the way omp’s own Overall: N/M done
line counts it, with a dropped task counted done and a blocked one still open. A
resumed or compacted session keeps its list. Transcript export renders the live
branch.
An omp --no-session run writes no session and no breadcrumb, so the terminal
shows Oh My Pi as ready and stays there. On macOS a PI_CODING_AGENT_DIR or
OMP_PROFILE redirect cannot be read, so the default directory is used; a
--profile flag still resolves.
Oh My Pi’s agent-directory locations
kolu follows omp’s own precedence, reading the foreground omp process’s
arguments and environment:
| Override | Where the breadcrumb and sessions land |
|---|---|
omp --profile <name>, else OMP_PROFILE, else PI_PROFILE | ~/.omp/profiles/<name>/agent |
PI_CODING_AGENT_DIR=<dir> | <dir> |
PI_CONFIG_DIR=<name> | ~/<name>/agent |
none of the above, and $XDG_STATE_HOME/omp exists | $XDG_STATE_HOME/omp (a profile uses $XDG_STATE_HOME/omp/profiles/<name>) |
| (none) | ~/.omp/agent |
Unlike pi, an unresolvable directory is not replaced by a kolu default: a run
whose process cannot be read publishes nothing, as does a profile name omp
itself would refuse. Set KOLU_OMP_DIR=<dir> to force kolu’s own default.
Xyne
kolu matches the terminal against the newest transcript under
~/.xyne/agent/sessions/<encoded-cwd>/. Xyne writes one
<timestamp>_<uuid>.jsonl transcript per session, plus a <name>_summary.json
sidecar holding the display title, in a directory named after the transcript’s
working directory with every non-alphanumeric character folded to -. That
newest transcript is the session xyne --continue reopens.
A Xyne terminal always reads waiting, because the transcript carries no live
phase signal. That does not mean it is your turn. The dock row and the agent
inspector still show the session title from the sidecar and the last-used model
from the transcript’s newest model_change entry. Task progress and context
tokens stay empty.
Resume uses xyne --session <uuid>, including for a terminal restored after a
reboot. Transcript export reads the same JSONL, taking token usage from the
freshest assistant row.
Which agents appear in the palette
Once you have run a known agent in any terminal, it also appears in the command palette, as a launch option in the worktree-naming flow and in the Recent agents group. Aider, Goose, Gemini and Cursor Agent write no session kolu can read, so they never appear.