> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# AI エージェント向け

> CLI のためのツール選択ガイダンス、context window のコスト効率、そしてコピー＆ペーストできるエージェントパターン。

Tiro のデータを必要とする Claude Code、Cursor、または ChatGPT のエージェントを構築している場合、このページではどのサーフェスをいつ呼び出すべきか、そして context window を軽く保つ方法を説明します。

## メンタルモデル

> **MCP は context に返し、CLI はディスクに返す。**

MCP の `get_note_transcript` を呼び出すと、トランスクリプト全文（通常はノートあたり 5〜50 KB）が会話の context window に注入されます。以降のすべてのターンは、圧縮や要約が行われるまでその重みを抱え続けます。

`tiro notes transcript --output transcript.md` を呼び出すと、同じコンテンツがディスクに出力されます。stdout にはメタデータが 1 行返ります:

```json theme={"system"}
{"ok":true,"data":{"saved":"./transcript.md","size":12450,"format":"md","guid":"note-a8f2c1…","paragraphCount":42,"segmentCount":127}}
```

100 件のトランスクリプトであれば、50 KB が約 50 トークン（パス + カウント）になります。各ファイルは必要になったときにだけ読み込んでください。

## ツール選択のチートシート

| やりたいこと                      | 使うもの                                                | 備考                                  |
| --------------------------- | --------------------------------------------------- | ----------------------------------- |
| トピックでノートを探す                 | MCP `search_notes`                                  | 主要ドキュメントが付与され、context に存在する         |
| 50 件以上のノートをディスクに取得する        | CLI `tiro notes search "…" --json > meetings.jsonl` | NDJSON パイプ。`jq` で簡単にスライスできる         |
| 逐語的な引用を読む                   | MCP `get_note_transcript`                           | 小さな部分集合のみ。トークン消費が大きい                |
| 後で使うために全文トランスクリプトを保存する      | CLI `tiro notes transcript <guid> --output <path>`  | コンテンツはディスク、メタデータは stdout            |
| 日付で会議をブラウズする                | CLI `tiro notes list --since 7d --json`             | 軽量。メタデータのみ                          |
| MCP ホストなしで MCP 形式の JSON を読む | CLI `tiro notes transcript <guid> --format json`    | MCP `get_note_transcript` とバイト単位で一致 |

## MCP と CLI のどちらを呼ぶか

```
Are you in an MCP-aware client (Claude Desktop, Cursor, Code)?
│
├─ NO  → CLI is your only option. Use --json everywhere.
│
└─ YES → Will the result fit comfortably in your context window?
         (Rule of thumb: <5 KB total, single-shot reasoning)
         │
         ├─ YES → MCP. Schema-typed call, multi-turn friendly.
         │
         └─ NO  → CLI with --output. Disk holds the content,
                  context holds the path. Reach for Read tool
                  on demand.
```

## 実践例 — 30 日分の「Acme Corp」の会議

クライアント別の四半期サマリーを作成したいとします。直近 30 日間で Acme が話題に上がったすべての会議について、全文トランスクリプトが必要です。

```bash theme={"system"}
# 1. Search → metadata + hydrated documents (NDJSON)
tiro notes search "Acme Corp" --since 30d --json > /tmp/acme.jsonl
# stdout: ~12 lines of NDJSON, ~3 KB total

# 2. Pull guids without loading bodies
cat /tmp/acme.jsonl | jq -r '.guid' > /tmp/guids.txt

# 3. Download each transcript to disk (paths only return to context)
xargs -I{} tiro notes transcript {} --output ./out/{}.md < /tmp/guids.txt
```

累積の context コスト: 約 80 トークン（stdout 3 行 + メタデータの ack 12 件）。12 件の会議トランスクリプトが `./out/` に保存されます。正確な文言が必要なときにだけ、`Read` ツールで 1 件ずつ読み込んでください。

MCP のみの場合と比較してみましょう。`get_note_transcript` を 12 回呼び出すと、60〜600 KB が context に注入されます（トランスクリプト 12 件 × 各 5〜50 KB）。その大半は不要な重荷です。詳細に必要なトランスクリプトは 2〜3 件だけです。

## エラーを JSON として読む

CLI のすべてのエラーは、安定したエンベロープに従います:

```json theme={"system"}
{
  "ok": false,
  "error": {
    "code": "auth_required",
    "message": "Not authenticated. Run `tiro auth login` to sign in, or set TIRO_TOKEN env var.",
    "suggestion": "tiro auth login",
    "errorType": "auth_required",
    "httpStatus": null,
    "requestId": null
  }
}
```

安定したフィールド:

| Field              | 用途                                                    |
| ------------------ | ----------------------------------------------------- |
| `error.code`       | 機械可読の識別子 — これで分岐する                                    |
| `error.errorType`  | 粗い粒度のカテゴリ（`unauthorized`、`not_found`、`bad_request`、…） |
| `error.suggestion` | 自動リカバリのために次に実行すべき正確なコマンド                              |
| `error.httpStatus` | 上流の HTTP ステータス（該当する場合）                                |
| `error.requestId`  | サポートへのエスカレーション用の上流 `x-request-id`                     |

`error.message` は人間が読むためのもので、リリースごとに文言が変わる場合があります。これに対してパターンマッチを行わないでください。

## 終了コード

| Code | 意味                             | エージェントのアクション                                                  |
| ---- | ------------------------------ | ------------------------------------------------------------- |
| `0`  | 成功                             | 続行する                                                          |
| `1`  | 一般的なエラー                        | `error.code` を確認する                                            |
| `2`  | 使用方法のエラー（不正なフラグ、無効な日付、必須引数の欠落） | 呼び出しを修正する。やみくもに再試行しない                                         |
| `4`  | 認証が必要                          | `tiro auth login` を実行してから再試行する                                |
| `64` | EX\_USAGE                      | `2` と同じ                                                       |
| `65` | EX\_DATAERR                    | レスポンスがスキーマ検証に失敗した。ユーザーに通知する                                   |
| `78` | EX\_CONFIG                     | env にも keychain にもトークンがない。認証するか `TIRO_TOKEN` を指定するようユーザーに依頼する |

シェルでの簡単な認証リカバリループ:

```bash theme={"system"}
output=$(tiro notes list --json 2>&1)
exit_code=$?
if [ $exit_code -eq 4 ] || [ $exit_code -eq 78 ]; then
  tiro auth login
  output=$(tiro notes list --json)
fi
echo "$output"
```

## 出力の保証

* **`--json` はストリームに対して NDJSON** — list と search は 1 行につき 1 つの JSON オブジェクトを出力します。ページネーションカーソルは最後の `{"_cursor": "…"}` 行として届きます。
* **`--output <path>` はアトミックに書き込む** — 一時ファイル + リネームで、部分的な書き込みは決して発生しません。
* **TTY の自動検出** — インタラクティブなシェルでは見やすく、パイプやリダイレクト時には JSON になります。`--pretty` / `--json` でどちらかを強制できます。
* **`tiro notes transcript --format json` は MCP `get_note_transcript` と一致** — 同じフィールド名、同じネスト、同じ話者セグメント構造です。既存のパーサーを再利用できます。
* **トークンは決してエコーされない** — `auth status` は最初の 4 文字のみを表示し、`--verbose` のログでさえ残りは伏せられます。

## 安定したコントラクト — パッチリリースをまたいで壊れないもの

* `error.code` の値
* `error.errorType` の値
* 終了コード
* list/search の NDJSON 行の形式
* `tiro notes transcript --format json` が返す MCP 形式の JSON
* `--output` 操作が返すメタデータ行の形式

それ以外（見やすい出力、エラーメッセージ、verbose ログの形式）はベストエフォートであり、変更される場合があります。

## リンク

* [Quickstart](/ja/developers/cli/quickstart) — 実践的な 5 つのシナリオ。
* [Setup](/ja/developers/cli/setup) — インストール + 認証 + ヘッドレス/CI の設定。
* [CLI on npm](https://www.npmjs.com/package/@theplato/tiro-cli)
* [tiro-cli on GitHub](https://github.com/plato-corp/tiro-cli)
* [CHANGELOG](https://github.com/plato-corp/tiro-cli/blob/main/CHANGELOG.md)