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

Web Browse

• chrome_list — List open Chrome tabs across all profiles (bridge, CDP, or AppleScript)
• web_browse — Fetch page content as text, Markdown, or structured JSON
• web_screenshot — Capture full-page or viewport screenshots
• web_interact — Multi-step page interaction (click, fill, scroll, evaluate JS)
• Four browser modes: bridge (Chrome extension, zero prompts), isolated (headless Chromium), cdp (DevTools Protocol), applescript (read-only macOS)
• Playwright-core is optional — only needed for isolated and CDP modes
• Chrome extension + native messaging bridge included for zero-prompt tab access

Feature Toggles

All tau features can be toggled on or off via the /tau command with six configuration scopes:

/tau features                              # open TUI overlay
/tau features set <id> on|off --scope <s>  # disable or enable a feature
/tau features get <id>                     # show effective value and source
/tau features unset <id> --scope <s>       # clear override, fall through to layer below

| Scope | Storage | Survives reload? | Survives session? | |-------|----------|-------------------|--------------------| | temporary | in-memory | no | no | | thread | session branch entry | yes (per branch) | no | | session | in-memory | no | no | | cwd | cwd/.pi/settings.json | yes | yes | | project | nearest .pi/settings.json walking up to git root | yes | yes | | global | ~/.pi/agent/settings.json | yes | yes |

Features default to on. The TUI shows the source layer for each feature's current value.

On-disk format in .pi/settings.json:

{
  "tau": {
    "features": {
      "bookmark": false
    }
  }
}

Some features (claude-rules, git-checkpoint) bootstrap at session start; toggling them at runtime requires /reload to take full effect. The TUI flags these with a reload indicator.

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 | | chrome_list | List open Chrome tabs (bridge, CDP, or AppleScript) | | web_browse | Fetch page content as text, Markdown, or structured JSON | | web_screenshot | Capture page screenshots | | web_interact | Multi-step page interaction (click, fill, scroll, evaluate) |

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 | | /tau | Toggle features: set, get, unset, or open TUI |

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