Gitlawb/zero 딥다이브
— 내 모델·내 컴퓨터·내 규칙으로 굴리는 터미널 코딩 에이전트

1프로젝트 한줄 요약

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

2왜 주목받는가

Claude Code·Codex가 즐비한데 왜 하필 zero인가.

터미널 코딩 에이전트는 이미 레드오션이다(Claude Code, OpenAI Codex, aider, opencode…). 그럼에도 zero가 TrendShift 상위에 오른 이유는 세 가지 "소유권(ownership)" 포인트를 하나의 도구에 모두 담았기 때문이다: 모델 소유(어떤 LLM이든), 데이터 소유(전부 로컬), 실행 통제 소유(OS 샌드박스).

경쟁 도구 대비 비교

3기술 스택 전체 지도

go.mod과 internal/ 트리에서 실제로 읽어낸 구성.

핵심 언어·런타임

TUI(터미널 UI) 계층 — charm 생태계

provider(두뇌) 계층

internal/providers/ 아래에 anthropic/, openai/, gemini/ 세 개의 네이티브 클라이언트가 있고, factory.go가 설정에 따라 알맞은 클라이언트를 만든다. 코드를 열어보면 ProviderKindOpenAI, ProviderKindOpenAICompatible, ProviderKindAnthropic, ProviderKindAnthropicCompat, ProviderKindGoogle 같은 종류(kind)로 갈라진다. 즉 "OpenAI 호환"이라는 사실상의 표준 프로토콜 하나만 맞으면 어떤 신규 모델이든 흡수된다. OAuth 로그인(zero auth), 모델 능력 카탈로그(modelregistry), provider 건강검진(providerhealth), 자동 탐지(providermodeldiscovery)까지 별도 패키지로 분리돼 있다.

확장(플러그인) 계층

4아키텍처 심화 분석 — 에이전트 루프 + 샌드박스

두 개의 심장: (1) 도구를 부르며 목표에 다가가는 루프, (2) 그 도구를 커널이 가두는 샌드박스.

전체 구조도

핵심 설계 패턴 1 — 에이전트 루프(agent/loop.go)

루프는 "LLM에게 물어보고 → 도구를 실행하고 → 결과를 다시 넣는" 것을 반복한다. 코드를 보면 단순한 while가 아니라 실전에서 부딪히는 함정들을 하나하나 방어한다:

• 최대 턴 제한: 무한 도구 호출을 막고, 한계에 닿으면 "도구 그만 쓰고 지금까지 한 걸 요약하라"고 강제 마무리.
• 이미지 거부 400 감지: 텍스트 전용 모델에 이미지를 넣어 400 에러가 무한 반복되던 실제 버그를, 압축-재시도 경로보다 먼저 잡아낸다.
• 스트림 정체(stall) 재시도: 출력이 하나도 없이 멈춘 연결만 최대 2회 새 연결로 재발행(부분 출력이 있으면 중복되므로 재시도 안 함).
• compaction(맥락 압축): 대화가 길어져 컨텍스트가 꽉 차면 과거를 요약해 자리를 비운다(compaction.go + 보존 규칙).
• guardrails / self-correct: 에이전트가 헛도는지 감시하고(no-progress-stop), 스스로 오류를 교정하는 로직.

핵심 설계 패턴 2 — 커널 샌드박스(sandbox/landlock_linux.go)

대부분의 코딩 에이전트가 "이 명령 실행할까요?"라는 프롬프트로만 안전을 지킨다면, zero는 여기에 OS 커널 수준의 강제를 얹는다. Linux에서는 Landlock(파일시스템 접근을 커널이 제한)과 seccomp(허용된 시스템콜만 통과)를 쓴다. 코드를 보면 도구 실행 직전에 PR_SET_NO_NEW_PRIVS를 걸어 권한 상승을 원천 차단한 뒤, 워크스페이스 밖 쓰기·네트워크 열기를 커널에 등록한 규칙으로 막는다.

// sandbox/landlock_linux.go — 실제 구조(요약)
func ApplyLandlockFilesystemProfile(profile, cwd) error {
    // 1) 이 프로세스는 이제 권한을 더 못 얻는다
    unix.Prctl(unix.PR_SET_NO_NEW_PRIVS, 1, ...)
    // 2) 파일시스템 규칙: 워크스페이스만 쓰기 허용
    // 3) 네트워크 차단(NetworkDeny)이면 소켓 개설 봉쇄
    // → 이후 caller가 최종 명령을 exec 한다
}

핵심 설계 패턴 3 — specialist & swarm(서브에이전트)

하나의 큰 문제를 전문 서브에이전트에게 위임한다. internal/specialist/에는 코드 리뷰·회계 같은 역할별 실행기가 있고, internal/swarm/은 여러 멤버 에이전트를 coordinator가 지휘하고 mailbox로 메시지를 주고받으며 scheduler가 작업을 배분하는 병렬 팀 협업 구조다. 메인 에이전트가 지휘자, 서브들이 일꾼인 셈.

헤드리스 모드와 stream-JSON

zero exec는 TUI 없이 스크립트로 돌리는 모드다. --input-format stream-json / --output-format stream-json으로 JSON 라인 스트림을 표준입출력으로 주고받아 CI 파이프라인에 물릴 수 있고, 의미 있는 종료 코드를 돌려준다. --worktree로 격리된 git worktree에서 실험하고, --use-spec로 "먼저 계획을 세우고 실행"하는 spec-first 방식도 지원한다.

5디렉토리 구조 해부

internal/ 아래 60여 개 패키지 — 어디에 무엇이 있나.

6학습 포인트 (주제별)

이 저장소에서 실제로 뽑아 배울 수 있는 것들.

① Go로 만드는 프로덕션 CLI/TUI

bubbletea의 Elm 아키텍처(Model-Update-View)로 대화형 터미널 앱을 만드는 정석을 볼 수 있다. 슬래시 커맨드 자동완성, 실시간 도구 렌더링, 스크롤백, 테마 라이브 프리뷰 같은 UX가 어떻게 상태머신으로 구현되는지 배운다.

② LLM provider 추상화 설계

서로 다른 API(OpenAI Chat/Responses, Anthropic Messages, Gemini)를 하나의 내부 인터페이스로 통합하는 법. "OpenAI 호환/Anthropic 호환"이라는 사실상의 표준을 축으로 신규 provider를 어댑터로 흡수하는 factory 패턴이 교과서적이다.

③ OS 수준 샌드박싱 실전

가장 희소가치 높은 학습 포인트. Linux Landlock LSM, seccomp-bpf, PR_SET_NO_NEW_PRIVS, macOS의 sandbox-exec+로그 감시, Windows 헬퍼 프로세스까지 — "신뢰할 수 없는 코드를 어떻게 커널로 가두나"를 실제 코드로 공부할 수 있다. 보안·인프라 지망생에게 특히 값지다.

④ 에이전트 신뢰성 엔지니어링

맥락 압축, 무한루프 방지, 스트림 정체 재시도, 이미지 거부 감지, 권한 스코프 — LLM 에이전트를 "데모"가 아닌 "제품"으로 만들 때 부딪히는 현실 문제와 그 해법이 internal/agent의 테스트 파일 이름에 고스란히 드러난다.

⑤ 확장 생태계 통합(MCP·skills·hooks)

MCP 클라이언트/서버 양방향 구현, 마크다운 스킬, 수명주기 훅, 플러그인을 한 CLI에 모두 태우는 아키텍처. 자신만의 에이전트 확장을 설계할 때 참고 지도가 된다.

7시스템 요구사항

돌리려면·빌드하려면 무엇이 필요한가.

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

난이도별로 손을 움직여 보자.

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

zero를 제대로 이해하려면 곁들이면 좋은 순서.

10핵심 키워드 사전

문서에 자주 나오는 용어 빠른 참조.

11참고 링크

직접 파고들 때.