Tau (τ) — Quality-of-Life Extension for pi

Background tasks, notifications, plan mode, presets, and other enhancements for the pi agent loop. Modelled after Claude Code's UX where possible.

Features

Background Tasks

• Ctrl+B — background running bash, background the agent loop, or resume a backgrounded agent
• 15-second auto-background — long-running commands are automatically backgrounded with agent confirmation
• Agent loop backgrounding — Ctrl+B during agent processing blocks further tool calls and yields control back to you
• Disk-based output — all background job output written to /tmp/pi-bg-<jobId>.log, not memory
• Process-group kill — process.kill(-pid) terminates entire process trees
• Stall detection — detects interactive prompts ((y/n), Press any key) in background jobs after 45s of stagnant output
• Size watchdog — kills background jobs exceeding 100 MiB output
• Background hint — ⏱ Ctrl+B to background appears after 2s of bash or agent activity
• Pill bar — ◐ job-1: cmd (12s) · ◐ agent (backgrounded) in the status area
• Task management UI — Shift+↓ or Ctrl+J opens grouped task list with detail views
• Ctrl+X — kill most recent running background task
• Session persistence — job history survives pi restarts

Notifications

• Native terminal notifications on agent completion — OSC 777 (Ghostty, iTerm2, WezTerm), OSC 99 (Kitty), Windows toast
• Last agent message shown in the notification body (first line, max 200 chars)
• Do Not Disturb — respects macOS Focus mode; suppresses notifications when DnD is active
• Persistent mode — option to keep notifications visible until dismissed
• /notifications command to configure

Plan Mode

• Ctrl+Alt+P or /plan — toggle read-only plan mode (only read, bash, grep, find, ls allowed)
• Automatic step extraction — numbered plan steps are parsed from the agent's response
• Execution tracking — switch to execution mode to track progress against the plan with [DONE:n] tags
• Status widget — shows 📋 3/7 progress in the status bar

Presets

• Ctrl+Shift+U — cycle through named presets
• /preset [name] — switch directly or open selector UI
• Configure model, thinking level, tools, and system prompt instructions per preset
• Config files: ~/.pi/agent/presets.json (global) and .pi/presets.json (project-local)
• CLI flag: pi --preset plan

Bookmarks

• /bookmark [label] — label the last assistant message for easy navigation in /tree
• /unbookmark — remove the most recent bookmark

Session Naming

• /session-name [name] — set a friendly name that appears in the session selector

Claude Rules

• Automatically scans .claude/rules/*.md (recursively) and injects the list into the system prompt
• The agent can read specific rule files when relevant

Custom Footer

• /footer — toggle a custom footer showing token usage (↑input ↓output $cost) and git branch

Git Checkpoints

• Creates a git stash create checkpoint at each turn
• On /fork, offers to restore code to that point in history

GitHub Issue Autocomplete

• Preloads the latest 100 open issues from the current GitHub repo via gh
• Type # in the input to trigger fuzzy-filtered issue completion
• Works with SSH and HTTPS remote URLs

Handoff

• /handoff <goal> — generates a focused context-transfer prompt using the current model
• Opens an editor to review/edit the prompt before creating a new session
• Preserves parent session linkage

Tasks

• task tool with nesting, links, and multi-status tracking
• Five statuses: todo, in-progress, done, blocked, cancelled
• Nested tasks via parentId — tree rendering in /tasks UI
• Directional links: blocks, depends-on, related
• Cycle detection on move, cascade removal, link cleanup
• /tasks command for interactive tree view

Conversation Summary

• /summarize — generates a structured summary of the current conversation using an LLM
• Renders as Markdown in a custom UI

Tools

Tool	Purpose
bash	Standard bash, enhanced with 15s auto-background timeout and Ctrl+B support
bash_bg	Start a command in the background immediately
jobs	list, output, kill, or attach to background jobs
job_decide	Decide what to do with a timed-out background job
task	Manage tasks with nesting, links, and status — list, add, update, remove, move, link, unlink

Commands

Command	Purpose
/bg	Same as Ctrl+B — background bash/agent or resume
/fg	Attach to a background job, optionally with --snapshot
/jobs	Open task management interface
/tasks	Show all tasks on the current branch
/tools	Enable/disable tools
/plan	Toggle plan mode (read-only exploration)
/notifications	Configure notification settings
/bookmark	Bookmark last assistant message
/unbookmark	Remove last bookmark
/session-name	Set or show session name
/footer	Toggle custom footer
/preset [name]	Switch preset configuration
/handoff <goal>	Transfer context to a new focused session
/summarize	Summarise the current conversation

Shortcuts

Shortcut	Action
Ctrl+B	Background running bash + agent, or resume backgrounded agent
Ctrl+X	Kill most recent running background task
Ctrl+J / Shift+↓	Open task management interface
Ctrl+Alt+P	Toggle plan mode
Ctrl+Shift+U	Cycle presets

CLI Flags

Flag	Purpose
--plan	Start in plan mode (read-only exploration)
--preset <name>	Start with a named preset

Architecture

src/
  index.ts              Entry point — creates TauState, registers all features, cross-cutting event handlers
  state.ts              TauState class — shared mutable state
  types.ts              Shared type definitions (BackgroundJob, RunningProcess, Task, etc.)
  utils.ts              Shared utilities (formatDuration, notify, killProcessGroup, etc.)
  plan-utils.ts         Plan-mode pure functions (step extraction, safe command checking)
  features/
    background.ts       bash override, bash_bg, jobs, job_decide tools
    background-commands.ts  /bg, /fg, /jobs commands, Ctrl+B/X/J shortcuts, task UI
    titlebar.ts         Braille spinner and elapsed timer
    plan-mode.ts        /plan, Ctrl+Alt+P, plan execution tracking
    task.ts             task tool, /tasks command (nesting, links, status)
    tools-selector.ts   /tools command, state persistence
    notifications.ts    /notifications, agent_end notification, DnD support
    bookmark.ts         /bookmark, /unbookmark
    claude-rules.ts     .claude/rules/ scanning
    custom-footer.ts    /footer command
    git-checkpoint.ts   git stash checkpointing
    github-autocomplete.ts  # issue autocomplete
    handoff.ts          /handoff command
    preset.ts           /preset, Ctrl+Shift+U, JSON config
    session-name.ts     /session-name command
    summarize.ts        /summarize command

Key Design Decisions

• Disk over memory: Output goes to files, not in-memory buffers. Survives crashes, no memory pressure on long-running tasks.
• Process groups over tree-kill: process.kill(-pid) kills the entire group when spawned with detached: true. No external dependency needed.
• Block over pause: The agent loop can't be truly backgrounded (it runs in-process). Tool call blocking is the closest approximation. The agent sees an empty block reason and stops cleanly.
• 15s timeout: Matches Claude Code's ASSISTANT_BLOCKING_BUDGET_MS. Commands that need longer should use bash_bg.
• Feature modules: Each feature is a self-contained module that registers its own tools, commands, shortcuts, and event handlers. Shared state lives in a single TauState instance.
• Subagent stays separate: The subagent extension is large (~1000 lines) with external agent definitions and prompt templates. It remains a standalone extension for maintainability.

Known Limitations

These require changes to pi core (see implementation path note):

1. Agent doesn't keep running in background — tool calls are blocked, the loop pauses. True background execution needs an AgentLoopHandle API in pi core.
2. No click handlers on pill bar — setWidget() renders static text. No way to register click callbacks.
3. No Ctrl+X inside dialogs — select() doesn't support custom keybindings. Can only navigate with ↑/↓/Enter.
4. No live output streaming — editor() shows a static snapshot. No file-tail component available.

Installation

From npm

pi install npm:pi-tau

Or add to ~/.pi/agent/settings.json:

{
  "packages": ["npm:pi-tau"]
}

From GitHub

pi install github:Mearman/tau

Or clone directly into the extensions directory:

git clone https://github.com/Mearman/tau.git ~/.pi/agent/extensions/tau
cd ~/.pi/agent/extensions/tau && pnpm install

Licence

MIT — github.com/Mearman/tau