Zerostack - 순수 Rust로 작성된 Unix에서 영감을 받은 코딩 에이전트

• zerostack은 Rust로 작성된 최소형 코딩 에이전트로, 여러 LLM 제공자와 사용자 지정 제공자를 함께 지원함
• 파일 읽기·쓰기·편집, grep, 파일 찾기, 디렉터리 목록, 권한 게이트가 붙은 Bash 실행, MCP, Exa 웹 도구를 제공함
• 약 7천 LoC, 8.9MB 바이너리이며 RAM은 빈 세션 약 8MB·작업 중 약 12MB, CPU는 유휴 0.0%로 측정됨
• 기본 제공자는 OpenRouter이고 cargo install zerostack으로 설치하며, --sandbox에서 Bash 격리를 쓰려면 bubblewrap이 필요함
• code·plan·review 등 내장 프롬프트, 4가지 권한 모드, 세션 재개, 반복 루프, Git worktrees 통합을 포함함

zerostack 개요

• zerostack은 Rust로 작성된 최소형 코딩 에이전트이며, pi와 opencode에서 영감을 받음
• OpenRouter, OpenAI, Anthropic, Gemini, Ollama, 사용자 지정 제공자를 지원하는 다중 제공자 구조를 갖춤
• 파일 읽기·쓰기·편집, grep, 파일 찾기, 디렉터리 목록 같은 파일 도구와 권한 게이트가 붙은 Bash 실행을 제공함
• 세션 저장·로드·재개, 컨텍스트 창 유지를 위한 자동 압축, crossterm 기반 터미널 UI, MCP 서버 연결, Exa 기반 WebFetch·WebSearch 도구를 포함함
• /worktree로 Git worktree 사이를 이동할 수 있고, 장기 작업을 위한 반복 루프도 통합됨

성능과 설치

• zerostack은 약 7천 LoC 규모이며, 바이너리 크기는 8.9MB임
• RAM 사용량은 빈 세션 약 8MB, 작업 중 약 12MB로, opencode나 다른 JS 기반 코딩 에이전트의 약 300MB와 비교됨
• CPU 사용량은 유휴 상태 0.0%, 도구 사용 중 약 1.5% 로 측정됐으며, Intel i5 7세대에서 opencode는 유휴 약 2%, 작업 중 약 20% 로 비교됨
• 설치에는 Cargo와 git이 필요하며, 다음 명령을 사용함 cargo install zerostack
• --sandbox 사용 시 모든 Bash 명령을 격리 환경에서 실행하려면 bubblewrap을 설치해야 함 # Debian/Ubuntu apt install bubblewrap # Fedora dnf install bubblewrap # Arch pacman -S bubblewrap

빠른 시작

• 기본 제공자는 OpenRouter이며, API 키는 환경 변수로 설정함 export OPENROUTER_API_KEY="[api_key]"
• 대화형 세션은 기본 프롬프트 code로 실행됨 zerostack
• 한 번만 실행하는 모드는 -p로 프롬프트를 전달함 zerostack -p "Explain this project"
• 마지막 세션은 -c로 이어서 실행함 zerostack -c
• 제공자와 모델을 명시할 수 있음 zerostack --provider openrouter --model deepseek/deepseek-v4-flash

프롬프트 시스템

• zerostack은 에이전트의 동작과 말투를 바꾸는 내장 시스템 프롬프트 세트를 포함함
• 목표는 superpower나 Claude 공식 skills를 대체할 수 있는 프롬프트 제품군을 만드는 것임
• /prompt로 등록된 프롬프트를 나열하거나 다른 프롬프트로 전환할 수 있음

• 내장 프롬프트

  • code는 기본값이며, 전체 파일·Bash 도구 접근과 TDD 워크플로를 사용하는 코딩 모드임
  • plan은 코드를 쓰지 않고 탐색한 뒤 계획을 만드는 계획 전용 모드임
  • review는 정확성, 설계, 테스트, 영향을 검토하는 코드 리뷰 모드임
  • debug는 수정안을 내기 전에 근본 원인을 찾는 디버그 모드임
  • ask는 읽기 전용 모드이며, read·grep·glob만 허용하고 쓰기나 Bash는 허용하지 않음
  • brainstorm은 코드를 작성하지 않고 아이디어를 탐색하고 설계를 제시하는 설계 전용 모드임
  • frontend-design는 독특하고 프로덕션 수준의 UI를 위한 프론트엔드 디자인 모드임
  • review-security는 악용 가능한 취약점을 찾는 보안 리뷰 모드임
  • simplify는 동작을 바꾸지 않고 명확성을 높이는 코드 단순화 모드임
  • write-prompt는 에이전트 프롬프트를 만들고 최적화하는 프롬프트 작성 모드임
  • 사용자 지정 프롬프트는 $XDG_CONFIG_HOME/zerostack/prompts/에 Markdown 파일을 두고 이름으로 참조해 만들 수 있음
  • 프로젝트 루트나 상위 디렉터리의 AGENTS.md 또는 CLAUDE.md를 자동으로 읽어 시스템 프롬프트에 삽입하며, -n 또는 --no-context-files로 비활성화 가능함

권한 시스템

• zerostack은 가장 안전한 방식부터 가장 허용적인 방식까지 4가지 권한 모드를 제공함

• 권한 모드

  • restrictive 또는 -R은 설정에서 명시적으로 허용하지 않은 모든 도구 동작마다 승인을 요청함
  • standard는 기본값이며, ls, cd, git log, cargo check 같은 안전한 명령은 자동 승인하고 쓰기와 파괴적 작업은 확인을 요청함
  • accept-all 또는 --accept-all은 작업 디렉터리 안의 모든 작업을 자동 승인하고 외부 경로는 확인을 요청함
  • yolo 또는 --yolo는 프롬프트 없이 모든 작업을 자동 승인함
  • 설정 파일에서 도구별 glob 패턴을 지정해 권한을 세밀하게 구성할 수 있음
  • 예를 들어 write **.rs는 자동 허용하면서 다른 파일 쓰기는 항상 확인하도록 만들 수 있음
  • 세션 허용 목록은 승인된 결정을 세션 동안 유지해 같은 작업을 반복 확인하지 않게 함
  • 동일한 도구 호출이 3회 이상 반복되면 doom-loop 감지가 경고 프롬프트를 띄우거나 설정에 따라 거부해, 에이전트가 파괴적 작업을 반복하지 못하게 막음

슬래시 명령과 세션 관리

• 주요 슬래시 명령은 모델, 사고 수준, 대화, 세션, 루프, 프롬프트, 권한 모드를 제어함
• /model은 모델을 전환하고, /thinking은 사고 수준을 설정함
• /clear는 대화를 지우고, /session은 세션을 나열·저장·로드함
• /loop는 반복 프롬프트를 예약하고, /prompt는 에이전트 프롬프트를 나열하거나 변경함
• /mode는 권한 시스템 모드를 설정하며, 전체 명령은 /help로 확인함
• 세션은 $XDG_DATA_HOME/zerostack/sessions/에 저장됨
• -c는 가장 최근 세션을 재개하고, -r은 세션을 탐색해 선택하며, --session <id>는 특정 세션을 로드함

반복 루프

• zerostack은 장기 작업을 위한 반복 코딩 루프를 포함함
• 에이전트는 작업을 반복해서 읽고, 계획에서 항목을 고르고, 작업을 수행하고, 테스트를 실행하고, 계획을 갱신하며, 작업 완료 또는 반복 제한 도달까지 루프를 계속함
• 루프 시스템은 실험적 기능임

• 루프 사용법

  • /loop Implement the user authentication system은 지정한 프롬프트로 루프를 시작함
  • /loop stop은 활성 루프를 중지함
  • /loop status는 현재 루프 상태를 표시함
  • 각 반복에는 원래 작업, 변화하는 LOOP_PLAN.md, 이전 반복 요약, 검증 출력이 포함됨
  • 루프가 활성화된 동안에는 슬래시 명령이 아닌 입력이 차단됨

• CLI 기반 헤드리스 루프

  • 다음 명령으로 헤드리스 루프를 실행할 수 있음 zerostack --loop --loop-prompt "Refactor the API" --loop-max 10 --loop-run "cargo test"
  • --loop는 헤드리스 루프 모드를 켬
  • --loop-prompt <text>는 각 반복에 사용할 프롬프트를 지정함
  • --loop-plan <path>는 사용자 지정 계획 파일 경로를 지정하며, 기본값은 LOOP_PLAN.md임
  • --loop-max <N>은 최대 반복 횟수를 지정하며, 기본값은 제한 없음임
  • --loop-run <cmd>는 각 반복 뒤 실행할 검증 명령을 지정함

Git worktrees 통합

• zerostack은 브랜치별 작업 흐름을 git worktrees로 제공함
• 채팅 UI 안에서 worktree를 만들고, 그 안에서 작업하고, 병합하고, 빠져나올 수 있음
• Git worktrees 통합은 실험적 기능임

• worktree 명령

  • /worktree <name>은 <name> 브랜치에 git worktree를 만들고 그곳으로 이동하며, 이미 존재하면 생성을 건너뜀
  • /wt-merge [branch]는 worktree 브랜치를 [branch]로 병합하고, push하고, 정리한 뒤 메인 저장소로 돌아감
  • /wt-exit은 병합하지 않고 메인 저장소로 돌아감

• 예시 워크플로

  • /worktree feature-x는 새 브랜치와 worktree 디렉터리를 만들고 그곳으로 이동함
  • 이후 zerostack을 평소처럼 사용하면 변경 사항이 feature 브랜치에 남음
  • /wt-merge는 에이전트가 브랜치를 병합하고 push하고 정리한 뒤 메인 저장소로 돌아가게 함
  • /wt-exit은 병합 없이 즉시 메인 저장소로 돌아감

지원 제공자와 라이선스

• 기본 제공자는 OpenRouter임
• OpenAI 호환 제공자로 vLLM, LiteLLM 등을 지원함
• Anthropic, Gemini, Ollama를 지원함
• 사용자 지정 제공자는 $XDG_CONFIG_HOME/zerostack/config.json에서 임의의 base URL과 API 키 환경 변수로 구성할 수 있음
• 라이선스는 GPL-3.0-only임