pi-task-tracker

Task workflow tracking for the pi coding agent: every completed task becomes a real git commit on your branch, and those commits double as interactive rollback checkpoints.

What it does

• TODO.md tracking — each prompt is recorded as a task entry in TODO.md and checked off when the agent settles.
• README.md maintenance — the project structure section stays up to date with agent-created files.
• Per-task git auto-commit — when a task completes, only the files the agent actually touched are staged and committed with the task as the message. Nothing else is swept in.
• /rollback — pick any prior commit interactively and the working tree is restored to that point while the conversation rewinds to the turn that produced it (one checkpoint for files and context). Worktree-only, nothing is committed, fully reversible (git diff to review, commit when satisfied). Old session branches are preserved — /tree can navigate back.

What makes it different

• Hashline-aware — records edits made through pi-hashline-edit-pro's replace/insert tools, not just the native edit tool (most setups that replace native edit would otherwise go completely untracked).
• Shell-aware — captures files created/modified by bash and powershell tool calls via before/after git status diffing.
• Nested-repo aware — changes inside a sub-repository (a .git below your session root) are committed there — the innermost repo wins — and never pollute the outer repo. The outer task commit records anchors (Nested: <repo>@<sha>), so /rollback restores nested repos to their exact matching commit.
• Pre-existing double tracking respected — if a file is already tracked by both an outer repo and a nested repo, changes go to the nested repo (innermost wins), pi never untracks the outer copy, and /rollback never lets the outer repo restore its stale copy over the inner worktree.
• Subdirectory start — start pi in a subdirectory of an existing repo and no fresh .git is created there: all session changes (including TODO.md / README.md) are recorded in the enclosing repository, and /rollback restores the enclosing repo scoped to the session subtree.
• Scope guard — the writable scope equals the trackable scope: out-of-session writes follow taskTracker.externalWrite (default "ask": confirm; "warn": allow + yellow notice; "block": hard deny), so nothing changes that /rollback could not restore. Git history protection is built in.
• Subagent-safe — .pi-subagents/ session artifacts are never recorded, listed, or committed.

Lightweight by design (measured, not claimed)

The model never knows this extension exists. Every cost number below is measured on a real Windows machine (git spawn baseline ≈ 10 ms).

Zero token footprint — the only overhead that compounds is context, and this extension adds exactly 0 tokens per turn:

• nothing injected into the system prompt (the before_agent_start system-prompt hook is never used)
• zero custom tools registered (tool descriptions are what usually bloat context)
• /rollback executes locally; its UI prompts never reach the model
• task history lives in git objects, not in your conversation

And it is token-negative in the failure-retry loop: /rollback rewinds the conversation branch, so a failed attempt's tokens leave the active context instead of piling up forever.

Idle = 0 — no file watchers, no daemons, no timers. Pure event handlers; when pi is idle the extension does nothing.

Bounded, spawn-bound runtime cost — the cost is a handful of short git child processes, and it does not grow with repository size (git status on a 20-file repo ≈ a 5,000-file repo ≈ 20 ms):

Event	git calls	Measured cost
Session start (once)	3–6	~50–100 ms
Each bash/powershell command	2 status snapshots	~40 ms
Task commit (per completed task)	add + diff + commit	~60–80 ms
Idle / between events	0	0

Bounded memory — snapshots hold only the dirty-file set and are freed as soon as the command's result arrives; TODO.md stays tiny (entries are removed when tasks complete — it starts at 8 bytes).

Zero dependencies, one file, no config — drop it in extensions/, done. No setup, no keys, no services.

/rollback

/rollback
  → pick a commit (sha, date, task subject)
  → review the impact summary (files restored / removed, dirty-worktree warning)
  → confirm → working tree restored to that commit

Conservative by design: the index is untouched, the rollback itself is never auto-committed, and untracked files are out of scope (they were never committed, so their provenance is unknown). Conversation rewind reuses pi's session-tree navigation, so nothing is ever deleted from the session file.

Configuration

Optional taskTracker key in ~/.pi/agent/settings.json (all default to true):

{
  "taskTracker": {
    "todo": true,
    "readme": true,
    "autoCommit": true
  }
}

• todo — maintain TODO.md (false: neither created nor maintained)
• readme — maintain the README.md project-structure section (false: neither created nor maintained)
• autoCommit — per-task commits; these are the /rollback checkpoints, so disabling this also disables rollback targets
• guard — master switch for the built-in permission layer (default true). Set false to defer permission decisions entirely to another extension (e.g. pi-permission-system): no external-write checks, no git-ask prompts, no cd sandbox.
• externalWrite — policy for tool calls that would create/modify files OUTSIDE the session directory: "ask" (default, per-attempt confirmation), "warn" (allow + yellow UI notice, no prompt), "block" (hard deny — external changes cannot be tracked or rolled back), "off" (no enforcement; defer permission decisions to another extension). Reads stay free. Copying files FROM outside INTO the session is allowed (cp checks only its destination); moving/deleting external paths is checked. Everything INSIDE the session directory passes by default. Git history protection is built in: history-rewriting git (rebase/reset/amend/force-push/clean/...) prompts for confirmation, routine git passes untouched, and an external git init/clone is allowed with a heads-up that the new repo is not tracked. Git-Bash/MSYS paths (/c/Users/..., /cygdrive/c/...) are normalized before evaluation, so drive-absolute forms do not false-positive as external; /tmp and other non-drive names stay external (they resolve outside the session on Windows). Shell commands are analyzed statically (redirects, rm/mv/cp/touch/..., PowerShell equivalents; redirect targets and -C destinations on git segments), with shell quoting honored: quoted text is DATA, not a path list, so sed 's/^/ /' is a single argument and never resolves to /; sed counts as a write only with -i/--in-place (without it every operand is a read and the script argument is an expression), so filter pipelines stay free. cd/Set-Location never violate by themselves (they write nothing, and every pi shell call starts pinned at the session root, so a cd cannot outlive its command): the effective working directory is tracked within the command and actual write targets are judged against it, while the outside-session decision always compares against the session root. cd .. && ls is silent; cd /tmp && echo x > f.txt is flagged at the real target; an unresolvable cd (~/x, cd $DIR) makes later relative targets conservatively external.
• Static-analysis edge cases (0.2.9) — two false positives are gone, both found by replaying a real session's commands against the guard. (1) A > inside quotes is data, not a redirect: sed 's/=.*KEY.*/=<redacted>/' used to have its > read as a redirect whose "target" parsed as /', normalized to /, and got reported as a write to the filesystem root. Quoted spans are now detected before redirect targets are extracted. (2) Interpreter payloads (python -c "...") only match a path that STARTS at a token boundary, so a relative ".venv/Scripts/python.exe" is no longer read as the absolute /Scripts/python.exe, and a/b/c.py is no longer read as /b/c.py. Genuine absolute paths in payloads (python -c "open('/etc/hosts')") are still caught.
• CJK path names (0.2.10) — the 0.2.9 token-boundary rule only excluded ASCII word characters, so a relative path under a non-ASCII directory still leaked its tail: 第6章_逆向/experiments_p5/generate_paper5_figures.py was reported as a write to /experiments_p5/generate_paper5_figures.py (CJK letters are not ASCII word chars, so 验 looked like a boundary). The boundary is now a Unicode-aware lookbehind that excludes ANY letter/digit (\p{L}/\p{N}) plus path punctuation; drive-absolute paths after CJK text (p='C:/Windows/...') are still caught.
• cd is no longer a violation (0.2.11) — the guard used to flag any cd that left the session directory (cd .. && ls, cd 论文 && latexmk … && cd .. && python audit_all.py), which was pure noise on read-only workflows and misnamed the offending path. cds are now tracked within the command and only actual writes are judged: cd /tmp && echo x > f.txt is still blocked — now reporting the real target — and cd deep/sub && echo x > ../../outside/f.txt (which lands back inside the session) is no longer over-blocked. Every pi shell call starts pinned at the session root, so a cd cannot outlive its command.

Requirements

• pi coding agent with the extension API
• git on PATH
• Works with or without pi-hashline-edit-pro

Limitations

• Rollback granularity is per task (agent turn-set), not per message. If you need message-level time travel including your own manual edits, a snapshot-based extension is a better fit — at the cost of full-worktree scans every turn.
• Files created by shell commands inside a nested repo that was never touched via write/edit during the session are not captured.
• Out-of-scope by design — files outside the session directory (and outside its owning repo) are neither recorded nor rolled back: no new commits in their repos, no worktree changes. /rollback only ever touches the session's own repo scope, so sibling projects are safe even when the agent writes there via absolute paths — but such changes have no checkpoint.
• An embedded (unregistered) sub-repo shows as ?? dir/ in the outer git status — that's standard git behavior; this extension never stages it.

本简介（中文）

pi-task-tracker 为 pi coding agent 提供任务级工作流跟踪：每次任务完成时，agent 实际改动的文件被自动提交到你的分支（提交信息即任务名），这些提交同时构成检查点；/rollback 可交互式地把工作区回滚到任意历史提交，同时把对话上下文回退到产生该提交的任务轮次（文件与上下文同一检查点；仅工作区、不自动提交、可逆，旧会话分支保留可 /tree 回访）。支持 hashline 编辑工具、bash/powershell 产物捕获、嵌套仓库归属最内层、自动排除 .pi-subagents/ 会话数据。配置项见上方 taskTracker。

License

MIT

Overview

TODO: Add project description.

Project Structure

pi-task-tracker/