Tiltmeter

Tiltmeter

AI エージェントが依存するサードパーティ API の早期警告システムです。修正内容はプルリクエストとして提示されます。 · tiltmeter.dev

火山学者は噴火よりずっと前にわずかな変形を検知するため、傾斜計を地面に取り付けます。Tiltmeter は、エージェントが利用する API に対して同じことを行います。実際のトラフィックから JSON レスポンスの形状を学習し、ベンダーがフィールド名を変更したり、null を送り始めたり、数値を文字列に変えたりしたことを検知して、何かが傾く前に、あなたや CI、エージェント自身に知らせます。その後、tiltmeter fix が変更をエージェントに渡し、その API を読み取るコードを適応させてプルリクエストを作成します。判断できないことは人間に委ねます。

型付きコードは API の変更時に明確にクラッシュしますが、エージェントはそうではありません。新しいレスポンスを読み、推測で不足を補ったり、予算が尽きるまでリトライしたりします。

主な機能

• エージェントは動作前に確認できます。 MCP サーバーを使うと、Claude Code、Cursor、LangChain、または任意の MCP クライアントが、API を信頼する前に has_drifted を呼び出し、get_schema で想定されるフィールドを確認できます。
• 仕様書は不要です。 Tiltmeter は実際のレスポンスから学習するため、ドキュメントの有無を問わず、あらゆる JSON API で動作します。
• 破壊的変更か無害な変更か、一目でわかります。 変更はすべて破壊的変更、警告、または情報に分類されます。また、削除されたフィールドの近くに似た新しいフィールドがある場合は、名称変更の可能性が高いと判定されます。
• 必要に応じて解説します。 Anthropic API キーを設定すると、Claude が変更内容、考えられる原因、対処方法を説明します。
• 修正にも対応します。 tiltmeter fix が変更をエージェントに渡し、その API を読み取るコードを適応させて、差分を表示し、プルリクエストを作成します。組み込みの LangChain Deep Agent、または独自の Claude Code や Codex のログインを使用できます。
• アラート機能付きの CI ゲートです。 破壊的変更があると、終了コードによってビルドが失敗します。Slack と Webhook のアラートは、設定を 1 行追加するだけで利用できます。
• ローカルでプライベートに使えます。 SQLite ファイル 1 つで動作し、アカウントは不要です。認証情報はリクエスト時に展開され、保存されることはありません。レスポンス本文は保存も LLM への送信もされず、保存・送信されるのはその形状のみです。

クイックスタート

pip install tiltmeter        # or: uv tool install tiltmeter
tiltmeter init               # writes tiltmeter.yaml with a public example API
tiltmeter check              # the first check records the baseline

Web アプリからすでに API を呼び出していますか？ ブラウザーの DevTools（Network タブ、「Export HAR」）から HAR をエクスポートすると、ページが呼び出した JSON リクエストから Tiltmeter が設定ファイルを作成します。トークンと Cookie は ${VAR} のプレースホルダーになります。

tiltmeter init --from-har session.har --host api.example.com

cron または CI から tiltmeter check を再度実行するか、tiltmeter watch を実行したままにしてください。ベンダーが phone の名称を変更し、balance を文字列に変えた場合、次のように表示されます。

$ tiltmeter check
✗ billing_customers  200 · 13 ms  BREAKING · 3 changes
    breaking  type_changed   $.data[*].balance       integer → string
    breaking  field_removed  $.data[*].phone         string → (absent)  possibly renamed to $.data[*].phone_number
    info      field_added    $.data[*].phone_number  (absent) → string  possibly replaces $.data[*].phone
1 endpoint checked · 1 breaking
$ echo $?
2

スタートガイドでは、お使いのマシン上のフェイク API を使って、まったく同じシナリオを約 5 分で実行します。

エージェントにチルトメーターを持たせる

claude mcp add tiltmeter -- tiltmeter serve --config /absolute/path/to/tiltmeter.yaml

次に、エージェントの指示に次のような行を追加します。

サードパーティ API に依存する前に、その API に対して has_drifted を呼び出してください。ドリフトがある場合は、概要を読み、応答を信頼する前に対応してください。

ツール	確認できること
has_drifted(endpoint_id, since?)	最近、警告レベル以上の変更が応答にありましたか？概要と変更内容を返します。
get_schema(endpoint_id)	JSON Schema で、想定されるフィールド、型、列挙値を確認できます。
get_changes(endpoint_id?, since?, min_severity?, limit?)	変更履歴を新しい順に確認できます。
list_endpoints()	監視対象の API と、それぞれの直近のチェック結果を確認できます。
check_api(endpoint_id, explain?)	1 つの API を今すぐ呼び出し、結果を記録します。
check_all(explain?)	すべての API を今すぐ呼び出します。

Cursor、Claude Desktop、LangChain エージェント向けのセットアップについては、 エージェントガイドをご覧ください。

コードを修正する

チェックでドリフトが見つかると、tiltmeter fix がエージェントに処理を渡します。エージェントはその API を読み取るコードを見つけて修正し、差分を表示してプルリクエストを作成します。

$ pip install "tiltmeter[fix]"            # or plain tiltmeter, then --agent claude-code or codex
$ tiltmeter fix 2 --repo ~/code/billing-service
✗ billing_customer  #2  200 · 10 ms  BREAKING · 3 changes
Working on a new branch, tiltmeter/fix-billing-customer-2, from main at 162dadd.
3 files changed  +5 -5
diff --git a/billing/client.py b/billing/client.py
-    return f"{customer['name']} <{customer['phone']}>"
+    return f"{customer['name']} <{customer['phone_number']}>"
...
Commit, push and open a pull request? [y/N]: y
✓ opened https://github.com/acme/billing-service/pull/41

• チェックアウトには一切触れません。 エージェントは新しいブランチ上の一時的な Git ワークツリーで作業します。差分を承認するか --yes を渡すまで、何もコミットされません。
• ワークツリー内でのみ作業します。 ネットワークアクセスはなく、読み取り可能なのは追跡対象のファイルのみです。.env ファイル、キー、.git へのアクセスは禁止されています。組み込みエージェントと Claude Code が利用できるのはファイルツールのみです。Codex はシェルを使用しますが、同じ制限のもと、OS のサンドボックス内に隔離されます。
• できなかったことを明示します。 Tiltmeter が把握するのは型であり、値ではありません。数値が文字列に変わった場合、エージェントは型を更新し、変換方法を推測するのではなく、プルリクエストで人間に形式を確認します。
• お使いのエージェントを利用できます。 すでに Claude Code または Codex をお使いですか？ tiltmeter fix 2 --agent claude-code または --agent codex を実行すると、API キーや追加インストールなしで、ご自身のログインを使って動作します。

--dry-run は差分を表示して破棄し、--no-pr はローカルブランチにコミットします。修正ガイドでは、各種フラグ、モデルに表示される内容、結果のレビュー方法について説明しています。

ドリフトの判定基準

変更	例	デフォルトの重大度
field_removed	すべての応答にあった phone がなくなった	破壊的
field_now_optional	常に存在していた email が、一部のオブジェクトで欠落するようになった	破壊的
type_changed	balance が整数から文字列に変わった	破壊的
nullable_introduced	phone が null になり得るようになった	破壊的
content_type_changed	JSON 本文が HTML のエラーページになった	破壊的
status_changed	200 から 503 への変更は破壊的、404 から 200 への変更は情報、200 から 202 への変更は警告	状況による
enum_value_added	status が active と past_due に加えて suspended を返した	警告
latency_regression	中央値のレイテンシがベースラインの 3 倍を超え、かつ 250 ms 以上遅くなった	警告
field_added	新しい phone_number フィールド	情報。strict: true の場合は警告

severity_overrides を使うと、これらの設定を全体またはエンドポイントごとに上書きできます。

CI で使用する

終了コード	意味
0	ドリフトなし。情報のみの変更と新しいベースラインは、ドリフトなしとして扱われます。
1	警告レベルのドリフト。
2	破壊的なドリフト。
3	チェックを実行できませんでした（ネットワークエラー、予期しないステータス、無効な JSON）。破損は発生していません。
4	使用方法または設定のエラー。

GitHub では、Tiltmeter Action が Actions キャッシュにベースラインを保持し、変更内容をジョブの概要に記録して、ドリフトがある場合はジョブを失敗させます。

- uses: tiltmeter-dev/tiltmeter-action@v1
  env:
    STRIPE_API_KEY: ${{ secrets.STRIPE_API_KEY }}

それ以外の環境では、実行のたびに .tiltmeter/ を保持してください。CI ガイドには、すぐにコピーして使える GitHub Actions、GitLab CI、cron 用のジョブが掲載されています。

仕組み

1. 観測。 チェックがエンドポイントを呼び出し、JSON の本文を 形状 に変換します。各パスについて、どの JSON 型が現れたか、各フィールドを含むオブジェクトの数、そしてカテゴリ型に見えるフィールド（active、past_due、USD）について、どの値が確認されたかを記録します。
2. 比較。 ベースラインは、直近 20 回の成功したチェックで得られた形状をマージしたものです。Tiltmeter は、ベースラインと 矛盾する ものだけを報告します。欠落している任意フィールドは問題ありませんが、すべてのオブジェクトに存在していたフィールドがなくなった場合は報告します。
3. 一度だけ報告。 新しい形状がベースラインに加わるため、変更を検知したチェックで報告され、その後はそれが新しい通常の状態になります。

graph TD;
  start([start]) --> observe
  observe -. fetch failed .-> persist
  observe --> load_baseline --> compare
  compare -. drift worth explaining .-> explain --> persist
  compare --> persist
  persist -. a notifier wants it .-> notify --> finish([end])
  persist --> finish

パイプラインは、各ステップを順に実行するだけの小さなLangGraphグラフです。差分の判定自体は、LLM を介さない、シンプルで決定論的な Python 処理です。詳細は仕組みをご覧ください。

設定

endpoints:
  - id: stripe_customers
    url: https://api.stripe.com/v1/customers
    params:
      limit: 10
    headers:
      Authorization: Bearer ${STRIPE_API_KEY}   # expanded from the environment at request time
    ignore_paths:
      - $.data[*].metadata                      # free-form, changes all the time

notify:
  - type: slack
    webhook_url: ${SLACK_WEBHOOK_URL}

すべてのオプションについては設定リファレンスで説明しています。また、examples/には、そのまま実行できる設定があります。

他の方法との比較

• OpenAPI 差分ツール（oasdiff など）は、2 つの仕様書のバージョンを比較します。ベンダーが仕様書を公開・管理している場合には適したツールですが、ベンダーが文書化していない変更は検出できません。
• コントラクトテスト（Pact など）では、プロバイダーがコントラクトを実行する必要がありますが、サードパーティのベンダーは対応しません。
• 稼働監視やシンセティック監視では、API が稼働しているかどうかを確認できます。レスポンスのアサーションは、自分で作成・保守する必要があります。
• Tiltmeter は実際のレスポンスからコントラクトを学習するため、ベンダー側での対応は不要で、文書化されていない変更も検出できます。また、学習した内容をエージェントに渡します。

プライバシーとセキュリティ

• ${VAR} プレースホルダーは、リクエストまたは通知の送信直前に展開されます。値がディスクに書き込まれたり、LLM に送信されたり、LangGraph の状態に保持されたりすることはありません。また、エラーメッセージからは値が除去されます。
• 履歴には形状、ステータスコード、レイテンシ、変更が保存されます。store_samples: true を設定しない限り、レスポンス本文は保存されません。
• エージェントがチェックできるのは、設定に記載されたエンドポイントだけです。Tiltmeter に任意の URL を呼び出させることはできません。
• tiltmeter fix は、変更一覧とエージェントが開くファイルを Anthropic に送信します。レスポンス値、${VAR} の値、.env などの未追跡ファイルは対象になりません。また、fix.ignore に一致するパスはブロックされます。

脅威モデルの全容と脆弱性の報告方法については、SECURITY.mdをご覧ください。

ロードマップ

• CI および MCP 経由での修正。 スケジュールされたチェックでドリフトが見つかったとき、GitHub Action から tiltmeter fix を実行し、エージェントが MCP ツールを通じて修正を依頼できるようにします。
• プロバイダーモード。 API ベンダーが変更を一度告知すると、すべての顧客にプルリクエストが届きます。
• 仕様書と変更履歴への対応。 ベンダーの OpenAPI 仕様書や変更履歴を、観測したレスポンスとあわせて差分比較します。
• ホスト型チェックとチーム向けダッシュボード。

ドキュメント

• はじめに：お使いのマシンで試せる 5 分間のガイド。
• 設定リファレンス：すべてのオプション、プレースホルダー、無視パターン。
• エージェントと MCP：Claude Code、Cursor、Claude Desktop、LangChain。
• CI とスケジュール実行：GitHub Actions、GitLab CI、cron。
• コードの修正：tiltmeter fix、エージェント、プルリクエストのレビュー方法。
• 仕組み：形状、ベースライン、差分ルール、パイプライン。
• FAQ とトラブルシューティング。

コントリビューション

バグ報告、アイデア、プルリクエストを歓迎します。プロジェクトのセットアップ方法や、望ましい変更についてはCONTRIBUTING.mdをご覧ください。参加するすべての方に、行動規範の遵守をお願いしています。

ライセンス

MIT