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

​
멘탈 모델

MCP는 컨텍스트로 반환하고, CLI는 디스크로 반환해요.
MCP get_note_transcript를 호출하면 전체 transcript 텍스트(노트당 보통 5~50 KB)가 대화 컨텍스트 윈도우에 주입돼요. 이후 모든 턴이 compaction이나 요약 전까지 그 무게를 계속 짊어지게 돼요. tiro notes transcript --output transcript.md를 호출하면 같은 내용이 디스크에 저장되고, stdout에는 메타데이터 한 줄만 반환돼요: 
{"ok":true,"data":{"saved":"./transcript.md","size":12450,"format":"md","guid":"note-a8f2c1…","paragraphCount":42,"segmentCount":127}}
transcript 100개라면 50 KB가 약 50 토큰(경로 + 개수)으로 줄어요. 필요할 때만 각각 읽으면 돼요.

​
도구 선택 치트시트

이럴 때…사용비고
주제로 노트 찾기MCP search_notesprimary document가 함께 hydrate됨, 컨텍스트에 남음
노트 50개 이상 디스크로CLI tiro notes search "…" --json > meetings.jsonlNDJSON 파이프, 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 jsonMCP 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와 함께 가져와야 해요. 
# 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번 호출하면 60600 KB(transcript 12개 × 각 550 KB)가 컨텍스트에 주입돼요. 대부분은 불필요한 무게예요. 실제로 자세히 봐야 하는 건 2~3개뿐이거든요.

​
에러를 JSON으로 읽기

CLI의 모든 에러는 안정적인 envelope을 따라요: 
{
  "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.codemachine-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 확인
2usage 에러(잘못된 flag, 잘못된 날짜, 필수 인자 누락)호출을 고침, 무작정 재시도 금지
4auth 필요tiro auth login 실행 후 재시도
64EX_USAGE2와 동일
65EX_DATAERR응답이 schema 검증 실패, 사용자에게 알림
78EX_CONFIGenv·keychain에 token 없음, 사용자에게 인증 요청 또는 TIRO_TOKEN 제공 요청
셸에서 빠른 auth 복구 루프: 
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이고 바뀔 수 있어요.

​
링크