agent-worktree-janitor

agent-worktree-janitor 是一个离线、安全优先的 AI agent 工作区清理计划工具。它面向同时运行 Codex、Claude Code、Cursor、多 git worktree、多分支实验的开发者和团队，扫描本地工作区、解析 git status --porcelain 与 git worktree list --porcelain 输出，识别缓存、构建产物、报告文件、临时输出、过期未跟踪文件、大文件、孤儿 worktree，并生成可审阅的 cleanup plan。

它不会自动删除任何东西。默认行为只是生成 Markdown、JSON、JUnit、summary、Bash、PowerShell 报告和 CI 退出码，帮助你回答：

• 哪些 agent 运行产物可以安全清理。
• 哪些文件需要人工确认。
• 哪些 worktree 已经 prunable 或可能是旧 agent 分支。
• 哪些大文件、未跟踪文件或构建产物不应该进仓库。
• CI 是否应该阻止一个“工作区太脏”的 PR 或交付包。
• PR、CI step summary 或 agent 交接里应该怎样简短说明当前清理状态。
• 如果 reviewer 已确认，哪些清理命令可以手动解注释执行。

项目只使用 Python 标准库，兼容 Python 3.9+，没有外部运行时依赖。

适用场景

• 多 agent 并行开发：一天开很多 Codex/Claude Code 任务后，统一生成清理计划。
• worktree 管理：识别 agent/* 分支 worktree、prunable worktree、路径缺失 worktree。
• 发布前收口：在公开项目发布前检查是否有缓存、报告、大文件或临时输出。
• CI hygiene gate：让 PR 在包含明显构建产物或大未跟踪文件时失败。
• 交接审计：把 cleanup plan 放进交付证据，让 reviewer 看见哪些东西被保留、哪些建议删除。

安装

python -m pip install -e .

或不安装直接运行：

PYTHONPATH=src python -m agent_worktree_janitor --root examples/workspace --no-fail

快速开始

最省事的方式是让工具自己只读采集 git 信息：

agent-worktree-janitor \
  --root . \
  --collect-git \
  --out reports/janitor \
  --formats summary,markdown,json,junit,scripts \
  --no-fail

如果你希望在 CI 中显式保存输入，也可以先导出 git 信息：

git status --porcelain > /tmp/status.txt
git worktree list --porcelain > /tmp/worktrees.txt

生成清理计划：

agent-worktree-janitor \
  --root . \
  --git-status-file /tmp/status.txt \
  --worktree-file /tmp/worktrees.txt \
  --config janitor.config.json \
  --out reports/janitor \
  --formats summary,markdown,json,junit,scripts

输出：

• janitor-plan.md：给人看的清理建议。
• janitor-summary.md：适合 PR、CI step summary、agent 交接的短摘要。
• janitor-plan.json：给 agent 或自动化脚本消费。
• junit.xml：给 CI 展示高风险项。
• cleanup-plan.sh：默认注释掉的 Bash 清理命令计划。
• cleanup-plan.ps1：默认注释掉的 PowerShell 清理命令计划。

CLI

agent-worktree-janitor [options]

常用参数：

• --root：要扫描的工作区根目录。
• --config：JSON 配置文件。
• --git-status-file：git status --porcelain 输出文件。
• --worktree-file：git worktree list --porcelain 输出文件。
• --collect-git：从 --root 运行只读 git 命令自动采集 status 和 worktree 信息。
• --out：报告输出目录。
• --formats：markdown,json,junit,summary,bash,powershell,scripts,all。
• --no-fail：只生成报告，不用风险分数影响退出码。
• --print-config：打印有效配置。

脚本格式说明：

• summary、brief、pr 写入 janitor-summary.md。
• bash 写入 cleanup-plan.sh。
• powershell 写入 cleanup-plan.ps1。
• scripts 同时写入 Bash 和 PowerShell 版本。
• 破坏性命令默认都是注释；请先 review，再手动删除某一行开头的 #。
• 已跟踪改动和包含换行的路径不会生成删除命令，只会标记为手动处理。

API

from agent_worktree_janitor import build_cleanup_plan
from agent_worktree_janitor.config import JanitorConfig

plan = build_cleanup_plan(
    root=".",
    config=JanitorConfig(),
    status_text="?? reports/run.md\n",
    worktree_text="",
)

print(plan.to_dict())

输入格式

git status

使用 git status --porcelain 文本：

?? reports/agent-run.md
?? .cache/session.bin
 M src/app.py
A  important/keep.txt

git worktree

使用 git worktree list --porcelain 文本：

worktree /tmp/project-agent
HEAD 2222222222222222222222222222222222222222
branch refs/heads/agent/refactor-login

配置

{
  "ignore_patterns": [".git/**", "**/.git/**"],
  "keep_patterns": ["important/**", "README.md"],
  "cache_patterns": ["**/__pycache__/**", "**/.cache/**"],
  "build_patterns": ["**/dist/**", "**/build/**", "**/node_modules/**"],
  "report_patterns": ["**/reports/**", "**/*.log", "**/*.tmp"],
  "large_file_bytes": 5242880,
  "stale_days": 14,
  "fail_score": 80
}

扫描规则

• cache：通常可再生，建议 delete，低风险。
• build：构建或依赖产物，建议 delete，中风险。
• report：生成报告、日志、临时输出；新文件建议 review，过期文件建议 delete。
• large-untracked：大未跟踪文件，高风险，需要人工确认。
• stale-untracked：过期未跟踪文件，中风险，需要人工确认。
• kept：命中 keep pattern，只记录保留。

风险等级

风险分数取文件和 worktree finding 的最高分，再叠加 warning 数量。达到 fail_score 时退出码为 1。

典型策略：

• 本地日常清理：使用 --no-fail。
• 发布前检查：fail_score=80。
• 严格 CI：降低 fail_score，并让 high risk 进入 JUnit failure。

CI / Agent 集成

GitHub Actions：

- name: Workspace hygiene plan
  run: |
    git status --porcelain > status.txt
    git worktree list --porcelain > worktrees.txt
    agent-worktree-janitor \
      --root . \
      --git-status-file status.txt \
      --worktree-file worktrees.txt \
      --out reports/janitor \
      --formats summary,markdown,json,junit,scripts

本地或简单 CI 中也可以直接只读采集：

agent-worktree-janitor --root . --collect-git --out reports/janitor --formats summary,markdown,json,junit,scripts --no-fail

Agent 使用建议：

• 让 agent 在交付前运行本工具，把 janitor-plan.md 放到 PR 描述。
• 把 janitor-summary.md 写入 GitHub Actions step summary 或 agent handoff。
• 把 cleanup-plan.sh 或 cleanup-plan.ps1 作为 artifact 上传，让 reviewer 看见实际待确认命令。
• 不要让 agent 自动执行删除；先让人 review plan。
• 如果 reviewer 确认某个低风险缓存或构建产物可删，再手动解注释对应命令。
• 对 large-untracked、stale-untracked、prunable worktree 单独确认。

限制

• 默认不调用 git 命令，只解析你提供的文本输出；启用 --collect-git 时会运行只读 git 命令采集 status 和 worktree 信息。
• 不删除文件，也不执行 git worktree prune。
• 文件年龄来自本地 mtime；复制目录后年龄可能变化。
• glob 规则是安全启发式，不替代团队自己的保留策略。

开发

PYTHONPATH=src python -m unittest discover -s tests -v
PYTHONPATH=src python -m agent_worktree_janitor \
  --root examples/workspace \
  --git-status-file examples/git-status.txt \
  --worktree-file examples/worktrees.txt \
  --config examples/janitor.config.json \
  --out reports \
  --formats summary,markdown,json,junit,scripts \
  --no-fail

发布前检查：

• README 中英双语。
• python -m unittest discover -s tests 通过。
• GitHub Actions 通过 Python 3.9 和 3.12。
• 不提交真实客户路径、密钥、缓存或机器本地 artifact。

English

agent-worktree-janitor is an offline, safety-first cleanup plan generator for AI-agent workspaces. It helps teams using Codex, Claude Code, Cursor, multiple git worktrees, and many experimental branches review what can be cleaned up after agent runs.

It scans a workspace, parses git status --porcelain and git worktree list --porcelain text, classifies cleanup candidates, scores risk, and writes Markdown, JSON, JUnit, summary, Bash, and PowerShell review artifacts. It never deletes files.

Use Cases

• Review workspace leftovers after many agent sessions.
• Find cache folders, build outputs, generated reports, logs, and large untracked files.
• Identify prunable or missing git worktrees.
• Add a CI hygiene gate before publishing a repository or accepting an agent delivery.
• Produce reviewable cleanup evidence for pull requests.
• Write short PR/CI/agent handoff summaries.
• Generate commented cleanup command plans for reviewers who want executable next steps.

Install

python -m pip install -e .

Or run without installation:

PYTHONPATH=src python -m agent_worktree_janitor --root examples/workspace --no-fail

CLI

agent-worktree-janitor \
  --root . \
  --collect-git \
  --config janitor.config.json \
  --out reports \
  --formats summary,markdown,json,junit,scripts

Important options:

• --root: workspace root.
• --config: JSON configuration.
• --git-status-file: captured git status --porcelain output.
• --worktree-file: captured git worktree list --porcelain output.
• --collect-git: run read-only git collection commands from --root.
• --formats: markdown,json,junit,summary,bash,powershell,scripts,all.
• --no-fail: report-only mode.
• --print-config: print effective defaults.

Script formats:

• summary, brief, and pr write janitor-summary.md.
• bash writes cleanup-plan.sh.
• powershell writes cleanup-plan.ps1.
• scripts writes both shell plans.
• Destructive commands are commented out by default. Review first, then uncomment only the accepted lines.
• Tracked changes and paths containing line breaks are marked for manual handling instead of receiving delete commands.

Model

The tool creates a cleanup plan with file findings and worktree findings. Each item has:

• action: delete, review, or keep
• risk: low, medium, or high
• score
• reason
• tracked state when git status data is available

The CI exit code fails when the plan risk score reaches fail_score.

Limitations

The tool does not run destructive commands or delete files. By default it only parses provided git text; with --collect-git it runs read-only git collection commands. It is a planner and gate, not an automatic cleanup tool. Always review the plan before removing files or pruning worktrees.