Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

はじめに

PRECCとは？

PRECC (Claude Codeの予測的エラー修正) は、公式のPreToolUseフックメカニズムを通じてClaude Codeのbashコマンドを傍受するRustツールです。エラーを発生する前に修正し、トークンを節約してリトライループを排除します。

コミュニティユーザーは無料。

問題

Claude Codeは防げるミスで大量のトークンを浪費します：

  • ディレクトリエラー – Cargo.tomlのない親ディレクトリでcargo buildを実行し、エラーを読んでからリトライ。
  • リトライループ – 失敗したコマンドが冗長な出力を生成し、Claudeがそれを読み、推論し、リトライ。
  • 冗長な出力 – findやls -Rのようなコマンドが数千行を出力。

4つの柱

コンテキスト修正 (cd-prepend)

cargo build や npm test などのコマンドが間違ったディレクトリで実行された場合を検出し、実行前に cd /正しい/パス && を追加します。

GDBデバッグ

セグフォルトやクラッシュの詳細なデバッグのためにGDBをアタッチする機会を検出します。

セッションマイニング

Claude Codeのセッションログを分析して失敗-修正ペアを見つけます。同じミスが再発するとPRECCは自動的に修正を適用します。

自動化スキル

コマンドパターンにマッチして書き換えるスキルのライブラリ。TOMLファイルまたはSQLite行として定義されます。

仕組み（30秒バージョン）

  1. Claude Codeがbashコマンドを実行しようとしています。
  2. PreToolUseフックがコマンドをJSON形式でprecc-hookに送信します。
  3. precc-hookがパイプラインを通じて3ミリ秒未満でコマンドを処理します。
  4. 修正されたコマンドがJSON形式で返されます。
  5. Claude Codeが修正されたコマンドを実行します。

Claudeはエラーを見ることがありません。トークンの無駄はありません。

適応圧縮

コマンドが圧縮後に失敗した場合、PRECCは次のリトライで圧縮を自動的にスキップし、Claudeがデバッグ用の完全な非圧縮出力を取得できるようにします。

リアルタイム使用統計

指標値
フック呼び出し–
節約されたトークン–
節約率–%
RTK書き換え–
CD修正–
フックレイテンシ– ms (p50)

数値は推定値です。各予防された失敗は、エラー出力、モデルの推論、リトライコマンドの完全なリトライサイクルを回避します。 これらの数値は匿名化されたテレメトリから自動的に更新されます。

リンク

インストール

クイックインストール (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash

これはお使いのプラットフォーム用の最新リリースバイナリをダウンロードし、SHA256チェックサムを検証して ~/.local/bin/ に配置します。

インストール後、PRECCを初期化します：

precc init

precc init はPreToolUseフックをClaude Codeに登録し、データディレクトリを作成し、スキルデータベースを初期化します。

インストールオプション

SHA256検証

デフォルトでは、インストーラーは公開されたSHA256サムに対してバイナリチェックサムを検証します。検証をスキップするには（非推奨）：

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash -s -- --no-verify

カスタムインストールプレフィックス

カスタムの場所にインストール：

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash -s -- --prefix /opt/precc

コンパニオンツール (–extras)

PRECCにはオプションのコンパニオンツールが付属しています。--extras でインストールします：

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash -s -- --extras

これにより以下がインストールされます：

ツール用途
RTKコマンド書き換えツールキット
lean-ctxCLAUDE.mdおよびプロンプトファイルのコンテキスト圧縮
nushell高度なパイプライン用の構造化シェル
cocoindex-codeより高速なコンテキスト解決のためのコードインデックス

Windows (PowerShell)

irm https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.ps1 | iex

次に初期化します：

precc init

手動インストール

  1. お使いのプラットフォーム用のリリースバイナリを GitHub Releases からダウンロードします。
  2. リリースの .sha256 ファイルに対してSHA256チェックサムを検証します。
  3. バイナリを PATH 上のディレクトリ（例：~/.local/bin/）に配置します。
  4. precc init を実行します。

アップデート

precc update

特定のバージョンへ強制アップデート：

precc update --force --version 0.3.0

自動アップデートを有効にする：

precc update --auto

インストールの確認

$ precc --version
precc 0.3.0

$ precc savings
Session savings: 0 tokens (no commands intercepted yet)

precc が見つからない場合は、~/.local/bin が PATH に含まれていることを確認してください。

クイックスタート

5分でPRECCを起動しましょう。

ステップ1：インストール

curl -fsSL https://raw.githubusercontent.com/peria-ai/precc-cc/main/scripts/install.sh | bash

ステップ2：初期化

$ precc init
[precc] Hook registered with Claude Code
[precc] Created ~/.local/share/precc/
[precc] Initialized heuristics.db with 8 built-in skills
[precc] Ready.

ステップ3：フックがアクティブか確認

$ precc skills list
  # Name               Type      Triggers
  1 cargo-wrong-dir    built-in  cargo build/test/clippy outside Rust project
  2 git-wrong-dir      built-in  git * outside a repo
  3 go-wrong-dir       built-in  go build/test outside Go module
  4 make-wrong-dir     built-in  make without Makefile in cwd
  5 npm-wrong-dir      built-in  npm/npx/pnpm/yarn outside Node project
  6 python-wrong-dir   built-in  python/pytest/pip outside Python project
  7 jj-translate       built-in  git * in jj-colocated repo
  8 asciinema-gif      built-in  asciinema rec

ステップ4：Claude Codeを通常通り使用

Claude Codeを開いて通常通り作業してください。PRECCはバックグラウンドで静かに動作します。Claudeが失敗するコマンドを発行すると、PRECCが実行前に修正します。

例：間違ったディレクトリでのCargo Build

プロジェクトが ~/projects/myapp/ にあり、Claudeが以下を実行するとします：

cargo build

~/projects/ から（1階層上で、そこに Cargo.toml はありません）。

PRECCなし： Claudeはエラー could not find Cargo.toml in /home/user/projects or any parent directory を受け取り、読んで推論し、cd myapp && cargo build で再試行します。コスト：約2,000トークンの無駄。

PRECCあり： フックが Cargo.toml の欠如を検出し、myapp/ で見つけ、コマンドを以下に書き換えます：

cd /home/user/projects/myapp && cargo build

Claudeはエラーを見ることがありません。トークンの無駄はゼロ。

ステップ5：節約を確認

セッション後、PRECCがどれだけのトークンを節約したか確認してください：

$ precc savings
Session Token Savings
=====================
Total estimated savings: 4,312 tokens

Breakdown:
  Pillar 1 (cd prepends):       2,104 tokens  (3 corrections)
  Pillar 4 (skill activations):   980 tokens  (2 activations)
  RTK rewrites:                 1,228 tokens  (5 rewrites)

次のステップ

  • スキル – 利用可能な全スキルと独自スキルの作成方法。
  • フックパイプライン – フードの下で何が起きているかを理解する。
  • 節約 – トークン節約の詳細分析。

ライセンス

PRECCは2つのティアを提供します：Community（無料）とPro。

Communityティア（無料）

Communityティアには以下が含まれます：

  • すべての組み込みスキル（ディレクトリ修正、jj変換など）
  • Pillar 1とPillar 4を完全サポートするフックパイプライン
  • 基本的な precc savings サマリー
  • precc ingest によるセッションマイニング
  • 無制限のローカル使用

Proティア

Proは追加機能をアンロックします：

  • 詳細な節約内訳 – precc savings --all コマンドごとの分析付き
  • GIF録画 – precc gif アニメーションターミナルGIFの作成用
  • IPジオフェンスコンプライアンス – 規制環境向け
  • メールレポート – precc mail report アナリティクスを送信
  • GitHub Actions分析 – precc gha 失敗したワークフローのデバッグ用
  • コンテキスト圧縮 – precc compress CLAUDE.mdの最適化用
  • 優先サポート

ライセンスの有効化

$ precc license activate XXXX-XXXX-XXXX-XXXX --email you@example.com
[precc] License activated for you@example.com
[precc] Plan: Pro
[precc] Expires: 2027-04-03

ライセンスステータスの確認

$ precc license status
License: Pro
Email:   you@example.com
Expires: 2027-04-03
Status:  Active

GitHub Sponsorsアクティベーション

GitHub SponsorsでPRECCをスポンサーしている場合、GitHubメールを通じて自動的にライセンスが有効化されます。キーは不要です。スポンサーメールが一致していることを確認してください：

$ precc license status
License: Pro (GitHub Sponsors)
Email:   you@example.com
Status:  Active (auto-renewed)

デバイスフィンガープリント

各ライセンスはデバイスフィンガープリントに紐付けられています。以下で確認できます：

$ precc license fingerprint
Fingerprint: a1b2c3d4e5f6...

ライセンスを新しいマシンに移行する必要がある場合は、まず無効化してください：

precc license deactivate

その後、新しいマシンで有効化します。

ライセンスの有効期限切れ？

Proライセンスの有効期限が切れると、PRECCはCommunityティアに戻ります。すべての組み込みスキルとコア機能は引き続き動作します。Pro固有の機能のみ利用できなくなります。詳細はFAQをご覧ください。

フックパイプライン

precc-hook バイナリはPRECCの中核です。Claude Codeとシェルの間に位置し、すべてのbashコマンドを5ミリ秒以内に処理します。

Claude Codeがフックを呼び出す方法

Claude CodeはPreToolUseフックをサポートしています。これは実行前にツール入力を検査・変更できる外部プログラムです。Claudeがbashコマンドを実行しようとすると、stdinで precc-hook にJSONを送信し、stdoutからレスポンスを読み取ります。

パイプラインステージ

Claude Code
    |
    v
+---------------------------+
| 1. Parse JSON stdin       |  Read the command from Claude Code
+---------------------------+
    |
    v
+---------------------------+
| 2. Skill matching         |  Query heuristics.db for matching skills (Pillar 4)
+---------------------------+
    |
    v
+---------------------------+
| 3. Directory correction   |  Resolve correct working directory (Pillar 1)
+---------------------------+
    |
    v
+---------------------------+
| 4. GDB check              |  Detect debug opportunities (Pillar 2)
+---------------------------+
    |
    v
+---------------------------+
| 5. RTK rewriting          |  Apply command rewrites for token savings
+---------------------------+
    |
    v
+---------------------------+
| 6. Emit JSON stdout       |  Return modified command to Claude Code
+---------------------------+
    |
    v
  Shell executes corrected command

例：JSONの入出力

入力（Claude Codeから）

{
  "tool_input": {
    "command": "cargo build"
  }
}

PRECCは現在のディレクトリに Cargo.toml がないが、./myapp/Cargo.toml が存在することを検出します。

出力（Claude Codeへ）

{
  "hookSpecificOutput": {
    "updatedInput": {
      "command": "cd /home/user/projects/myapp && cargo build"
    }
  }
}

変更が不要な場合、updatedInput.command は空となり、Claude Codeは元のコマンドを使用します。

ステージ詳細

ステージ1：JSON解析

stdinから完全なJSONオブジェクトを読み取ります。tool_input.command を抽出します。パースに失敗した場合、フックは即座に終了し、Claude Codeは元のコマンドを使用します（フェイルオープン設計）。

ステージ2：スキルマッチング

SQLiteヒューリスティクスデータベースに、トリガーパターンがコマンドに一致するスキルを問い合わせます。スキルは優先度順にチェックされます。組み込みTOMLスキルとマイニングされたスキルの両方が評価されます。

ステージ3：ディレクトリ修正

ビルドコマンド（cargo、go、make、npm、python など）に対して、期待されるプロジェクトファイルが現在のディレクトリに存在するかチェックします。存在しない場合、近くのディレクトリをスキャンして最も近い一致を見つけ、cd <dir> && を先頭に追加します。

ディレクトリスキャンは5秒のTTLを持つキャッシュされたファイルシステムインデックスを使用して高速を維持します。

ステージ4：GDBチェック

コマンドがクラッシュを引き起こす可能性がある場合（例：デバッグバイナリの実行）、PRECCはGDBラッパーを提案または注入して、生のクラッシュログの代わりに構造化されたデバッグ出力をキャプチャできます。

ステージ5：RTK書き換え

RTK（Rewrite Toolkit）ルールを適用して、冗長なコマンドを短縮し、ノイズの多い出力を抑制し、トークン効率のためにコマンドを再構成します。

ステージ6：JSON出力

変更されたコマンドをJSONにシリアライズしてstdoutに書き込みます。変更がなかった場合、出力はClaude Codeに元のコマンドを使用するよう信号を送ります。

パフォーマンス

パイプライン全体が5ミリ秒（p99）以内に完了します。主な最適化：

  • ロックフリーの並行読み取りのためのSQLite WALモード
  • スキルマッチングのためのプリコンパイル済み正規表現パターン
  • キャッシュされたファイルシステムスキャン（5秒TTL）
  • ホットパスにネットワーク呼び出しなし
  • フェイルオープン：エラーが発生しても元のコマンドにフォールスルー

フックの手動テスト

フックを直接呼び出すことができます：

$ echo '{"tool_input":{"command":"cargo build"}}' | precc-hook
{"hookSpecificOutput":{"updatedInput":{"command":"cd /home/user/myapp && cargo build"}}}

スキル

スキルは、PRECCがコマンドを検出して修正するために使用するパターンマッチングルールです。組み込み（TOMLファイルとして配布）またはセッションログからマイニングされます。

組み込みスキル

スキルトリガー条件アクション
cargo-wrong-dirRustプロジェクト外での cargo build/test/clippy最も近い Cargo.toml ディレクトリへの cd を先頭に追加
git-wrong-dirgitリポジトリ外での git *最も近い .git ディレクトリへの cd を先頭に追加
go-wrong-dirGoモジュール外での go build/test最も近い go.mod ディレクトリへの cd を先頭に追加
make-wrong-dirカレントディレクトリにMakefileがない状態での make最も近いMakefileディレクトリへの cd を先頭に追加
npm-wrong-dirNodeプロジェクト外での npm/npx/pnpm/yarn最も近い package.json ディレクトリへの cd を先頭に追加
python-wrong-dirPythonプロジェクト外での python/pytest/pip最も近いPythonプロジェクトへの cd を先頭に追加
jj-translatejj共存リポジトリでの git *同等の jj コマンドに書き換え
asciinema-gifasciinema recprecc gif に書き換え

スキルの一覧表示

$ precc skills list
  # Name               Type      Triggers
  1 cargo-wrong-dir    built-in  cargo build/test/clippy outside Rust project
  2 git-wrong-dir      built-in  git * outside a repo
  3 go-wrong-dir       built-in  go build/test outside Go module
  4 make-wrong-dir     built-in  make without Makefile in cwd
  5 npm-wrong-dir      built-in  npm/npx/pnpm/yarn outside Node project
  6 python-wrong-dir   built-in  python/pytest/pip outside Python project
  7 jj-translate       built-in  git * in jj-colocated repo
  8 asciinema-gif      built-in  asciinema rec
  9 fix-pytest-path    mined     pytest with wrong test path

スキルの詳細表示

$ precc skills show cargo-wrong-dir
Name:        cargo-wrong-dir
Type:        built-in
Source:      skills/builtin/cargo-wrong-dir.toml
Description: Detects cargo commands run outside a Rust project and prepends
             cd to the directory containing the nearest Cargo.toml.
Trigger:     ^cargo\s+(build|test|clippy|run|check|bench|doc)
Action:      prepend_cd
Marker:      Cargo.toml
Activations: 12

スキルをTOMLにエクスポート

$ precc skills export cargo-wrong-dir
[skill]
name = "cargo-wrong-dir"
description = "Prepend cd for cargo commands outside a Rust project"
trigger = "^cargo\\s+(build|test|clippy|run|check|bench|doc)"
action = "prepend_cd"
marker = "Cargo.toml"
priority = 10

スキルの編集

$ precc skills edit cargo-wrong-dir

これにより、$EDITOR でスキル定義が開きます。保存後、スキルは自動的にリロードされます。

Advise コマンド

precc skills advise は最近のセッションを分析し、繰り返しパターンに基づいて新しいスキルを提案します：

$ precc skills advise
Analyzed 47 commands from the last session.

Suggested skills:
  1. docker-wrong-dir: You ran `docker compose up` outside the project root 3 times.
     Suggested trigger: ^docker\s+compose
     Suggested marker: docker-compose.yml

  2. terraform-wrong-dir: You ran `terraform plan` outside the infra directory 2 times.
     Suggested trigger: ^terraform\s+(plan|apply|init)
     Suggested marker: main.tf

Accept suggestion [1/2/skip]?

スキルのクラスタリング

$ precc skills cluster

類似するマイニングされたスキルをグループ化し、冗長または重複するパターンの特定を支援します。

マイニングスキルと組み込みスキル

組み込みスキルはPRECCに同梱され、skills/builtin/*.toml で定義されています。最も一般的なディレクトリ間違いをカバーします。

マイニングスキルは precc ingest または precc-learner デーモンによってセッションログから作成されます。~/.local/share/precc/heuristics.db に保存され、ワークフローに固有です。詳細はマイニングを参照してください。

節約

PRECCは各インターセプションから推定されるトークン節約を追跡します。precc savings を使用して、PRECCがどれだけの無駄を防いだかを確認してください。

クイックサマリー

$ precc savings
Session Token Savings
=====================
Total estimated savings: <span data-stat="session_tokens_saved">8,741</span> tokens

Breakdown:
  Pillar 1 (cd prepends):         <span data-stat="session_p1_tokens">3,204</span> tokens  (<span data-stat="session_p1_count">6</span> corrections)
  Pillar 4 (skill activations):   <span data-stat="session_p4_tokens">1,560</span> tokens  (<span data-stat="session_p4_count">4</span> activations)
  RTK rewrites:                   <span data-stat="session_rtk_tokens">2,749</span> tokens  (<span data-stat="session_rtk_count">11</span> rewrites)
  Lean-ctx wraps:                 <span data-stat="session_lean_tokens">1,228</span> tokens  (<span data-stat="session_lean_count">2</span> wraps)

詳細内訳（Pro）

$ precc savings --all
Session Token Savings (Detailed)
================================
Total estimated savings: <span data-stat="session_tokens_saved">8,741</span> tokens

Command-by-command:
  #  Time   Command                          Saving   Source
  1  09:12  cargo build                      534 tk   cd prepend (cargo-wrong-dir)
  2  09:14  cargo test                       534 tk   cd prepend (cargo-wrong-dir)
  3  09:15  git status                       412 tk   cd prepend (git-wrong-dir)
  4  09:18  npm install                      824 tk   cd prepend (npm-wrong-dir)
  5  09:22  find . -name "*.rs"              387 tk   RTK rewrite (output truncation)
  6  09:25  cat src/main.rs                  249 tk   RTK rewrite (lean-ctx wrap)
  7  09:31  cargo clippy                     534 tk   cd prepend (cargo-wrong-dir)
  ...

Pillar Breakdown:
  Pillar 1 (context resolution):   <span data-stat="session_p1_tokens">3,204</span> tokens  <span data-stat="session_p1_pct">36.6</span>%
  Pillar 2 (GDB debugging):            0 tokens   0.0%
  Pillar 3 (mined preventions):        0 tokens   0.0%
  Pillar 4 (automation skills):    <span data-stat="session_p4_tokens">1,560</span> tokens  <span data-stat="session_p4_pct">17.8</span>%
  RTK rewrites:                    <span data-stat="session_rtk_tokens">2,749</span> tokens  <span data-stat="session_rtk_pct">31.5</span>%
  Lean-ctx wraps:                  <span data-stat="session_lean_tokens">1,228</span> tokens  <span data-stat="session_lean_pct">14.1</span>%

節約の推定方法

各修正タイプには、PRECCなしで何が起こったかに基づく推定トークンコストがあります：

修正タイプ推定節約理由
cd prepend~500 tokensエラー出力 + Claudeの推論 + リトライ
スキルアクティベーション~400 tokensエラー出力 + Claudeの推論 + リトライ
RTK rewrite~250 tokensClaudeが読まなければならない冗長な出力
Lean-ctx wrap~600 tokens大きなファイル内容が圧縮される
マイニングされた予防~500 tokens既知の失敗パターンを回避

これらは控えめな見積もりです。Claudeのエラーに関する推論は冗長になることがあるため、実際の節約はより高いことが多いです。

累積節約

節約はPRECCデータベースにセッション間で保持されます。時間の経過とともに、総合的な影響を追跡できます：

$ precc savings
Session Token Savings
=====================
Total estimated savings: <span data-stat="session_tokens_saved">8,741</span> tokens

Lifetime savings: <span data-stat="total_tokens_saved">142,389</span> tokens across <span data-stat="total_sessions">47</span> sessions

圧縮

precc compress は CLAUDE.md やその他のコンテキストファイルを圧縮し、Claude Code がそれらを読み込む際のトークン使用量を削減します。これは Pro 機能です。

基本的な使い方

$ precc compress .
[precc] Scanning directory: .
[precc] Found 3 context files:
         CLAUDE.md (2,847 tokens -> 1,203 tokens, -57.7%)
         ARCHITECTURE.md (4,112 tokens -> 2,044 tokens, -50.3%)
         ALTERNATIVES.md (3,891 tokens -> 1,967 tokens, -49.5%)
[precc] Total: 10,850 tokens -> 5,214 tokens (-51.9%)
[precc] Files compressed. Use --revert to restore originals.

ドライラン

ファイルを変更せずに変更内容をプレビュー：

$ precc compress . --dry-run
[precc] Dry run -- no files will be modified.
[precc] CLAUDE.md: 2,847 tokens -> 1,203 tokens (-57.7%)
[precc] ARCHITECTURE.md: 4,112 tokens -> 2,044 tokens (-50.3%)
[precc] ALTERNATIVES.md: 3,891 tokens -> 1,967 tokens (-49.5%)
[precc] Total: 10,850 tokens -> 5,214 tokens (-51.9%)

元に戻す

元のファイルは自動的にバックアップされます。復元するには：

$ precc compress --revert
[precc] Restored 3 files from backups.

何が圧縮されるか

コンプレッサーはいくつかの変換を適用します：

  • 冗長な空白と空行を削除
  • 意味を保ちながら冗長な表現を短縮
  • テーブルとリストを圧縮
  • コメントと装飾的なフォーマットを除去
  • すべてのコードブロック、パス、技術的識別子を保持

圧縮された出力はまだ人間が読める形式です——ミニファイや難読化はされていません。

特定のファイルを対象にする

$ precc compress CLAUDE.md
[precc] CLAUDE.md: 2,847 tokens -> 1,203 tokens (-57.7%)

レポート

precc report は PRECC の活動とトークン節約をまとめた分析ダッシュボードを生成します。

レポートの生成

$ precc report
PRECC Report -- 2026-04-03
==========================

Sessions analyzed: 12
Commands intercepted: 87
Total token savings: 42,389

Top skills by activation:
  1. cargo-wrong-dir     34 activations   17,204 tokens saved
  2. npm-wrong-dir       18 activations    9,360 tokens saved
  3. git-wrong-dir       12 activations    4,944 tokens saved
  4. RTK rewrite         15 activations    3,750 tokens saved
  5. python-wrong-dir     8 activations    4,131 tokens saved

Savings by pillar:
  Pillar 1 (context resolution):  28,639 tokens  67.6%
  Pillar 4 (automation skills):    7,000 tokens  16.5%
  RTK rewrites:                    3,750 tokens   8.8%
  Lean-ctx wraps:                  3,000 tokens   7.1%

Recent corrections:
  2026-04-03 09:12  cargo build -> cd myapp && cargo build
  2026-04-03 09:18  npm test -> cd frontend && npm test
  2026-04-03 10:05  git status -> cd repo && git status
  ...

レポートのメール送信

レポートをメールアドレスに送信（メール設定が必要、Email 参照）：

$ precc report --email
[precc] Report sent to you@example.com

受信者アドレスは ~/.config/precc/mail.toml から読み取られます。precc mail report EMAIL を使って特定のアドレスに送信することもできます。

レポートデータ

レポートは ~/.local/share/precc/history.db のローカル PRECC データベースから生成されます。レポートを明示的にメール送信しない限り、データはマシンから出ません。

マイニング

PRECCはClaude Codeのセッションログを解析して失敗-修正パターンを学習します。同じミスを再び見つけると、自動的に修正を適用します。

セッションログの取り込み

単一ファイルの取り込み

$ precc ingest ~/.claude/logs/session-2026-04-03.jsonl
[precc] Parsing session-2026-04-03.jsonl...
[precc] Found 142 commands, 8 failure-fix pairs
[precc] Stored 8 patterns in history.db
[precc] 2 new skill candidates identified

すべてのログの取り込み

$ precc ingest --all
[precc] Scanning ~/.claude/logs/...
[precc] Found 23 session files (14 new, 9 already ingested)
[precc] Parsing 14 new files...
[precc] Found 47 failure-fix pairs across 14 sessions
[precc] Stored 47 patterns in history.db
[precc] 5 new skill candidates identified

強制再取り込み

すでに取り込まれたファイルを再処理するには：

$ precc ingest --all --force
[precc] Re-ingesting all 23 session files...

マイニングの仕組み

  1. PRECCはセッションJSONLログファイルを読み取ります。
  2. 最初のコマンドが失敗し、2番目が修正されたリトライであるコマンドペアを特定します。
  3. パターン（何が問題だったか）と修正（Claudeが何を変えたか）を抽出します。
  4. パターンは ~/.local/share/precc/history.db に保存されます。
  5. パターンが信頼度の閾値に達すると（複数回確認）、heuristics.db のマイニングスキルになります。

パターンの例

Failure: pytest tests/test_auth.py
Error:   ModuleNotFoundError: No module named 'myapp'
Fix:     cd /home/user/myapp && pytest tests/test_auth.py
Pattern: pytest outside project root -> prepend cd

precc-learner デーモン

precc-learner デーモンはバックグラウンドで実行され、新しいセッションログを自動的に監視します：

$ precc-learner &
[precc-learner] Watching ~/.claude/logs/ for new sessions...
[precc-learner] Processing session-2026-04-03-1412.jsonl... 3 new patterns

デーモンはファイルシステム通知（LinuxではinotifyOSではFSEvents）を使用するため、セッション終了時に即座に反応します。

パターンからスキルへ

マイニングされたパターンは以下の条件を満たすとスキルに昇格します：

  • セッション全体で少なくとも3回確認
  • 一貫した修正パターン（毎回同じタイプの修正）
  • 誤検出なし

スキル候補は以下で確認できます：

$ precc skills advise

スキルの管理の詳細については Skills を参照してください。

データストレージ

  • 失敗-修正ペア: ~/.local/share/precc/history.db
  • 昇格したスキル: ~/.local/share/precc/heuristics.db

どちらもWALモードのSQLiteデータベースで、安全な並行アクセスが可能です。

メール

PRECCはメールでレポートやファイルを送信できます。これには一度だけのSMTP設定が必要です。

セットアップ

$ precc mail setup
SMTP host: smtp.gmail.com
SMTP port [587]: 587
Username: you@gmail.com
Password: ********
From address [you@gmail.com]: you@gmail.com
[precc] Mail configuration saved to ~/.config/precc/mail.toml
[precc] Sending test email to you@gmail.com...
[precc] Test email sent successfully.

設定ファイル

設定は ~/.config/precc/mail.toml に保存されます：

[smtp]
host = "smtp.gmail.com"
port = 587
username = "you@gmail.com"
password = "app-password-here"
from = "you@gmail.com"
tls = true

このファイルを直接編集できます：

$EDITOR ~/.config/precc/mail.toml

Gmailの場合は、アカウントパスワードではなくアプリパスワードを使用してください。

レポートの送信

$ precc mail report team@example.com
[precc] Generating report...
[precc] Sending to team@example.com...
[precc] Report sent.

ファイルの送信

$ precc mail send colleague@example.com output.log
[precc] Sending output.log to colleague@example.com...
[precc] Sent (14.2 KB).

SSHリレーサポート

マシンがSMTPサーバーに直接到達できない場合（例：企業ファイアウォールの背後）、PRECCはSSHトンネル経由のリレーをサポートします：

[smtp]
host = "localhost"
port = 2525

[ssh_relay]
host = "relay.example.com"
user = "you"
remote_port = 587
local_port = 2525

PRECCは送信前にSSHトンネルを自動的に確立します。

GIF録画

precc gifはbashスクリプトからターミナルセッションのアニメーションGIF録画を作成します。これはPro機能です。

基本的な使い方

$ precc gif script.sh 30s
[precc] Recording script.sh (max 30s)...
[precc] Running: echo "Hello, world!"
[precc] Running: cargo build --release
[precc] Running: cargo test
[precc] Recording complete.
[precc] Output: script.gif (1.2 MB, 24s)

最初の引数は実行するコマンドを含むbashスクリプトです。2番目の引数は最大録画時間です。

スクリプト形式

スクリプトは標準的なbashファイルです：

#!/bin/bash
echo "Building project..."
cargo build --release
echo "Running tests..."
cargo test
echo "Done!"

入力シミュレーション

インタラクティブコマンドの場合、追加引数として入力値を指定します：

$ precc gif interactive-demo.sh 60s "yes" "my-project" "3"

追加の各引数は、スクリプトが入力を要求するときにstdinの行として渡されます。

出力オプション

出力ファイルはデフォルトでスクリプト名に基づいて命名されます（script.gif）。GIFはダークターミナルテーマで標準80x24サイズを使用します。

なぜasciinemaではなくGIFなのか？

組み込みスキル asciinema-gif は asciinema rec を自動的に precc gif に書き換えます。GIFファイルはより移植性が高く、GitHub README、Slack、メールでプレーヤーなしでインライン表示されます。

GitHub Actionsの分析

precc ghaは失敗したGitHub Actionsの実行を分析し、修正を提案します。これはPro機能です。

使い方

失敗したGitHub Actionsの実行URLを渡します：

$ precc gha https://github.com/myorg/myrepo/actions/runs/12345678
[precc] Fetching run 12345678...
[precc] Run: CI / build (ubuntu-latest)
[precc] Status: failure
[precc] Failed step: Run cargo test

[precc] Log analysis:
  Error: test result: FAILED. 2 passed; 1 failed
  Failed test: tests::integration::test_database_connection
  Cause: thread 'tests::integration::test_database_connection' panicked at
         'called Result::unwrap() on an Err value: Connection refused'

[precc] Suggested fix:
  The test requires a database connection but the CI environment does not
  start a database service. Add a services block to your workflow:

    services:
      postgres:
        image: postgres:15
        ports:
          - 5432:5432
        env:
          POSTGRES_PASSWORD: test

機能

  1. GitHub ActionsのランURLを解析して、オーナー、リポジトリ、ランIDを抽出します。
  2. GitHub API経由でランログを取得します（GITHUB_TOKENが設定されている場合はそれを使用、そうでなければパブリックアクセス）。
  3. 失敗したステップを特定し、関連するエラー行を抽出します。
  4. エラーを分析し、一般的なCI失敗パターンに基づいて修正を提案します。

サポートされる障害パターン

  • 不足しているサービスコンテナ（データベース、Redisなど）
  • ランナーのOSまたはアーキテクチャの不一致
  • 環境変数またはシークレットの不足
  • 依存関係のインストール失敗
  • テストタイムアウト
  • 権限エラー
  • キャッシュミスによるビルドの遅延

ジオフェンス

PRECCは規制環境向けのIPジオフェンスコンプライアンスチェックを含みます。これはPro機能です。

概要

一部の組織は、開発ツールが承認された地理的リージョン内でのみ動作することを要求しています。PRECCのジオフェンス機能は、現在のマシンのIPアドレスが許可されたリージョンリスト内にあることを検証します。

コンプライアンスチェック

$ precc geofence check
[precc] Current IP: 203.0.113.42
[precc] Region: US-East (Virginia)
[precc] Status: COMPLIANT
[precc] Policy: us-east-1, us-west-2, eu-west-1

マシンが許可されたリージョンの外にある場合：

$ precc geofence check
[precc] Current IP: 198.51.100.7
[precc] Region: AP-Southeast (Singapore)
[precc] Status: NON-COMPLIANT
[precc] Policy: us-east-1, us-west-2, eu-west-1
[precc] Warning: Current region is not in the allowed list.

ジオフェンスデータの更新

$ precc geofence refresh
[precc] Fetching updated IP geolocation data...
[precc] Updated. Cache expires in 24h.

ジオフェンス情報の表示

$ precc geofence info
Geofence Configuration
======================
Policy file:    ~/.config/precc/geofence.toml
Allowed regions: us-east-1, us-west-2, eu-west-1
Cache age:      2h 14m
Last check:     2026-04-03 09:12:00 UTC
Status:         COMPLIANT

キャッシュのクリア

$ precc geofence clear
[precc] Geofence cache cleared.

設定

ジオフェンスポリシーは ~/.config/precc/geofence.toml で定義されます：

[geofence]
allowed_regions = ["us-east-1", "us-west-2", "eu-west-1"]
check_on_init = true
block_on_violation = false

block_on_violation = true を設定すると、許可されたリージョン外でPRECCの動作を防止します。

テレメトリ

PRECCはツールの改善に役立つオプトイン方式の匿名テレメトリをサポートしています。明示的に同意しない限り、データは収集されません。

オプトイン

$ precc telemetry consent
[precc] Telemetry enabled. Thank you for helping improve PRECC.
[precc] You can revoke consent at any time with: precc telemetry revoke

オプトアウト

$ precc telemetry revoke
[precc] Telemetry disabled. No further data will be sent.

ステータス確認

$ precc telemetry status
Telemetry: disabled
Last sent: never

送信されるデータのプレビュー

オプトインする前に、収集されるデータを正確に確認できます：

$ precc telemetry preview
Telemetry payload (this session):
{
  "version": "0.3.0",
  "os": "linux",
  "arch": "x86_64",
  "skills_activated": 12,
  "commands_intercepted": 87,
  "pillars_used": [1, 4],
  "avg_hook_latency_ms": 2.3,
  "session_count": 1
}

収集されるもの

  • PRECCバージョン、OS、アーキテクチャ
  • 集計カウント：インターセプトされたコマンド、アクティブ化されたスキル、使用された柱
  • 平均フックレイテンシ
  • セッション数

収集されないもの

  • コマンドテキストや引数なし
  • ファイルパスやディレクトリ名なし
  • プロジェクト名やリポジトリURLなし
  • 個人を特定できる情報（PII）なし
  • IPアドレスなし（サーバーは記録しません）

環境変数によるオーバーライド

コマンドを実行せずにテレメトリを無効にするには（CIや共有環境で便利）：

export PRECC_NO_TELEMETRY=1

これは同意設定よりも優先されます。

データの送信先

テレメトリデータはHTTPSで https://telemetry.peria.ai/v1/precc に送信されます。データは使用パターンの理解と開発の優先順位付けにのみ使用されます。

コマンドリファレンス

全PRECCコマンドの完全リファレンス。

precc init

PRECCを初期化し、Claude Codeにフックを登録します。

precc init

Options:
  (none)

Effects:
  - Registers PreToolUse:Bash hook with Claude Code
  - Creates ~/.local/share/precc/ data directory
  - Initializes heuristics.db with built-in skills
  - Prompts for telemetry consent

precc ingest

セッションログから失敗-修正パターンをマイニングします。

precc ingest [FILE] [--all] [--force]

Arguments:
  FILE            Path to a session log file (.jsonl)

Options:
  --all           Ingest all session logs from ~/.claude/logs/
  --force         Re-process files that were already ingested

Examples:
  precc ingest session.jsonl
  precc ingest --all
  precc ingest --all --force

precc skills

自動化スキルを管理します。

precc skills list

precc skills list

List all active skills (built-in and mined).

precc skills show

precc skills show NAME

Show detailed information about a specific skill.

Arguments:
  NAME            Skill name (e.g., cargo-wrong-dir)

precc skills export

precc skills export NAME

Export a skill definition as TOML.

Arguments:
  NAME            Skill name

precc skills edit

precc skills edit NAME

Open a skill definition in $EDITOR.

Arguments:
  NAME            Skill name

precc skills advise

precc skills advise

Analyze recent sessions and suggest new skills based on repeated patterns.

precc skills cluster

precc skills cluster

Group similar mined skills to identify redundant or overlapping patterns.

precc report

分析レポートを生成します。

precc report [--email]

Options:
  --email         Send the report via email (requires mail setup)

precc savings

トークン節約を表示します。

precc savings [--all]

Options:
  --all           Show detailed per-command breakdown (Pro)

precc compress

コンテキストファイルを圧縮してトークン使用量を削減します。

precc compress [DIR] [--dry-run] [--revert]

Arguments:
  DIR             Directory or file to compress (default: current directory)

Options:
  --dry-run       Preview changes without modifying files
  --revert        Restore files from backup

precc license

PRECCライセンスを管理します。

precc license activate

precc license activate KEY --email EMAIL

Arguments:
  KEY             License key (XXXX-XXXX-XXXX-XXXX)

Options:
  --email EMAIL   Email address associated with the license

precc license status

precc license status

Display current license status, plan, and expiration.

precc license deactivate

precc license deactivate

Deactivate the license on this machine.

precc license fingerprint

precc license fingerprint

Display the device fingerprint for this machine.

precc mail

メール機能。

precc mail setup

precc mail setup

Interactive SMTP configuration. Saves to ~/.config/precc/mail.toml.

precc mail report

precc mail report EMAIL

Send a PRECC analytics report to the specified email address.

Arguments:
  EMAIL           Recipient email address

precc mail send

precc mail send EMAIL FILE

Send a file as an email attachment.

Arguments:
  EMAIL           Recipient email address
  FILE            Path to the file to send

precc update

PRECCを最新バージョンに更新します。

precc update [--force] [--version VERSION] [--auto]

Options:
  --force             Force update even if already on latest
  --version VERSION   Update to a specific version
  --auto              Enable automatic updates

precc telemetry

匿名テレメトリを管理します。

precc telemetry consent

Opt in to anonymous telemetry.

precc telemetry revoke

precc telemetry revoke

Opt out of telemetry. No further data will be sent.

precc telemetry status

precc telemetry status

Show current telemetry consent status.

precc telemetry preview

precc telemetry preview

Display the telemetry payload that would be sent (without sending it).

precc geofence

IPジオフェンスコンプライアンス（Pro）。

precc geofence check

precc geofence check

Check if the current machine is in an allowed region.

precc geofence refresh

precc geofence refresh

Refresh the IP geolocation cache.

precc geofence clear

precc geofence clear

Clear the geofence cache.

precc geofence info

precc geofence info

Display geofence configuration and current status.

precc gif

bashスクリプトからアニメーションGIFを録画（Pro）。

precc gif SCRIPT LENGTH [INPUTS...]

Arguments:
  SCRIPT          Path to a bash script
  LENGTH          Maximum recording duration (e.g., 30s, 2m)
  INPUTS...       Optional input lines for interactive prompts

Examples:
  precc gif demo.sh 30s
  precc gif interactive.sh 60s "yes" "my-project"

precc gha

失敗したGitHub Actionsの実行を分析（Pro）。

precc gha URL

Arguments:
  URL             GitHub Actions run URL

Example:
  precc gha https://github.com/org/repo/actions/runs/12345678

precc cache-hint

現在のプロジェクトのキャッシュヒント情報を表示します。

precc cache-hint

precc trial

Proトライアルを開始します。

precc trial EMAIL

Arguments:
  EMAIL           Email address for the trial

precc nushell

PRECC統合のNushellセッションを起動します。

precc nushell

よくある質問

PRECCは安全ですか？

はい。PRECCはClaude Code公式のPreToolUseフックメカニズムを使用しています。Anthropicがまさにこの目的のために設計した拡張ポイントです。フックは：

  • 完全にオフラインで動作（ホットパスでのネットワーク呼び出しなし）
  • 5ミリ秒未満で完了
  • フェイルオープン：問題が発生した場合、元のコマンドがそのまま実行される
  • コマンドを変更するだけで、自ら実行することはない
  • データはローカルのSQLiteデータベースに保存

PRECCは他のAIコーディングツールで動作しますか？

PRECCはClaude Code専用に設計されています。Claude Codeが提供するPreToolUseフックプロトコルに依存しています。Cursor、Copilot、Windsurf、その他のAIコーディングツールでは動作しません。

テレメトリはどのようなデータを送信しますか？

テレメトリはオプトインのみです。有効にすると送信されるもの：

  • PRECCバージョン、OS、アーキテクチャ
  • 集計カウント（インターセプトされたコマンド、アクティブ化されたスキル）
  • 平均フックレイテンシ

コマンドテキスト、ファイルパス、プロジェクト名、個人を特定できる情報は送信しません。オプトイン前に precc telemetry preview で正確なペイロードを確認できます。詳細はテレメトリを参照。

PRECCをアンインストールするには？

??faq_uninstall_a_intro??

  1. フック登録を削除：

    # Delete the hook entry from Claude Code's settings
# (precc init added it; removing it disables PRECC)

  2. バイナリを削除：

    rm ~/.local/bin/precc ~/.local/bin/precc-hook ~/.local/bin/precc-learner

  3. データを削除（任意）：

    rm -rf ~/.local/share/precc/
rm -rf ~/.config/precc/

ライセンスが期限切れになりました。どうなりますか？

PRECCはCommunityティアに戻ります。すべてのコア機能は引き続き動作します：

  • 組み込みスキルはアクティブのまま
  • フックパイプラインは正常に動作
  • precc savings はサマリービューを表示
  • precc ingest とセッションマイニングは動作

Pro機能は更新まで利用できなくなります：

  • precc savings --all（詳細な内訳）
  • precc compress
  • precc gif
  • precc gha
  • precc geofence
  • メールレポート

フックが動作していないようです。どうやってデバッグしますか？

??faq_debug_a_intro??

  1. フックが登録されていることを確認：

    precc init

  2. フックを手動でテスト：

    echo '{"tool_input":{"command":"cargo build"}}' | precc-hook

  3. バイナリがPATHにあることを確認：

    which precc-hook

  4. ~/.claude/settings.json のClaude Codeフック設定を確認。

PRECCはClaude Codeを遅くしますか？

いいえ。フックは5ミリ秒未満（p99）で完了します。Claudeが推論と応答生成に費やす時間と比べると知覚できません。

CI/CDでPRECCを使用できますか？

PRECCはインタラクティブなClaude Codeセッション向けに設計されています。CI/CDでは、フックするClaude Codeインスタンスがありません。ただし、precc gha はどの環境からでも失敗したGitHub Actionsの実行を分析できます。

マイニングされたスキルと組み込みスキルはどう違いますか？

組み込みスキルはPRECCに同梱され、一般的な間違ったディレクトリパターンをカバーします。マイニングされたスキルはあなたの特定のセッションログから学習されます。両方ともSQLiteに保存され、フックパイプラインで同一に評価されます。

スキルをチームと共有できますか？

はい。precc skills export NAME でスキルをTOMLにエクスポートしてファイルを共有できます。チームメンバーは skills/ ディレクトリに配置するか、ヒューリスティクスデータベースにインポートできます。

他の言語