wip:一個指令,讓 AI agent 一秒看懂每個專案做到哪

wip:一個指令,讓 AI agent 一秒看懂每個專案做到哪封面

快速連結

GitHub:yazelin/wip

下載安裝:Releases

我想解決的問題

我手上同時在飛的 repo 不只一個。一天分散在好幾個專案裡寫東西,常常一開新的 session,第一個動作就是繞一圈:這個 repo 在哪條 branch?上次 commit 是什麼時候?有沒有沒推上去的東西?還有沒結的 PR?上次寫到哪了?

更煩的是,Claude Code 或 Codex 一進來什麼都不知道。 它得自己跑一堆 git status、git log、gh pr list 才能拼出「現在到底在哪」。這些指令吐出來的東西又雜又長,白白吃掉 context。

wip 就是把這件事收斂成一條指令:掃完所有我在追的 repo,輸出一份精煉的狀態。人看 terminal 表格,AI agent 跑 wip --md 吞 markdown —— 兩邊讀的是同一份事實。

它掃出什麼

對每個 repo,wip 收集這些(都是真的去 shell out git / gh 拿的,不是猜的):

current branch —— git rev-parse --abbrev-ref HEAD。
last commit —— 相對時間、訊息、short SHA(例:2 hours ago - did thing (abc123))。
dirty / unpushed —— working tree 有幾個檔有動(git status --porcelain 行數)、有幾個 commit 還沒推上去(@{u}..HEAD)。沒設 upstream 就當 0,不會炸。
open PRs / issues —— 透過 gh pr list / gh issue list。gh 是 optional:沒裝、沒登入,PR/issue 欄位就顯示 -,其餘 git 狀態照常出。
progress 尾巴 —— 抓 repo 根目錄的 progress.md(或 PROGRESS.md / docs/progress.md)的最後一個 ## 區塊,當作「這個 repo 最近在發生什麼」的一句話敘述。

repo 排序是最近有 commit 的排前面,所以一眼就看到哪個專案最熱。

給人看 vs 給 AI 看

同一份資料,三種輸出:

wip                 # terminal 表格,最近 commit 的 repo 排最前
wip --md            # markdown digest(給 Claude Code / SessionStart hook 吃)
wip --json          # 結構化輸出
wip --root ~/some/dir   # 臨時掃某資料夾下的子目錄,忽略 config

--md 是給 agent 的入口。它長這樣,每個 repo 一個 ## 段:

## web-app (main)
- last: 2 hours ago - wire up auth (abc123)
- local: 3 dirty, 1 unpushed
- PR #12: refactor session store
- open issues: 4
- progress: ## 2026-06-05 finished login flow, next is token refresh
- next:
  1. token refresh
  2. e2e for logout
- see: ROADMAP.md

刻意全 ASCII、沒有任何 emoji,連 [3 dirty]、PR: none 都是純文字 —— 這是作者自己的偏好,README 裡明寫了。對 agent 來說也好,一行就是一行,不用去解析符號字形。

跟 Claude Code / Codex 接起來

最有感的是這個:讓 agent 每次 session 一開始就自動拿到跨 repo 狀態,不用我手動貼。

wip install-hook

這會裝一個 SessionStart hook,進 Claude Code(~/.claude/settings.json)和 Codex(~/.codex/hooks.json)兩邊。安裝是 idempotent 的:先各自備份成 .bak,已經有 wip hook 就跳過,該建的目錄會建,其他既有設定不動。hook 跑的是 wip hook —— 印出 markdown 板、跳過 gh(不連網、session 啟動快),沒設 repo 就安靜不出聲。

Codex 有一步要手動:它會跳過未信任的 hook,所以 install-hook 之後要在互動 Codex session 裡跑一次 /hooks 把這條 hook trust 起來(hook 指令改了要重 trust)。install-hook 自己會印這個提醒。

hook 是被動推:session 一開就塞狀態進來。如果還想讓 agent 主動學會 wip 的指令面 —— 還有 hook 沒覆蓋到的 Codex —— 就把它裝成 skill:

wip install-skill   # 寫進 ~/.claude/skills/wip/ 和 ~/.codex/skills/wip/

skill 定義是內嵌在 binary 裡的(runtime 不需要 repo 在),agent 讀了就學會跑 wip --md 拿新鮮快照、用 wip next / wip done 管某個 repo 的 NEXT.md。

隨身的 next-action:NEXT.md

每個 repo 可以帶一個根目錄的 NEXT.md —— 一份純 markdown 的待辦清單,跟著 code 走 git,所以你的下一步永遠就在 repo 旁邊,換機器也在。板上會把未完成項目逐 repo 編號顯示。

wip next <repo> "finish the thing"   # 在 <repo>/NEXT.md 追一條 "- [ ] finish the thing"
wip done <repo> 1                    # 把第 1 個 OPEN 項目翻成 "- [x]"

<repo> 可以是 config 裡的 basename,也可以是 repo 路徑。注意 wip 只寫 NEXT.md、不會幫你 commit —— 跟著你其他的改動一起提交就好。

板上還會多一行 see:,列出它在 repo 根目錄找到的常見規劃檔(ROADMAP.md / TODO.md / PLAN.md / BACKLOG.md)—— 只列檔名當指標,不會去解析內容,要深入脈絡自己去讀。

怎麼裝

不需要 Rust。到 Releases 抓對應 OS 的壓縮檔,把 wip binary 放到 PATH:

# Linux x86_64
tar xzf wip-*-linux-x86_64.tar.gz
install -m 755 wip ~/.local/bin/wip       # 確認 ~/.local/bin 在 PATH

# 指向你要追的 repo
mkdir -p ~/.config/wip
cp repos.example.toml ~/.config/wip/repos.toml   # 編這份清單

# 選用:讓狀態在 Claude Code session 開始時自動載入
wip install-hook

install-hook 記的是你執行它那顆 wip 的絕對路徑,所以你放到 PATH 上的 release binary,就正好是 hook 會叫的那顆。

從源碼裝:

cargo install --git https://github.com/yazelin/wip
mkdir -p ~/.config/wip
cp repos.example.toml ~/.config/wip/repos.toml

repos.toml 就是一份你想追的 repo 清單,~ 會展開成家目錄,絕對路徑也行。清單建議只留真正在飛的那幾個。

一點設計上的取捨

wip 的依賴很少 —— clap / serde / toml 而已,沒有任何 HTTP crate。它不自己連網:PR/issue 全靠 shell out 給你本機的 gh,沒有 gh 就乾脆降級。所以它沒有任何 token、沒有任何雲端、資料就是你本機那些 repo。

它也很誠實地知道自己只是個快照:skill 文件裡寫得很清楚 —— 事實的來源是 live 的 repo,不是 digest 文字;某個數字看起來舊了,就重跑一次,別信先前注入的那份。對 agent 來說這是重要的提醒,免得拿著 session 開頭那份過時狀態當真。

Roadmap 上 v1(唯讀狀態)、v2(next / done + see: 指標)、v3a(SessionStart hook)都已經完成,v3b 規劃中 —— 跨平台預編 binary + CI。

這工具很小,但它幫我把「每天開工繞一圈確認狀態」這件雜事收乾淨了,也讓 AI agent 一進來就站在跟我同一個起點。如果你也同時在好幾個 repo 之間跳,或者常用 Claude Code / Codex 跑開發,也許用得上。

想支持持續開發? 請我喝杯咖啡 → buymeacoffee.com/yazelin