huggingface/tau 딥다이브
— "읽어서 배우는" 미니멀 코딩 에이전트

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

tau의 코드는 3개의 계층으로 명확히 나뉜다. README가 그린 그림 그대로:

tau_ai는 여러 모델 프로바이더(OpenAI, Anthropic 등)의 서로 다른 API를 tau만의 프로바이더 중립 스트림으로 번역한다. tau_agent는 "이식 가능한 두뇌"를 담고 있다 — 메시지, 툴, 이벤트, 루프, 하니스, 세션 원시 타입까지 전부 CLI나 UI를 몰라도 되는 순수 로직이다. tau_coding은 그 두뇌를 실제 코딩 앱으로 감싼다 — CLI, TUI, 파일/셸 툴, 프로바이더 설정, 프로젝트 지침, 스킬, 디스크에 저장되는 세션까지.

2왜 주목받는가

"교육용 코딩 에이전트"라는 드문 포지셔닝 · Hugging Face의 후원 · Claude Code/opencode/pi 대비 위치.

2026년 코딩 에이전트 생태계는 이미 붐비다 못해 포화 상태다. Claude Code, opencode, Codex CLI, Aider, Cursor CLI 등 실전에서 쓰는 도구는 넘쳐난다. 그런데 tau가 TrendShift에서 주목받는 이유는 "실전에서 더 잘 쓰기 위한" 경쟁이 아니라 "어떻게 만들어지는지 배우기 위한" 경쟁에 참가했기 때문이다. 이 포지셔닝은 실제로 드물다.

다른 코딩 에이전트와 무엇이 다른가

3기술 스택 전체 지도

Python 3.14+, Textual TUI, Rich, uv, 프로바이더 5종, PyPI 배포 — 각각 상세.

pyproject.toml을 열어 보면 tau의 런타임 의존성이 놀랍도록 적다 — 딱 7개뿐이다. 이는 우연이 아니라 "작은 레이어가 마법을 이긴다"는 철학의 직접적 결과다.

4아키텍처 심화 분석

tau_ai→tau_agent→tau_coding 3계층 · 이벤트 스트림 계약 · AgentHarness vs CodingSession vs TUI 경계 · 툴=타입드 함수 · JSONL 세션.

tau의 아키텍처를 이해하는 가장 좋은 방법은 "요청 하나가 어디를 거쳐 화면까지 도달하는가"를 실제 소스 코드로 따라가 보는 것이다. 이 절에서는 tau_agent/harness.py·loop.py·events.py·tools.py와 tau_coding/tui/adapter.py를 근거로 그 경로를 그려본다.

① 핵심 경계 — "두뇌 vs 코딩 환경 vs 프론트엔드"

README가 명시하는 문장을 그대로 옮기면: "AgentHarness = reusable brain, CodingSession = coding-agent environment, TUI = one possible frontend". 실제 코드에서 이 경계가 어떻게 지켜지는지 보면 — tau_agent/harness.py의 AgentHarness 클래스는 메시지 리스트, 이벤트 리스너, 취소 토큰, 스티어링/팔로업 큐만 알면 된다. 이 클래스 안에는 파일 경로도, 터미널 렌더링도, 세션 JSONL 저장 로직도 전혀 없다. 반면 tau_coding/session.py의 CodingSession은 같은 AgentHarness 인스턴스를 소유하면서 그 위에 프로젝트 지침 로딩, 스킬 확장, 슬래시 커맨드, JSONL 세션 저장, 자동 압축까지 코딩 앱에 필요한 모든 걸 덧붙인다.

② 이벤트 스트림 — "이벤트가 계약이다"를 코드로 확인하기

tau_agent/events.py는 PEP 695 type 별칭으로 AgentEvent를 14가지 pydantic 모델의 합집합(union)으로 정의한다 — AgentStartEvent, TurnStartEvent, MessageDeltaEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, ErrorEvent 등. 모든 이벤트가 model_config = ConfigDict(extra="forbid")를 쓴다는 점이 중요한데, 이는 "정의되지 않은 필드가 몰래 섞여 들어가는 것"을 pydantic이 즉시 막아준다는 뜻이다 — 이벤트 스키마가 사실상의 API 계약이 된다.

# tau_agent/events.py 실제 union 정의 (PEP 695 type 별칭)
type AgentEvent = (
    AgentStartEvent | AgentEndEvent
    | TurnStartEvent | TurnEndEvent
    | QueueUpdateEvent | RetryEvent
    | MessageStartEvent | MessageDeltaEvent | ThinkingDeltaEvent | MessageEndEvent
    | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent
    | ErrorEvent
)

이 계약이 실전에서 어떻게 소비되는지는 tau_coding/tui/adapter.py의 TuiEventAdapter.apply()가 정확히 보여준다. 이 메서드는 isinstance(event, ...) 체인으로 각 이벤트 타입을 분기해 TuiState(순수 데이터 클래스)를 갱신할 뿐, Textual 위젯을 직접 건드리지 않는다. 반대편에는 tau_coding/rendering/ 아래 FinalTextRenderer·JsonEventRenderer·TranscriptRenderer가 있는데, 이들은 같은 AgentEvent 스트림을 완전히 다른 방식(순수 텍스트/JSON/트랜스크립트)으로 소비한다 — "이벤트가 계약"이라는 말이 실제로 여러 프론트엔드가 같은 계약을 놓고 자유롭게 구현을 갈아 끼울 수 있다는 뜻임을 코드로 확인할 수 있다.

③ 프로바이더 경계 — ProviderEvent → AgentEvent 번역

tau_ai/events.py는 tau_agent/events.py와 별개의 이벤트 계층을 정의한다(ProviderResponseStartEvent, ProviderTextDeltaEvent, ProviderToolCallEvent 등). tau_agent/loop.py의 run_agent_loop()가 바로 이 두 계층 사이의 번역자다 — provider.stream_response()가 내보내는 ProviderEvent를 하나씩 받아, isinstance 분기로 대응하는 AgentEvent로 변환해 yield한다. 왜 프로바이더 전용 이벤트와 에이전트 전용 이벤트를 분리했을까 — 프로바이더가 늘어나도(OpenAI, Anthropic, Codex, 커스텀 엔드포인트) 그 위의 에이전트/UI 계층 코드는 한 글자도 안 바뀌게 하기 위해서다.

// tau_agent/loop.py 핵심 번역 로직 (실제 코드 발췌)
async for provider_event in provider.stream_response(...):
    if isinstance(provider_event, ProviderResponseStartEvent):
        yield MessageStartEvent()
    elif isinstance(provider_event, ProviderTextDeltaEvent):
        yield MessageDeltaEvent(delta=provider_event.delta)
    elif isinstance(provider_event, ProviderResponseEndEvent):
        assistant_message = provider_event.message
        messages.append(assistant_message)   // 트랜스크립트는 loop가 직접 갱신
        yield MessageEndEvent(message=assistant_message)
    elif isinstance(provider_event, ProviderErrorEvent):
        yield ErrorEvent(message=provider_event.message, recoverable=False)

④ 툴 = 스키마 + 비동기 실행기

tau_agent/tools.py의 AgentTool은 놀랍도록 단순한 @dataclass(frozen=True, slots=True)다 — name, description, input_schema(JSON 스키마), executor(비동기 콜러블) 4개 필드가 전부다. "툴은 그냥 평범한 타입드 함수"라는 철학이 그대로 타입 시그니처가 됐다. 실제 구현은 tau_coding/tools.py(1,055줄)의 create_coding_tools()가 read·write·edit·bash 4종을 생성하며, 각 팩토리 함수는 실행기 클로저 안에서 cwd 기준 경로 해석, 출력 바이트/라인 트렁케이션, 동시 쓰기 방지용 파일별 asyncio.Lock까지 처리한다.

⑤ JSONL 세션 — append-only 트리 구조 + 재생(replay)

tau의 세션 저장 방식은 "히스토리를 통째로 덮어쓰는" 대신 추가만 하는(append-only) JSONL 파일이다. tau_agent/session/entries.py는 9가지 SessionEntry 타입(MessageEntry, ModelChangeEntry, CompactionEntry, BranchSummaryEntry, LeafEntry 등)을 정의하고, 각 엔트리는 id와 parent_id를 가진다 — 즉 세션 파일 하나가 사실은 트리(tree) 구조다. session/tree.py의 path_to_entry()는 임의의 리프(leaf) id에서 부모를 따라 올라가며 루트까지의 경로를 복원한다.

이 구조 덕분에 세션 분기(branching)가 자연스럽게 가능하다 — 같은 parent_id를 가리키는 서로 다른 leaf_id 두 개는 "같은 지점에서 갈라진 두 개의 대화 흐름"이 된다. 파일은 절대 잘리거나 덮어써지지 않고, "지금 어느 리프에 있는지"만 LeafEntry로 추적한다. CompactionEntry는 이 append-only 원칙을 지키면서도 "요약으로 대체"를 구현하는 영리한 방법을 보여준다 — 원본 엔트리는 그대로 남기고, 재생(replay) 시점에만 replaces_entry_ids에 나열된 옛 메시지들을 요약 하나로 치환한다(session/memory.py의 _apply_compaction()).

5디렉토리 구조 해부

src/의 3패키지 실제 구성 + dev-notes/website/tests 역할.

6학습 포인트 (기술별)

이 저장소에서 실제로 무엇을 배울 수 있는가 + 각 주제 실습 아이디어.

7하드웨어 / 시스템 요구사항

GPU 불필요 · 로컬 실행 중심 · 모델 프로바이더 API 키만 있으면 됨.

tau는 GPU도, 특별한 인프라도 필요 없는 순수 CPU·터미널 애플리케이션이다. 실제로 무거운 계산(LLM 추론)은 전부 원격 프로바이더 API가 담당하고, tau 자신은 파일 읽기/쓰기, 셸 명령 실행, HTTP 요청 정도의 가벼운 작업만 로컬에서 수행한다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 설치·사용부터 새 프로바이더 붙이기까지.

과제 1 · 설치하고 첫 대화 나눠보기 난이도 ★☆☆☆☆

가장 먼저 할 일이다. uv로 tau를 설치하고, 아무 프로젝트 폴더에서 실행해 /login으로 프로바이더를 연결한 뒤, "이 프로젝트 설명해줘" 같은 간단한 요청을 던져본다. 응답이 스트리밍되는 동안 터미널에 무엇이 표시되는지, 툴 호출(파일 읽기)이 어떻게 시각화되는지 관찰한다.

# 설치 & 실행
uv tool install tau-ai
cd my-project
tau

# TUI 안에서:
/login openai
explain what this project does

과제 2 · JSONL 세션 파일을 직접 열어 구조 파악하기 난이도 ★★☆☆☆

대화를 몇 차례 나눈 뒤 ~/.tau/sessions/ 아래 생성된 .jsonl 파일을 텍스트 에디터로 열어본다. 각 줄이 {"type": "message", "id": ..., "parent_id": ...} 형태의 독립된 JSON 객체임을 확인하고, message·leaf·session_info 타입이 각각 몇 개씩 있는지 세어본다. /tree 슬래시 커맨드로 tau가 보여주는 트리 구조와 파일 내용을 대조.

# 세션 파일 위치 확인 & 내용 보기
ls ~/.tau/sessions/
cat ~/.tau/sessions/<session-id>.jsonl | python3 -m json.tool --json-lines
grep -o '"type":"[a-z_]*"' ~/.tau/sessions/<session-id>.jsonl | sort | uniq -c

과제 3 · 새 코딩 툴 추가하기 (예: word_count) 난이도 ★★★☆☆

tau_coding/tools.py의 create_read_tool_definition() 구조를 그대로 참고해, 파일 경로를 입력받아 단어 수를 세어 반환하는 word_count 툴을 직접 작성한다. ToolDefinition(스키마 + 실행기)을 만들고 create_coding_tools()가 반환하는 리스트에 추가한 뒤, 실제로 tau를 재빌드해 "이 파일 단어 수 세어줘"라고 요청해 새 툴이 호출되는지 확인.

// 직접 구현해 볼 시그니처 (tau_coding/tools.py 패턴 참고)
def create_word_count_tool_definition(*, cwd: Path | None = None) -> ToolDefinition:
    # input_schema: {"path": str}
    # executor: 파일을 읽어 단어 수를 세고 AgentToolResult(ok=True, content=f"{n} words")로 반환
    ...

과제 4 · 커스텀 이벤트 렌더러(프론트엔드) 만들기 난이도 ★★★★☆

tau_coding/rendering/plain.py(FinalTextRenderer)의 구조를 참고해, AgentEvent 스트림을 받아 이모지가 포함된 한 줄 로그(예: 툴 실행 시작 = 🔧, 에러 = ❌, 메시지 완료 = ✅)로 출력하는 나만의 EventRenderer를 구현한다. EventRenderer 프로토콜(render() + finish())만 지키면 되므로 기존 코드를 전혀 건드릴 필요가 없다는 걸 체감하는 게 목표.

과제 5 · 새 모델 프로바이더 어댑터 붙이기 난이도 ★★★★★

tau_ai/fake.py(가장 단순한 참고 구현, 41줄)와 tau_ai/openai_compatible.py를 함께 읽고, Google Gemini나 Mistral처럼 아직 지원하지 않는 프로바이더용 ModelProvider 구현체를 처음부터 작성해 본다. stream_response() 하나만 구현해 ProviderTextDeltaEvent·ProviderResponseEndEvent를 올바르게 내보내면, tau_agent/loop.py는 전혀 수정하지 않고도 새 프로바이더가 tau 전체와 즉시 호환된다는 걸 직접 확인한다.

9관련 기술 심화 학습 로드맵

에이전트 루프 기초 → 이벤트 아키텍처 → 세션/영속화 → 프로바이더 통합 — 5주 계획.

10핵심 키워드 사전

이 문서와 저장소에 나온 주요 용어 정리.

11참고 링크

공식 저장소 · 문서 · 패키지 · 관련 프로젝트.