@dinhtungdu/watcher 1.0.0

package/CONTEXT.md

@@ -0,0 +1,77 @@
+# Watcher
+
+Watcher helps a user observe running agent sessions and jump to the relevant workspace.
+
+## Language
+
+**Agent Pane**:
+An interactive workspace running an agent session that Watcher can surface and activate. Agent Panes are identified by a Terminal Backend and that backend's local surface identity.
+_Avoid_: Agent activity, agent shell, bot pane
+
+**Agent Status**:
+The current condition of an Agent Pane: working, needs input, idle, unknown, or stalled. Agent Status is used for priority, visual attention, and detail context; it does not decide whether a running Agent Pane appears in the Agent Switcher.
+_Avoid_: Activity, state, health
+
+**Pending Assistant Message**:
+A completed assistant message observed before the agent turn has finished. It may be promoted to the final assistant message when the Agent Pane becomes idle, but it is not itself the final assistant result.
+_Avoid_: Last message, final answer, assistant summary
+
+**Needs Input Agent**:
+An Agent Pane that explicitly needs human input, permission, or a decision before continuing. Recent activity may remain visible as context for what needs the input.
+_Avoid_: Blocked agent, waiting agent, stuck agent
+
+**Stalled Agent**:
+An Agent Pane that appears to be working but has had no output, title, or Watcher Agent Event change for a configured time window.
+_Avoid_: Stuck agent
+
+**Agent Integration**:
+Watcher’s knowledge of how to detect, install support for, and interpret events from a specific agent program. Capability metadata describes what Watcher currently supports, not every upstream feature the agent may theoretically expose.
+_Avoid_: Agent provider, agent backend, agent plugin, agent abstraction
+
+**Watcher Agent Event**:
+A normalized event describing agent progress, such as a user message, assistant message, tool activity, need for input, or completion. Agent Integrations translate agent-specific hooks and plugins into Watcher Agent Events before sending them to Watcher.
+_Avoid_: Raw hook event, agent callback, daemon event
+
+**Observation Capability**:
+The currently active way Watcher can observe a specific Agent Pane, such as integration events, assistant deltas, or terminal preview. Observation Capability describes what is true for one running Agent Pane, not what an Agent Integration or Terminal Backend could theoretically support.
+_Avoid_: Integration capability, supported feature, provider capability
+
+**Agent Event Source**:
+An installed hook, plugin, extension, or stream connection that emits Watcher Agent Events for an Agent Pane.
+_Avoid_: Status hook, silent hook, auto hook
+
+**Event Surface Identity**:
+The backend-aware identity an Agent Event Source reports so Watcher can associate a Watcher Agent Event with the correct Agent Pane. Its canonical key combines Terminal Backend and backend-local surface id, such as `tmux:%7`.
+_Avoid_: Pane id, hook target, routing metadata
+
+**Repo Group**:
+A collection of Agent Panes that belong to the same source repository. Repo Groups contain one or more Worktree Groups.
+_Avoid_: Project group, repo bucket
+
+**Worktree Group**:
+A collection of Agent Panes that share the same Git worktree path within a Repo Group. The branch is displayed as context, but the worktree path is the identity.
+_Avoid_: Branch group, session group
+
+**Path Fallback Group**:
+A collection of Agent Panes grouped by path when Watcher cannot determine repository and worktree identity.
+_Avoid_: Unknown repo, ungrouped panes
+
+**Terminal Backend**:
+A local terminal environment that can discover, identify, and activate Agent Panes. tmux is Watcher's current Terminal Backend.
+_Avoid_: Provider, terminal type, transport
+
+**Running Agent Pane**:
+An Agent Pane whose Terminal Backend surface still exists and is running a known agent process. Agent Event Sources provide Agent Status and activity for Running Agent Panes, but stale daemon history alone is not liveness: if tmux is available and the known agent process is gone, the Agent Pane is no longer running even if its shell pane remains. Running Agent Panes are shown regardless of Agent Status, including `idle`.
+_Avoid_: Non-terminated agent pane, active-only session, actionable-only pane
+
+**Agent Pane Activation**:
+The user action of jumping from Watcher to the selected Agent Pane.
+_Avoid_: Switch, attach, focus
+
+**Watcher Daemon**:
+The background process that receives Watcher Agent Events and serves the current Agent Pane snapshot to the TUI.
+_Avoid_: Server, backend, monitor
+
+**Agent Switcher**:
+The terminal interface that lists running Agent Panes and activates the selected pane.
+_Avoid_: Dashboard, monitor, agent list

package/README.md

@@ -0,0 +1,20 @@
+# Watcher
+
+A tmux-native switcher for local coding agents.
+
+Built because I live in the terminal and already use tmux. Watcher is deliberately not trying to reinvent the wheel: tmux already owns windows, panes, sessions, keybindings, and muscle memory. Watcher just shows which agent panes need attention, previews enough context, then jumps straight back into tmux.
+
+![Watcher terminal preview](docs/assets/watcher-terminal-preview.png)
+
+```sh
+watcher
+watcher integrations install pi
+```
+
+Tmux binding example:
+
+```tmux
+bind -n M-s new-window -n watcher "watcher"
+```
+
+This keeps Watcher one keystroke away: `Alt-s` opens the switcher in a tmux window, `j/k` picks an agent, and `Enter` jumps to it.

package/docs/adr/0001-agent-switcher-architecture.md

@@ -0,0 +1,15 @@
+# Agent Switcher architecture
+
+Watcher uses explicit Agent Integrations as the primary source for Agent Status and activity, with terminal-backend process/title/output heuristics as fallback while the Agent Switcher is open. Integrations call a small `watcher event <agent> <event>` CLI shim, which reads backend identity and forwards normalized Watcher Agent Events to the Watcher Daemon over a local Unix socket. Agent Event Sources are installed with `watcher integrations install`. The daemon stores snapshots keyed by backend-local surface id; the Agent Switcher discovers current panes across supported local Terminal Backends, shows all running agent panes including idle panes, uses Agent Status for priority/context rather than visibility, and activates the selected pane through backend-specific commands.
+
+## Considered Options
+
+- Scrape terminal output only: rejected because task/status inference from arbitrary TUI output is noisy and agent-specific.
+- Require hooks only: rejected because unsupported or not-yet-restarted agents should still be discoverable best-effort.
+- Poll terminal backends from the daemon continuously: rejected because capture polling is only needed while the switcher UI is open.
+- Use Ink: rejected by product preference.
+- Use `@opentui/core`: rejected after Bun/runtime compatibility issues and prototype mismatch; render the accepted prototype-style ANSI terminal frame directly for MVP.
+
+## Consequences
+
+Supported agents need explicit `watcher integrations install` before rich status works. Existing running agents may need restart/reload before integrations emit events. Integrations stay small because they shell out to the Watcher CLI instead of embedding socket protocol code in every agent hook/plugin. Remote terminal backends are out of scope for MVP; run Watcher on the remote host separately.

package/docs/adr/0002-agent-switcher-focus-layout.md

@@ -0,0 +1,15 @@
+# Agent Switcher focus layout
+
+Watcher organizes the Agent Switcher as `repo > worktree/branch > sessions`, with worktrees from the same repository grouped together and all running Agent Panes shown under each worktree, including idle panes. The worktree path is the grouping identity because branch names alone are ambiguous; branch names are displayed as context, and panes without Git metadata fall back to path grouping.
+
+## Considered Options
+
+- Flat status-first list: rejected because it scatters related work across the switcher and makes multi-worktree repositories harder to scan.
+- Repo-only grouping: rejected because multiple worktrees in the same repository represent separate task contexts.
+- Showing only one pane per worktree: rejected because users still need to choose between multiple running sessions in the same branch/worktree.
+- Text status badges in rows: rejected because they add noise; rows use a colored status dot and the details pane carries exact status.
+- Status-gated visibility: rejected because Watcher is a switcher, not only an alert queue. Agent Status affects sort priority and context; all running agents remain visible, including idle panes.
+
+## Consequences
+
+The switcher needs best-effort Git metadata for repo, branch, and worktree path, plus a path fallback when Git metadata is unavailable. It also needs Agent Status for priority sorting and selected-pane context even though status no longer gates visibility. Activation continues to exit the TUI before jumping to the selected Agent Pane, so Watcher remains a focus switcher rather than a dashboard to keep open.

package/docs/adr/0003-terminal-backends.md

@@ -0,0 +1,13 @@
+# Terminal Backend abstraction
+
+Watcher keeps a Terminal Target seam so core Agent Switcher logic does not depend directly on tmux field names. tmux remains the only supported backend. Native Ghostty support was investigated and postponed because current stable Ghostty does not provide both reliable cross-platform surface identity and cross-platform activation control.
+
+## Considered Options
+
+- Keep tmux fields in the core Agent Pane model: rejected because it spreads tmux vocabulary through grouping, rendering, stalled detection, and activation code.
+- Add Ghostty as a runtime backend now: rejected because support would be partial or platform-specific.
+- Use macOS AppleScript for Ghostty activation: rejected because Watcher should support every platform Ghostty supports, and macOS-only automation would turn Terminal Backend into a platform-specific footgun.
+
+## Consequences
+
+Core switcher code should depend on Terminal Target helpers instead of tmux-specific fields. Runtime support remains tmux-only until another terminal backend can provide identity, discovery, stalled-signal inputs, and activation without platform-specific hacks.

package/docs/adr/0004-agent-integrations-and-events.md

@@ -0,0 +1,40 @@
+# Agent Integrations and normalized Watcher Agent Events
+
+Watcher observes existing agent sessions running in terminal panes. It will model agent-specific support as Agent Integrations that emit normalized Watcher Agent Events, rather than centering the architecture on ACP or raw agent-specific hook events.
+
+## Considered Options
+
+- Use ACP as the primary integration path: rejected because Watcher's core workflow is observing and activating already-running terminal sessions, while ACP is best suited to sessions launched and owned by an ACP client.
+- Let the Watcher Daemon understand raw events from each agent: rejected because Pi, Codex, OpenCode, and other agents expose different hook/plugin/event names and payloads; putting every dialect in the daemon would make it the integration junk drawer.
+- Keep the hook model named around status: rejected because integrations now report user messages, assistant messages, tool activity, assistant deltas, input needs, and completion, not only Agent Status.
+- Model terminal preview as an Agent Integration capability: rejected because terminal preview comes from the Terminal Backend, not from a specific agent program.
+
+## Decision
+
+Watcher will use **Agent Integrations** as the agent-specific abstraction. An Agent Integration owns detection, install/status behavior for its Agent Event Source, capability metadata, and translation from agent-specific hooks/plugins/events into normalized **Watcher Agent Events**.
+
+Agent Event Sources call:
+
+```sh
+watcher event <agent> <event>
+```
+
+The event name and payload at this CLI boundary are normalized Watcher Agent Events, not raw Pi/Codex/OpenCode event names. The legacy `watcher hook` command is not retained because Watcher does not yet have external users.
+
+Watcher will use `watcher integrations install` and `watcher integrations status` as the user-facing commands for installing and inspecting Agent Event Sources.
+
+Watcher Agent Events include semantic activity such as user messages, assistant messages, optional assistant deltas, tool activity, input needs, completion, and errors. High-frequency assistant deltas must be coalesced by the Agent Integration before shelling out to `watcher event`; integrations must not spawn one process per token.
+
+Agent Integrations and Terminal Backends remain separate axes. Terminal Backends own discovery, activation, and terminal preview capabilities. Agent Integrations own semantic agent events and assistant delta support. Per-pane Observation Capability describes what is actually active for a specific Agent Pane.
+
+Event routing uses backend-aware Event Surface Identity. Event payloads may provide a `surface` identity; otherwise `watcher event` may fall back to `$TMUX_PANE` as a tmux Event Surface Identity. `AgentPane.id` is an internal canonical Event Surface Identity key such as `tmux:%7`; user-facing terminal labels come from the Terminal Target.
+
+## Consequences
+
+The daemon can stay focused on applying normalized Watcher Agent Events to Agent Pane state instead of learning every agent's native event dialect.
+
+Pi remains the first fully functional Agent Integration during the refactor. OpenCode, Codex, and Claude can be added to the integration registry for detection/capability metadata before their installers are implemented.
+
+Terminal preview is intentionally left as a separate implementation slice after the Agent Integration/event refactor.
+
+Existing generated Pi hooks and CLI command names will be broken by the refactor and must be reinstalled, which is acceptable before public adoption.

package/docs/requirements.md

@@ -0,0 +1,189 @@
+# Watcher MVP Requirements
+
+Watcher is a tmux-wide Agent Switcher. It lists running agent panes across all local tmux sessions and activates the selected pane.
+
+## Scope
+
+- Local tmux only.
+- tmux is the supported backend for discovery, Event Surface Identity, stalled detection, and activation.
+- Native Ghostty support is not part of the MVP.
+- Bun/TypeScript CLI named `watcher`.
+- Prototype-aligned terminal switcher UI rendered by the Bun CLI.
+- In-memory Watcher Daemon.
+- Explicit Agent Event Sources where supported; backend/process/title/output fallback while the TUI is open.
+
+## Commands
+
+- `watcher`: open Agent Switcher.
+- `watcher daemon`: run Watcher Daemon.
+- `watcher event <agent> <event>`: CLI shim called by Agent Integrations; reads JSON from stdin and `$TMUX_PANE`.
+- `watcher integrations install <agents...>`: install supported Agent Event Sources.
+- `watcher integrations status`: show Agent Event Source install status.
+
+## Statuses
+
+Agent Status describes priority and context for a running Agent Pane. It does not decide visibility; all running Agent Panes are shown.
+
+- `working`: agent is handling a prompt.
+- `needs_input`: agent needs human input, permission, or decision.
+- `stalled`: agent appears working but has no output, title, or Watcher Agent Event change for 5 minutes.
+- `unknown`: known agent process exists but no reliable status yet.
+- `idle`: agent finished or is inactive; still shown while the agent pane exists so the switcher can activate it.
+
+## Switcher Layout
+
+Show all running Agent Panes with statuses `needs_input`, `stalled`, `working`, `unknown`, and `idle`. Hide only panes whose tmux pane no longer exists.
+
+Use the final prototype layout: `repo > worktree/branch > sessions`.
+
+Group the list as:
+
+1. Repo Group
+2. Worktree Group
+3. Agent Pane rows
+
+Repo and worktree rules:
+
+- Group all worktrees from the same repository under one Repo Group.
+- Key Worktree Groups by Git worktree path, not branch name alone.
+- Show branch and worktree path in each Worktree Group header.
+- If repository/worktree metadata is unavailable, use a Path Fallback Group keyed by pane path.
+- Show all running Agent Panes within each Worktree Group, including `idle` panes.
+
+Each session row should show only:
+
+- colored status dot
+- agent type
+- task/prompt summary
+
+Do not show status text badges, time columns, tmux target, cwd, current action, or message previews inline in rows.
+
+Selected Agent Pane details should show:
+
+- exact Agent Status
+- agent type
+- repo, branch, and worktree path, or path fallback
+- task/prompt summary
+- current tool/action when available
+- last assistant message preview when available
+- tmux session/window/pane
+- last update age
+
+Responsive layout:
+
+- wide terminals: list on the left with a large details pane on the right
+- medium/narrow terminals: list-first layout with selected summary at the bottom
+- selected row: full-width, theme-adaptive reverse highlight; no hardcoded colors and no selection triangle
+
+Ordering applies at Repo Group, Worktree Group, and Agent Pane row levels:
+
+1. Repo Groups by highest-priority running Agent Pane, then newest update.
+2. Worktree Groups by highest-priority running Agent Pane, then newest update.
+3. Agent Pane rows within a Worktree Group by status priority, then newest update.
+
+Status priority:
+
+1. `needs_input`
+2. `stalled`
+3. `working`
+4. `unknown`
+5. `idle`
+
+Within the same highest-priority status, newest update first.
+
+## Backend Discovery
+
+While the switcher is open, tmux discovery should:
+
+- poll `tmux list-panes -a` every 2 seconds
+- detect known agent processes by pane command and one-level process tree scan from `pane_pid`
+- capture pane tail/hash for candidate agent panes only
+- derive `stalled` when status is `working` and no Watcher Agent Event, title, or output change occurs for 5 minutes
+
+Native Ghostty discovery, Event Surface Identity, and activation are out of MVP. tmux sessions running inside Ghostty remain supported through the tmux backend.
+
+No ghost panes: if a tmux pane no longer exists, hide it.
+
+## Activation
+
+- tmux inside tmux: switch client to target session, select target window, select target pane.
+- tmux outside tmux: select target window/pane first, then attach to target session.
+- Use tmux pane ids like `%42`.
+- Exit TUI before activation/attach/focus.
+
+## Agent Event Sources
+
+Agent Integrations shell out to `watcher event <agent> <event>` rather than embedding daemon protocol code.
+
+`watcher event`:
+
+- accepts only known Agent Integrations and normalized Watcher Agent Event names
+- accepts `--quiet` only as `watcher event --quiet <agent> <event>` for generated Agent Event Sources
+- reads Event Surface Identity from the event payload when present
+- falls back to `$TMUX_PANE` as a tmux Event Surface Identity
+- reads normalized Watcher Agent Event JSON from stdin; empty stdin is treated as `{}`
+- validates the canonical payload schema; schema/agent/event errors are loud outside quiet mode and silent in quiet mode
+- starts daemon if absent, retries briefly
+- exits 0 silently if daemon unavailable
+- never breaks the agent
+- must not be called once per token; high-frequency streaming events should be coalesced by the Agent Integration before shelling out
+
+Watcher Agent Event mapping:
+
+- `session-started` -> `unknown`
+- `user-message` / `assistant-delta` / `assistant-message` / `tool-started` / `tool-updated` / `tool-finished` -> `working`
+- `needs-input` -> `needs_input`
+- `agent-finished` -> `idle`
+- `error` -> `needs_input` with reason `error`
+
+Watcher Agent Event payload rules:
+
+- event payload identity uses `surface`, not `target`
+- message `text` fields must be strings
+- `assistant-delta.text` is the current accumulated partial assistant text, not an incremental token chunk
+- `tool-updated.text` is the current summarized tool state, not an append-only chunk
+- tool `input` and `output` may be JSON values and are compacted centrally
+- unknown extra fields are ignored, but required canonical fields are strict
+- large text fields are capped centrally at ingestion; normal truncation and wrapping belong to display code
+
+Agent Pane state rules:
+
+- `AgentPane.id` is an internal canonical Event Surface Identity key such as `tmux:%42`; user-facing terminal labels come from the Terminal Target
+- `user-message` sets `userMessage` and row `summary`
+- assistant/tool events never replace `summary` once `userMessage` exists
+- `assistant-delta` updates running activity and `currentAction = "Responding"`, but does not update `lastMessage`
+- `assistant-message` stores a Pending Assistant Message and updates activity, but does not update `lastMessage` until completion
+- `agent-finished` clears activity/current action and sets `lastMessage` from non-empty `finalMessage`, else Pending Assistant Message, else previous `lastMessage`
+- activity items merge by id, are kept newest-first, and are limited to 3 while non-idle
+- `needs-input` preserves recent activity context and may mark referenced activity as waiting
+
+## Pi MVP Agent Event Source
+
+Install global extension:
+
+`~/.pi/agent/extensions/watcher-status.ts`
+
+Behavior:
+
+- `session_start` -> `watcher event pi session-started`
+- `before_agent_start` -> `watcher event pi user-message` with prompt
+- `message_end` -> `watcher event pi assistant-message` with last completed assistant message
+- `tool_execution_start/update/end` -> `watcher event pi tool-started/tool-updated/tool-finished`
+- `agent_end` -> `watcher event pi agent-finished` with last assistant message when available
+
+Installer:
+
+- overwrite only files with current or legacy Watcher markers
+- report legacy Watcher-managed files as `outdated` until reinstalled
+- refuse to overwrite non-Watcher file
+- after install, tell user to `/reload` existing Pi panes or restart them
+
+## Non-goals MVP
+
+- remote SSH/tmux relay
+- native Ghostty support before stable foreground PID/TTY support and cross-platform activation control
+- session resume/restore
+- history database
+- unread/dismiss workflow
+- parsing arbitrary terminal output for task text
+- automatic silent global config mutation

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dinhtungdu/watcher",
+  "version": "1.0.0",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dinhtungdu/watcher.git"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.9.1",
+    "typescript": "^5.9.3"
+  },
+  "bin": {
+    "watcher": "src/cli.ts"
+  },
+  "bugs": {
+    "url": "https://github.com/dinhtungdu/watcher/issues"
+  },
+  "description": "tmux-wide Agent Switcher for agent panes",
+  "directories": {
+    "doc": "docs"
+  },
+  "files": [
+    "src",
+    "docs",
+    "CONTEXT.md"
+  ],
+  "homepage": "https://github.com/dinhtungdu/watcher#readme",
+  "keywords": [],
+  "license": "ISC",
+  "packageManager": "bun@1.3.13",
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "build": "bunx tsc -p tsconfig.json --noEmit",
+    "lint": "bunx tsc -p tsconfig.json --noEmit",
+    "test": "bun test test/*.test.ts"
+  },
+  "type": "module"
+}

package/src/activation.ts

@@ -0,0 +1,58 @@
+import { AgentPane, TmuxTarget } from './model.js';
+import { paneTargetLabel } from './terminalTarget.js';
+import { CommandRunner, nodeCommandRunner } from './tmux.js';
+
+export interface TerminalCommand {
+  file: string;
+  args: string[];
+}
+
+export interface ActivationOptions {
+  insideTmux?: boolean;
+  runner?: CommandRunner;
+  env?: NodeJS.ProcessEnv;
+}
+
+function requireTmuxTarget(target: TmuxTarget): { paneId: string; session: string; window: string } {
+  const paneId = target.paneId;
+  const session = target.sessionName;
+  const window = target.windowIndex;
+  if (!paneId || !session || window === undefined) {
+    throw new Error(`Cannot activate ${target.id}: missing tmux session/window/pane target`);
+  }
+  return { paneId, session, window };
+}
+
+export function activationTargetLabel(pane: AgentPane): string {
+  return paneTargetLabel(pane);
+}
+
+export function buildTmuxActivationCommands(target: TmuxTarget, insideTmux: boolean): TerminalCommand[] {
+  const required = requireTmuxTarget(target);
+  const windowTarget = `${required.session}:${required.window}`;
+  if (insideTmux) {
+    return [
+      { file: 'tmux', args: ['switch-client', '-t', required.session] },
+      { file: 'tmux', args: ['select-window', '-t', windowTarget] },
+      { file: 'tmux', args: ['select-pane', '-t', required.paneId] },
+    ];
+  }
+  return [
+    { file: 'tmux', args: ['select-window', '-t', windowTarget] },
+    { file: 'tmux', args: ['select-pane', '-t', required.paneId] },
+    { file: 'tmux', args: ['attach-session', '-t', required.session] },
+  ];
+}
+
+export function buildActivationCommands(pane: AgentPane, insideTmux: boolean): TerminalCommand[] {
+  return buildTmuxActivationCommands(pane.target, insideTmux);
+}
+
+export async function activateAgentPane(pane: AgentPane, options: ActivationOptions = {}): Promise<void> {
+  const runner = options.runner ?? nodeCommandRunner;
+  const env = options.env ?? process.env;
+  const insideTmux = options.insideTmux ?? Boolean(env.TMUX);
+  for (const command of buildActivationCommands(pane, insideTmux)) {
+    await runner.execFile(command.file, command.args, { timeout: 5000, env });
+  }
+}