docsweep

English version: README.en.md

AI コーディングツール（Claude Code / Codex 等）が生成する plan_*.md / bugfix_*.md / pending_*.md の 蓄積・陳腐化問題を解決する クロスプラットフォーム CLI + Web UI ツール。

H1 ステータスラベル（[完了] / [計画] / [廃止] 等）を機械的に読み取り、完了を各プロジェクトの archive/ へ自動移送し、陳腐化を「要判断」フラグで可視化し、複数プロジェクトを横断 INDEX で一望できます。

OKF（Open Knowledge Format）v0.2 対応

docsweep は OKF v0.2 の公式仕様 に合わせ、Markdown frontmatter の type / status を機械可読に扱います。 OKF の status は文書ライフサイクル（draft / stable / deprecated）なので、 docsweep の作業状態（planned / in-progress / watching / done / discarded / pending）は拡張フィールド docsweep_state に分離しています。

type と追加フィールドは OKF の方針どおり閉じた登録簿にせず、docsweep が標準管理する plan / bugfix / pending 以外も壊さず保持します。manual / reference / setup は 静的な知識文書として扱い、H1 ラベルは 人間向け表示として併用し、旧形式の status: planned なども読み取り互換を維持します。 既存ファイルを移行するときは migrate-frontmatter --dry-run で差分を確認してから --apply を実行してください。

詳細な対応表は docs/okf-mapping.md、Bundle の構造は docs/okf-export-format.md を参照してください。

インストール

pip install docsweep                  # コア + CLI（wings の主要コマンド・SQLite 索引込み）
pip install 'docsweep[all]'           # Web UI / 対話レビュー / MCP / watch / resurrect も含む
pip install 'docsweep[watch]'         # index-watch のみ追加（watchdog）
pip install 'docsweep[resurrect]'     # resurrect の embedding 経路（sentence-transformers）

docsweep は PATH に docsweep コマンドを通さない運用を標準にしています。 CLI / Web UI / MCP は、Python 実行ファイルから module として起動できます。

python -m docsweep triage
python -m docsweep mcp
python -m docsweep serve --root ~/dev

MCP クライアントへ登録する場合も、docsweep mcp ではなく python -m docsweep mcp を推奨します。より再現性を上げるなら、command には Python 実行ファイルの絶対パスを指定します。

{
  "mcpServers": {
    "docsweep": {
      "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["-m", "docsweep", "mcp"]
    }
  }
}

上記の Python312 は インストールされている Python のバージョンに置き換えてください。 確認方法: Windows は where python、macOS / Linux は which python3。 もしくは python -c "import sys; print(sys.executable)" でフルパスが取れます。

docsweep ... は Python の Scripts/bin ディレクトリが PATH に入っている環境向けの短縮形です。

インストール後どこに置かれて、どう使えるか（OS 別）

pip install docsweep は Python の site-packages にライブラリを配置します。 別バイナリは生成されず、python -m docsweep ... で起動するのが標準動線です。

共通の挙動

• docsweep/ パッケージ本体: 起動中の Python が解決する site-packages に展開される
• 設定・状態: ~/.docsweep/（全 OS 共通の論理パス）
• MCP 設定: AI クライアント（Claude Code 等）の設定ファイルに python -m docsweep mcp を 1 行登録するだけ
• PATH 設定不要: docsweep を PATH に通さなくても、python -m docsweep ... ですべての機能にアクセス可能

Windows

Windows ストア版 Python は避けることを推奨。%LOCALAPPDATA%\Microsoft\WindowsApps\python.exe 経由のストア版は仮想ストア配置の制約で Scripts/ ディレクトリへの書き込みが弾かれることがあり、 pip install 自体は通っても docsweep.exe ランチャーが正しく作られない／PATH に乗らないトラブルが 起きます。python.org 配布のインストーラ（per-user）か pyenv-win を使うのが安全です。

# インストール
pip install 'docsweep[all]'

# 起動（PATH を気にせず常に動く形）
python -m docsweep triage
python -m docsweep serve --root D:\dev
python -m docsweep mcp

# MCP 登録例（~\.claude\mcp.json）— 絶対パスにすると Python 切替時も安定
# {
#   "mcpServers": {
#     "docsweep": {
#       "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
#       "args": ["-m", "docsweep", "mcp"]
#     }
#   }
# }
# Python312 は実環境のバージョンに置換。確認: `where python` または `python -c "import sys; print(sys.executable)"`

macOS

# インストール（PEP 668 で system Python 保護がかかっていれば --user か venv 経由を選ぶ）
pip3 install 'docsweep[all]'

# 起動
python3 -m docsweep triage
python3 -m docsweep serve --root ~/dev
python3 -m docsweep mcp

# MCP 登録例（~/.claude/mcp.json）
# {
#   "mcpServers": {
#     "docsweep": {
#       "command": "/opt/homebrew/bin/python3",
#       "args": ["-m", "docsweep", "mcp"]
#     }
#   }
# }
# 自環境の Python パスは `which python3` で確認

Linux

PEP 668 注意（Ubuntu 23.04+ / Debian 12+ / Fedora 38+ など）: 近年の distro は system Python を保護しており、 素の pip install は error: externally-managed-environment で拒否されます。 解決策は venv か --user か pipx のいずれか（下記コマンド例の通り）。 --break-system-packages フラグでの強行は OS 管理パッケージとコンフリクトする原因になるので推奨しません。

# 多くの distro は system Python を pip で汚せない。venv か --user か pipx を推奨
python3 -m venv ~/.venvs/docsweep && source ~/.venvs/docsweep/bin/activate
pip install 'docsweep[all]'

# または
pip install --user 'docsweep[all]'

# 起動
python3 -m docsweep triage
python3 -m docsweep serve --root ~/dev
python3 -m docsweep mcp

# MCP 登録例（~/.claude/mcp.json）— venv 内 Python の絶対パスを指定する
# {
#   "mcpServers": {
#     "docsweep": {
#       "command": "/home/you/.venvs/docsweep/bin/python",
#       "args": ["-m", "docsweep", "mcp"]
#     }
#   }
# }
# 自環境の Python パスは `which python3` で確認

インストール形態を選ぶ

アンインストール

pip uninstall docsweep
# 設定を消したい場合は別途
rm -rf ~/.docsweep                # macOS / Linux
Remove-Item -Recurse ~/.docsweep  # Windows PowerShell

使い方

朝の入口は brief: 何も思い出せなくても python -m docsweep brief で「今日の 1 個」が断定的に出ます。 プロジェクト横断は python -m docsweep cross。詳細: docs/ai-agent-integration.md。

# === wings（v0.2 系）の主要新コマンド ===

# 朝の入口 — 今日 1 個だけやろうを断定する（cwd プロジェクト）
python -m docsweep brief
python -m docsweep brief --all              # 全プロジェクト横並び要約
python -m docsweep brief --continue         # 末尾の対話を出さず context を即クリップボードへ

# 全プロジェクト束ねた俯瞰 — top_pick + 凍結予備軍 + project_summaries
python -m docsweep cross
python -m docsweep cross --project alpha,beta
python -m docsweep cross --explain plan_x.md   # スコア内訳

# 会話履歴から plan/bugfix/pending の草案を抽出（heuristic / LLM mock）
python -m docsweep capture --from clipboard
python -m docsweep capture --from file ./conv.md --save-all

# plan の「変更予定ファイル」と実装実態の整合チェック
python -m docsweep linkcheck --json

# 親 plan と child plan の closeout 検査（read-only。状態変更・archive はしない）
python -m docsweep closeout-check --path docs/local/plan_<parent>.md --to watching --json

# 状態遷移を提案（ruleset / 将来 LLM 委譲）+ 一括適用
python -m docsweep auto-triage --suggest > decisions.json
python -m docsweep auto-triage --apply decisions.json --dry-run

# 関係性ネットワーク（plan/bugfix/pending と frontmatter related のグラフ）
python -m docsweep graph --json

# archive と現役の類似ペアを抽出（embedding opt-in / 既定は Jaccard）
python -m docsweep resurrect --threshold 0.5

# SQLite 索引 ~/.docsweep/index.db
python -m docsweep index-sync               # 差分のみ取り込み（高速）
python -m docsweep index-rebuild            # 全件再構築
python -m docsweep index-watch              # ファイル監視で自動同期（watchdog 必要）

# === 従来コマンド（既存・後方互換） ===

# スキャン（既定は要判断＋保留のみ表示）
python -m docsweep --root ~/dev
python -m docsweep ./thisproject            # config 不要の単発スキャン
python -m docsweep scan --all --json        # 全件を機械可読 JSON で

# 自動移送（cron / CI / AI 委譲向け・非対話）。done/discarded のみ・様子見は守る
python -m docsweep sweep --dry-run
python -m docsweep sweep

# 横断 INDEX を再生成（.docsweep/INDEX.md と INDEX.json）
python -m docsweep index
python -m docsweep pending                  # 全プロジェクトの [保留] だけ一発表示
python -m docsweep report                   # 人間向け週次レポート
python -m docsweep summary                  # AI に渡す圧縮 JSON

# リリース整理（様子見をまとめて完了へ昇格し archive へ）
python -m docsweep promote --state watching --to done
# 卒業期限が来た様子見だけを下見／昇格（due 当日を含む）
python -m docsweep promote --due-expired --dry-run
python -m docsweep promote --due-expired

# 今回だけ卒業期限を今日 + 5 日に上書き（設定ファイルは変更しない）
python -m docsweep apply --path <plan-or-bugfix.md> --action relabel --to watching --watching-days 5

# 対話チェックリスト（人間専用）
python -m docsweep review

# テンプレ即生成
python -m docsweep new plan my-topic
python -m docsweep new bugfix crash-on-start
python -m docsweep new plan my-topic --split 3  # child に docsweep_parent を付ける

# OKF 互換 zip でエクスポート（docsweep を抜けても md が腐らないことを実演する材料）
python -m docsweep export --okf                          # ./docsweep-okf-<date>.zip
python -m docsweep export --okf --out /tmp/snapshot.zip  # 出力先を明示
python -m docsweep export --okf --include-archive        # archive/ 配下も含める

# 任意 Bundle を read-only 検査（未知 type / 追加キー / 壊れた link は警告扱い）
python -m docsweep okf-check ./bundle --json
python -m docsweep okf-profiles

# profile は既定では同梱 JSON。外部 profile は明示したときだけ取得する
python -m docsweep export --okf --okf-profile ./okf-profile.json
python -m docsweep okf-check ./bundle --okf-profile https://raw.githubusercontent.com/<org>/<repo>/<sha>/okf.json --okf-profile-sha256 <sha256>

# 運用ルールを各プロジェクトへ注入／取り消し（CLAUDE.md=正本・AGENTS.md はそこを指すポインタ）
python -m docsweep inject --project ./foo --preset claude-jp
python -m docsweep inject --project ./foo --no-guidance   # 導線を省きラベル節だけ（導線をグローバルに寄せる場合）
python -m docsweep eject  --project ./foo                  # 管理ブロックだけ剥がす（手書きは温存。--purge で .docsweep.yaml も）

# 個人グローバルへ「セッション開始時に triage を読む」導線＋due ルールを一度だけ注入（全プロジェクトで有効）
python -m docsweep inject --global                         # 既定 agent=claude（~/.claude/CLAUDE.md に @import 1 行）
python -m docsweep inject --global --agent codex           # ~/.codex/AGENTS.md にインライン（CODEX_HOME 尊重）
python -m docsweep inject --global --lang en               # 注入文言を英語で生成（プロジェクト注入でも --lang 可）
python -m docsweep eject  --global

python -m docsweep list                                    # 注入済み（プロジェクト＋グローバル）一覧

# Web UI（UX 主役・127.0.0.1・初回だけ ?token= 付き URL、以降は Cookie で /board を直接開ける）。注入/解除もダッシュボードから（プレビュー必須）
python -m docsweep serve --root ~/dev

# MCP サーバー（AI エージェント面・stdio）
python -m docsweep mcp

Web UI（看板）はこんな見た目です。

「完了」「廃止」になったカードは archive 候補列にまとまり、まとめて archive へ送れます。

状態モデル（一直線・単一正本）

plan:    [保留] → [計画] → [実行中] → [様子見] → [完了]
bugfix:           [実行中] → [様子見] → [完了]
         （どちらも、どの状態からでも [廃止] へ分岐できる）

• [様子見] = 直したが寝かせ中。自動移送されません（再発確認の待機列として守る）。
• [完了] / [廃止] だけが archive 対象。[廃止] は削除ではなく archive へ隔離（復元可能）。
• 移送先は archive_dir を明示しなければ work queue に連動します。work_policy: private （既定）なら <work_dir>/archive（既定 docs/local/archive）、shared なら repo 直下 archive/。private な作業文書を git 追跡され得る場所へ黙って出さないための既定です。 移送先と選択根拠は python -m docsweep sweep --dry-run --json の archive_routes で 確認できます。
• ラベル語彙・archive 可否・自動移送可否は states: 設定が 唯一の正本で、検出・Web 表示・ 注入テンプレを全部そこから導出します。

設定の層

優先順位 ① CLI フラグ > ② プロジェクト .docsweep.yaml > ③ グローバル ~/.docsweep/config.yaml。 グローバルだけ書けば体感 1 層。.docsweep.yaml は置いた時だけ部分上書きで効きます。

よくある 3 パターン（グローバル ~/.docsweep/config.yaml）

プロジェクト境界は .git / package.json / pyproject.toml 等の実体マーカーで自動判定するので、 root の中で各プロジェクトがどの深さにあっても OK（フォルダ階層を決め打ちしない）。

A. 1 つの親ディレクトリ以下を丸ごと管理

roots:
  - ~/dev

B. 飛び飛びの複数ディレクトリを管理

roots:
  - ~/dev/github/public
  - ~/dev/works/clientA
  - ~/dev/works/clientB
  - /d/sandbox/experiments

C. 用途別に切り替えたい（profiles）

roots:
  - ~/dev/github/public        # 既定（無引数）で見る範囲
profiles:
  work:                         # python -m docsweep triage --profile work
    - ~/dev/works/clientA
    - ~/dev/works/clientB
  all:                          # python -m docsweep triage --profile all
    - ~/dev/github/public
    - ~/dev/works

一回きりの単発スキャンは config を書かずに位置引数で指定もできます:

python -m docsweep triage ~/dev/foo ~/projects/bar

作業 queue と private ドキュメント

new / capture --save-all / MCP capture_save は、同じプロジェクト相対 work_dir に保存します。 未設定時の既定は docs/local で、プロジェクトに docs/ があるかどうかで保存先は変わりません。

work_dir: docs/local       # プロジェクト相対。例: docs/ai
work_policy: private       # private は Git ignore / tracked 状態を保存前に検査
secret_policy: block       # high-confidence secret は拒否。warn / off も選択可

解決順は CLI の --work-dir / --work-policy / --secret-policy、プロジェクト設定、 グローバル設定の順です。private queue は export の既定対象から除外され、brief / triage は Git ignore されていても設定済み queue を確認できます。秘密情報の警告や JSON / UI の表示には本文・値の一部を含めません。 必要な場合だけ --allow-sensitive を明示してください。

初回は python -m docsweep init で既定設定を作り、各プロジェクトでは python -m docsweep inject の導線と python -m docsweep new plan <topic> を使います。

作成AIとC単位の実行AI（opt-in）

個人の ~/.docsweep/config.yaml で provenance を有効にすると、新規work MDへ work_id、固定の ai_author_*、ai_execution_refs を追加し、実行本体はリポ外の 個人台帳へ1実行1行で保存できます。

作成したセッションのtranscript（AI CLI 自身が残す生ログ）のフルパスを ai_session_logs に 記録します。md の記述だけでは追えない判断の経緯へ、後から会話ログで戻れるようにするためです。 記録するのはパスだけで中身は読みません。work_policy: private のqueueに限り、かつ実在する ときだけ書きます。

plan は複数セッションにまたがるため、provenance start でC実行を開始したときにも そのセッションのパスを追記します（同じパスは重複しません）。作成時の1本だけでは C2以降を誰がどの会話で実装したのか追えないためです。解決できないセッションでは キー自体を書きません（unknown のような偽の値を置きません）。

対応は Claude Code / Codex / Grok / Copilot / Cursor Agent です。Claude Code はセッションIDを 環境変数に出すため確実に一致します。それ以外は「作業ディレクトリが一致し、直近まで書かれ続けて いるセッションが1つだけ」のときに限って記録し、2つ以上に絞れなければ何も書きません （別セッションのログを指すくらいなら残さない）。opencode は全セッションが単一のSQLiteに集約され 1セッションを特定できないため対象外です。自動解決できないときは --ai-session-log <path> で 明示するか、DOCSWEEP_AI_SESSION_LOG を設定します。

provenance:
  enabled: true
  manager: docsweep
  ledger: provenance/ai-executions.csv
  actor_key: your-key

新規作成時は現在AIの取得可能なmetadataを明示します。exact model IDを取得できない場合は 推測せず unknown、取得元は unavailable または実際の取得経路を指定します。

python -m docsweep new plan auth-refactor \
  --ai-agent codex --ai-runtime codex-cli --ai-provider openai \
  --ai-model-id unknown --ai-model-source unavailable

C単位の実装・レビュー・検証は作業前に開始し、返されたIDを終了時に閉じます。 context配分 表には AI実行 列が追加され、詳細metadataは台帳だけに保持されます。

python -m docsweep provenance start --path docs/local/plan_auth-refactor.md \
  --context C1 --role implementation --agent codex --runtime codex-cli \
  --provider openai --model-id unknown --model-source unavailable --json
python -m docsweep provenance finish --execution <AIX-ID> --result completed --json
python -m docsweep provenance check --path docs/local/plan_auth-refactor.md --json

provenance が有効なのに --ai-* / --agent を渡さなかった場合は、作成AIが unknown で 記録される前にstderrへ1行警告します（作成自体は成功します）。あとから実値へ直すときは provenance init --update を使います。台帳のauthoring行とfrontmatterの ai_author_* を まとめて更新し、execution_id / work_id / started_at は変えません。

python -m docsweep provenance init --update --path docs/local/plan_auth-refactor.md   --agent claude --runtime claude-code --provider anthropic   --model-id claude-opus-5 --model-display "Claude Opus 5" --model-source runtime --json

独自台帳を正典にするリポは .docsweep.yaml で manager: repo と delegate_skill を宣言します。 この場合、汎用コマンドは委譲を返し、個人の汎用台帳へ二重記録しません。

AI エージェント連携

方針: 「全 AI 対応」を最優先し、MCP を使わない AI でも CLI 直叩き（--json）で同じことが できるようにしています。自然言語起動の主役は 朝の入口（brief / cross / capture_extract+capture_save） ですが、MCP サーバーが露出する tool は v0.5.0 時点で 24 個あり、md を書き換える apply / update_status / archive_done や、グローバル設定を書き換える inject_global / eject_global も含みます。 一覧と権限の目安・自然言語マッピング表は docs/ai-agent-integration.md。

推奨運用: MCP 登録せず CLI 一本化

各 AI ツール（Claude Code / Codex / Cursor …）に MCP サーバーを個別登録するより、 CLI 経由（python -m docsweep ...）を AI に直接叩かせる運用が最もシンプルです。

• インストール 1 回で全 AI ツールから使える（MCP 登録は AI ツールごとに別ファイル）
• 戻り値・triage の中身は MCP と同じ — AI から見た体験はほぼ変わらない
• 唯一の手間は AI 側で python -m docsweep を allowlist に追加 すること

Claude Code の場合、~/.claude/settings.json の permissions.allow に 1 行追記:

{
  "permissions": {
    "allow": [
      "Bash(python -m docsweep:*)"
    ]
  }
}

docsweep からは この JSON を自動で書き換えません（権限境界の操作になるため）。 ユーザーが意図的に貼り付ける運用に倒しています。MCP として使いたい場合は 上の「MCP 登録例」を使ってください（こちらも自動登録はしません）。

triage の中身

python -m docsweep triage（または MCP の triage ツール）は、要判断＋保留を古い順に絞った残作業を counts ＋ items[] ＋ needs_fix[] で返します。各 item は rel（相対パス）・title（H1）・ state（ラベル）・type・age_days・summary・actions（discard/keep/resume/relabel/promote の閉じた集合）を持ち、エージェントは「次にどのファイルの何を続けるか」を判断 → python -m docsweep apply で 機械実行します。横断 INDEX 全体の俯瞰は python -m docsweep summary。docsweep 自身は AI API を叩きません（ベンダー非依存）。

セッション開始時に AI へ自動でこの残作業を渡すには python -m docsweep inject --global（Claude は @import、 Codex はインラインで「作業前に triage を読む」導線を個人グローバル設定へ一度だけ注入）。

特定プロジェクトだけ調べたい時（--project）

複数 root を横断管理していると、AI からの自然言語クエリは「全体」より 「<このリポ> だけ」になりがちです。sweep / promote / triage / scan / summary は 共通の --project <name> フラグでプロジェクト名（境界フォルダ名）に絞り込めます。

# 「many-ai-cli の archive 移送対象いくつ?」
python -m docsweep sweep --dry-run --project many-ai-cli

# 「docsweep プロジェクトの様子見昇格候補は?」
python -m docsweep promote --due-expired --dry-run --project docsweep

# 「many-ai-cli の残作業ある?」
python -m docsweep triage --project many-ai-cli

# 「docsweep プロジェクトの全件だけ JSON で吐いて」
python -m docsweep scan --all --project docsweep --json

# 「docsweep プロジェクトの俯瞰を圧縮 JSON で」
python -m docsweep summary --project docsweep

絞り込みは スキャンルートを動かさず後段でフィルタ します。各プロジェクトの .gitignore が docs/local/ を除外していても、グローバル config の roots: から見えていれば対象になります （位置引数 . で当該プロジェクトを単発スキャンすると .gitignore で除外されて 0 件になる 落とし穴を回避するための設計）。

triage / summary の counts も per-project スコープに揃えて返します（フィルタ後の items 数と一致するので、AI/人間どちらが見ても齟齬がありません）。

MCP 経由でも同じく引数で絞れます。例: triage(project="many-ai-cli") / summary(project="docsweep") / sweep(project="many-ai-cli", dry_run=True)。CLI と MCP で引数名・挙動を完全に揃えています。

プロジェクトを一覧・除外する（docsweep project）

roots: の下に 20〜30 個のリポジトリが並ぶと、看板にも scan にも関係ないプロジェクトが 混ざります。docsweep project で一覧の確認と除外の切り替えができます。

# 一覧（ON / OFF と未処理件数）
python -m docsweep project list

# 除外リストへ入れて board / scan から外す
python -m docsweep project disable D:/dev/github/public/foo

# 除外を解除
python -m docsweep project enable D:/dev/github/public/foo

除外は ~/.docsweep/excluded.json に root の絶対パスとして記録され、ファイルは一切動かしません （表示から外れるだけで archive も削除もしません）。Web UI ではプロジェクト行のトグルから、 MCP では list_projects / set_project_enabled から同じ操作ができます。

中身の入った状態で試す（docsweep demo）

自分のプロジェクトへ入れる前に触ってみたいときは、使い捨てのサンプルを作れます。

# 一時ディレクトリにサンプル project を作る（既存のプロジェクトには触りません）
python -m docsweep demo

# 出力された root を指定して見る
python -m docsweep triage --root <生成先>
python -m docsweep serve   --root <生成先>

overdue / 今日 / 未来 / 期日なし / 保留 / 完了 がそろった md が 8 本できるので、 看板も triage も空になりません。グローバル設定の roots には登録しないので、 使い終わったらフォルダごと消せます。--dir で生成先を指定できます。

まとめて動かすときの確認（bulk_confirm_threshold）

一括 archive・一括ラベル変更・promote は 1 手で数十件を動かせます。対象件数が しきい値以上のときだけ確認の段が 1 つ増えます（既定 20 件。しきい値未満は従来どおり）。

# .docsweep.yaml または ~/.docsweep/config.yaml
bulk_confirm_threshold: 20   # 0 にすると常に確認する
metrics: true                # 連続日数・今週の片付け件数の表示（false で記録ごと停止）

Web はフレーズ（ARCHIVE / RELABEL）の打ち込みを求め、CLI の promote は --yes を 要求します。非対話を崩さないため、CLI は端末でもプロンプトを出しません。

詳細は docs/conventions.md と templates/AGENT_GUIDE.md を参照してください。

ライセンス

MIT