> ## 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를 위한 도구 선택 가이드, 컨텍스트 윈도우 경제성, 복사해서 바로 쓰는 에이전트 패턴이에요.

Tiro 데이터가 필요한 Claude Code·Cursor·ChatGPT 에이전트를 만들고 있다면, 이 페이지가 어떤 surface를 언제 호출할지와 컨텍스트 윈도우를 가볍게 유지하는 법을 알려줘요.

## 멘탈 모델

> **MCP는 컨텍스트로 반환하고, CLI는 디스크로 반환해요.**

MCP `get_note_transcript`를 호출하면 전체 transcript 텍스트(노트당 보통 5\~50 KB)가 대화 컨텍스트 윈도우에 주입돼요. 이후 모든 턴이 compaction이나 요약 전까지 그 무게를 계속 짊어지게 돼요.

`tiro notes transcript --output transcript.md`를 호출하면 같은 내용이 디스크에 저장되고, stdout에는 메타데이터 한 줄만 반환돼요:

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

transcript 100개라면 50 KB가 약 50 토큰(경로 + 개수)으로 줄어요. 필요할 때만 각각 읽으면 돼요.

## 도구 선택 치트시트

| 이럴 때…                     | 사용                                                  | 비고                                      |
| ------------------------- | --------------------------------------------------- | --------------------------------------- |
| 주제로 노트 찾기                 | MCP `search_notes`                                  | primary document가 함께 hydrate됨, 컨텍스트에 남음 |
| 노트 50개 이상 디스크로            | CLI `tiro notes search "…" --json > meetings.jsonl` | NDJSON 파이프, `jq`로 쉽게 자름                 |
| 그대로 인용하기                  | MCP `get_note_transcript`                           | 작은 일부만, 토큰 많이 듦                         |
| 전체 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가 언급된 모든 회의를 전체 transcript와 함께 가져와야 해요.

```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
```

누적 컨텍스트 비용: 약 80 토큰(stdout 3줄 + 메타데이터 ack 12개). 이제 회의 transcript 12개가 `./out/`에 있어요. 정확한 표현이 필요할 때만 `Read` 도구로 하나씩 읽으면 돼요.

MCP만 쓰는 경우와 비교해 보면, `get_note_transcript`를 12번 호출하면 60~~600 KB(transcript 12개 × 각 5~~50 KB)가 컨텍스트에 주입돼요. 대부분은 불필요한 무게예요. 실제로 자세히 봐야 하는 건 2\~3개뿐이거든요.

## 에러를 JSON으로 읽기

CLI의 모든 에러는 안정적인 envelope을 따라요:

```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
  }
}
```

안정적인 필드:

| 필드                 | 용도                                                  |
| ------------------ | --------------------------------------------------- |
| `error.code`       | machine-readable 식별자, 이걸로 분기                        |
| `error.errorType`  | 큰 분류(`unauthorized`, `not_found`, `bad_request`, …) |
| `error.suggestion` | 자동 복구를 위해 실행할 바로 그 명령                               |
| `error.httpStatus` | 해당되는 경우 upstream HTTP status                        |
| `error.requestId`  | 지원 에스컬레이션용 upstream `x-request-id`                  |

`error.message`는 사람이 읽는 용도이고 릴리스마다 표현이 바뀔 수 있으니, 이걸로 패턴 매칭하지 마세요.

## Exit code

| Code | 의미                                   | 에이전트 동작                                                   |
| ---- | ------------------------------------ | --------------------------------------------------------- |
| `0`  | 성공                                   | 계속                                                        |
| `1`  | 일반 에러                                | `error.code` 확인                                           |
| `2`  | usage 에러(잘못된 flag, 잘못된 날짜, 필수 인자 누락) | 호출을 고침, 무작정 재시도 금지                                        |
| `4`  | auth 필요                              | `tiro auth login` 실행 후 재시도                                |
| `64` | EX\_USAGE                            | `2`와 동일                                                   |
| `65` | EX\_DATAERR                          | 응답이 schema 검증 실패, 사용자에게 알림                                |
| `78` | EX\_CONFIG                           | env·keychain에 token 없음, 사용자에게 인증 요청 또는 `TIRO_TOKEN` 제공 요청 |

셸에서 빠른 auth 복구 루프:

```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는 한 줄에 JSON 객체 하나씩 내보내요. 페이지네이션 cursor는 마지막에 `{"_cursor": "…"}` 줄로 와요.
* **`--output <path>`는 원자적으로 씀** — temp 파일 + rename 방식이라 절대 부분 저장이 없어요.
* **TTY 자동 감지** — 인터랙티브 셸에선 pretty, 파이프·리다이렉트되면 JSON. `--pretty` / `--json`으로 강제할 수 있어요.
* **`tiro notes transcript --format json`은 MCP `get_note_transcript`와 일치** — 같은 필드명, 같은 중첩, 같은 speaker-segment 구조예요. 기존 파서를 그대로 재사용하세요.
* **token은 절대 출력되지 않음** — `auth status`는 앞 4자만 보여주고, `--verbose`에서도 나머지는 가려져요.

## 안정 계약 — patch 릴리스에서 깨지지 않는 것

* `error.code` 값
* `error.errorType` 값
* Exit code
* list/search의 NDJSON 줄 형태
* `tiro notes transcript --format json`이 반환하는 MCP 형태 JSON
* `--output` 작업이 반환하는 메타데이터 줄 형태

그 외(pretty 출력, 에러 메시지, verbose 로그 포맷)는 best-effort이고 바뀔 수 있어요.

## 링크

* [Quickstart](/ko/developers/cli/quickstart) — 직접 해보는 다섯 가지 시나리오.
* [Setup](/ko/developers/cli/setup) — 설치 + 인증 + headless/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)