Tiro CLI for AI agents

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 行返ります:

{"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 が話題に上がったすべての会議について、全文トランスクリプトが必要です。

# 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 のすべてのエラーは、安定したエンベロープに従います:

{
  "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` を指定するようユーザーに依頼する

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

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 — 実践的な 5 つのシナリオ。
Setup — インストール + 認証 + ヘッドレス/CI の設定。
CLI on npm
tiro-cli on GitHub
CHANGELOG

​メンタルモデル

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

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

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

​エラーを JSON として読む

​終了コード

​出力の保証

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

​リンク