kolu
Docs

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.

AgentCommand
Claude Codeclaude
Codexcodex
Grok Buildgrok
OpenCodeopencode
Pipi
Xynexyne
Oh My Piomp

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.

The five agent states and their indicators: thinking is a pulsing accent dot, tool use a pulsing amber dot, awaiting you a pulsing alert dot, working-in-background a spinning teal ring, and waiting a dim dot.ThinkinggeneratingTool userunning toolsAwaiting youblocked on inputWorkingbackground taskWaitingidle, your turn

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:

StateIndicatorMeaning
Startingthe agent’s mark, no glowthe program is up and its screen is still being drawn
Readythe agent’s mark, no glowits screen has settled and nothing has been submitted to it
Workingthe agent’s mark, working glowyou 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.

Detection reads each terminal’s foreground process id, checks whether it’s a known agent CLI, reads that agent’s own session store (a JSONL transcript or a SQLite database), and derives the live state shown on the dock and tile.foregroundprocess idknown agent?claude · codex · …session storeJSONL · SQLitelive statedock · tile · minimap

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:

FactWhere it comes from
which agentthe detection adapter that matched this terminal’s foreground process
which conversationthe agent’s own session file, plus its process or its breadcrumb
which flagsthe 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 runsWake replays
claude --plugin-dir P --resume <id> --dangerously-skip-permissionsclaude --resume <id> --dangerously-skip-permissions
omp -e P --resume <path> --model fableomp --resume <path> --model fable
ld-linux… …/opencode --standalone --session <id> --model sonnetopencode --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.

StateRead from
Thinkingan API call is in flight
Tool useClaude is executing tools
Running in backgroundClaude ended its turn while a dynamic workflow it launched is still running
Awaiting inputan AskUserQuestion prompt or a tool-permission gate on the rendered screen
Waitingfinished 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.

StateRead from
Thinkinglatest lifecycle event is task_started, no open tool call
Tool usea function_call is open that is not an awaiting-user tool
Awaiting inputevery open call is request_user_input, request_permissions or request_plugin_install
Waitinglatest 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.

StateRead from
Thinkinglatest message is your prompt, or an assistant message not finished with finish: "stop", and no tool running
Tool usea running tool part other than question
Awaiting inputevery running tool part is question
Waitinglatest 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.

StateRead from
Thinkingnewest entry is a prompt or a tool result; pi persists an assistant message only when it completes
Tool usenewest assistant message ended stopReason: "toolUse"
Waitingnewest 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:

OverrideWhere 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.

StateRead from
Thinkingnewest entry is a prompt or a tool result; omp persists an assistant message only when it completes
Tool usenewest assistant message ended stopReason: "toolUse"
Awaiting inputa tool-approval dialog (Allow tool: …) or an ask question on the rendered screen
Waitingnewest 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:

OverrideWhere 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.