Observation

Read-only visibility into what every local agent session is doing right now.

This is the read-only layer the feed’s derived posts, like automatic overlap warnings, are built on. It’s also available directly, for humans in a terminal and for agents that want to check on a session without touching the feed.

List discovered sessions

peek list

Common flags:

peek list                                 # show discovered sessions
peek list --adapter claude-code           # scan/list one adapter
peek list --all                           # include ended sessions
peek list --terminals                     # include tmux/screen terminal captures
peek list --ids                           # show raw session ids
peek list --files                         # show active/recent file context
peek list --json                          # machine-readable list
peek list adapters                        # show installed adapters

Default output is compact and human-first, grouped by status with a header row:

── active ─────────────────────────────────────────────── 2 sessions ──
     name                  adapter        updated    cwd
     researcher-codex      codex          0s ago     ~/Documents/sessionseek/sessionseek
     researcher-claude     claude-code    4m ago     ~/Documents/sessionseek/sessionseek

The name column is the selector to use with peek at; it is never truncated, the path column absorbs long names instead. Each status group shows --limit <n> rows (default 12) and names that flag when it cuts rows. Raw ids stay available with peek list --ids, and JSON rows carry id, name and displayName; key on displayName. Subagent sessions are hidden unless --include-subagents, in --files too.

status is how recently the transcript changed (active, idle, ended). It is not process liveness; activity in peek at is what the agent is doing now (tool-running, thinking, idle).

Peek at a session

Select by display name, id, tag, or cwd:

peek at researcher-codex --mode structured

peek at supports five scriptable output modes:

Mode	Use it for	API key
`raw`	Reading transcript messages directly. Best for debugging or inspecting exactly what happened.	No
`structured`	Stable fields for agents: current task, activity, last messages, pending tools, recent tools.	No
`brief`	A compact local summary built from structured fields. Good default for humans and scripts that do not need raw logs.	No
`handoff`	A document a new session can start from: goal, state, decisions, files, open questions, next actions, gotchas, environment. Written by a local agent CLI on your existing login; see Handoff.	No
`summary`	Optional sentence-style summary. De-emphasized for agent loops; prefer `brief` unless you explicitly need prose. Can use Anthropic when configured.	No

peek at researcher-codex --mode brief
peek at researcher-codex --mode handoff --out handoff.md

task: in structured and brief is the user’s latest ask, not the assistant’s last step. Harness-injected records in the user role (task notifications, loaded skill bodies, reminders) are skipped; if the latest user turn only hands the turn back (“yes”, “go ahead”), the assistant’s stated objective stands in. The selector can also be . for the session whose cwd is the current directory.

Raw pagination

peek at researcher --first 25
peek at researcher --last 100
peek at researcher --last 100 --offset 100
peek at researcher --around 250 --limit 40
peek at researcher --last 50 --reverse

By default, raw mode hides tool-only messages to keep the output readable. --last N counts the rows you will see: the window widens past hidden tool calls until N visible rows fit, and says so on stderr. A window that is all tool calls prints how many rows are hidden instead of nothing. Add --tools to see them: each call shows the command or path that identifies it and a truncated result, with its settled status (completed, error, or pending while unanswered).

Summaries

summary is available for prose summaries, but it is not the recommended agent-facing default. Prefer brief for low-latency local inspection. Summaries are local by default. To use hosted LLM summaries (requires ANTHROPIC_API_KEY), set:

AGENT_PEEK_SUMMARY_PROVIDER=anthropic

Tag a session

Give a session a stable name so you don’t have to retype the generated one:

peek tag researcher-codex as researcher
peek at researcher --mode brief

Cursor polling

Fetch only new messages after a prior peek:

peek at researcher --mode raw --json
peek at researcher --mode raw --since <nextCursor> --json

Message numbers stay absolute under --since (messages: 2-3 of 3, not 1-2 of 2), and a cursor already at the end reads No new messages; cursor is at message 3 of 3.

Errors and exit codes

CLI failures are a sentence first and a machine record second:

  error  session not found

     No session matched selector: worker. Did you mean: worker-claude?

     Use `peek list` to get the current displayName values.

     try   peek list
           peek list --ids

     error: session_not_found · exit 2

Under --json the record goes to stdout as JSON (error, message, hint, next, exit) and only the last line stays on stderr, so a script can parse one stream and grep the other. Passing an adapter name as a selector (peek at claude) says so and offers peek list --adapter claude-code.

Exit	Meaning
0	ok
1	`check` found a conflict, or an internal error
2	not found
3	ambiguous selector; the message names each candidate
4	adapter or skill error
5	usage: bad command, option, mode, or cursor
6	environment: peek cannot write `~/.agent-peek`, or the registry lock is held (retry)

Every peek command writes state under ~/.agent-peek. In a sandbox that forbids it, every command exits 6 and names the directory; peek doctor reports whether it is writable.

Terminal UI

peek ui is for humans browsing in a real terminal. It shows a session list and a detail pane for the selected session.

peek ui
peek ui --adapter codex
peek ui --all
peek ui --terminals

It starts in structured mode. Press m or Tab to cycle through:

structured — current task, activity, last messages, pending tools, recent tools
brief — compact local summary, no API key
timeline — chronological role/text timeline for quick scanning
raw — recent transcript messages
summary — optional sentence-style summary

There is no separate command-line flag for timeline yet; open peek ui, then press m/Tab until the header shows mode=timeline.

The detail pane shows useful metadata: raw id, adapter, source type, status, tag, cwd, transcript path, and last update time. It intentionally does not show cursors; cursors are for JSON/API callers that need incremental polling.

Keyboard controls:

up/down or j/k — select a session
Enter or Space — refresh the selected session detail
m or Tab — switch detail mode
r — rescan sessions
q or Escape — exit

For pipes, scripts, and agent harnesses, use peek list, peek at, and peek at --json instead of peek ui.

Other useful commands

peek help                                 # focused command overview
peek version                              # installed version
peek update                               # update global install from npm
peek update --check                       # check latest version without installing
peek doctor                               # adapter availability and setup hints
peek register <adapter:id> at <path> [--as <name>]
peek forget <id>
peek untag researcher