터미널에 거주하는 오픈소스 AI 코딩 에이전트.
OpenRouter의 모든 모델을 사용하여 코드 계획, 편집, 실행 및 검토를 수행합니다.
Postal는 OpenRouter를 통해 LLM(대규모 언어 모델)에 연결하고, 내장된 도구 세트로 사용자의 코드를 읽고 편집하며, 셸 명령을 실행하고, 전문화된 서브 에이전트에게 위임하며, 전체 화면 TUI(Text User Interface)를 통해 모든 것을 스트리밍합니다. 모든 변경하는 동작은 사용자가 제어하는 승인 정책을 거치므로, 원하는 만큼 자율적이거나 신중할 수 있습니다.
제가 Postal를 만든 이유는 현대 AI 코딩 하네스(harnesses)가 실제로 어떻게 작동하는지 이해하고 싶었기 때문입니다: 에이전트 루프(agent loop), 도구 호출(tool calls), 컨텍스트 관리(context management), 승인(approvals) 등 모델을 코드베이스에서 작업할 수 있는 무언가로 변모시키는 모든 과정 말입니다. 제가 배우고 싶었던 하네스들은 폐쇄형 소스이거나 파이썬 이외의 언어로 작성되어 있었습니다. 저는 이미 즐겨 사용하는 언어로 읽고, 분해하고, 실험해 볼 수 있는 것을 원했습니다.
Postal는 이러한 학습 과정을 모두에게 개방하는 저만의 방식입니다. 코딩 에이전트로 사용할 수도 있고, 조각들이 어떻게 맞물리는지 연구할 수도 있으며, 자신만의 것을 만들 수도 있는 오픈소스 파이썬 프로젝트입니다. 도구를 구축하거나, 서브 에이전트를 추가하거나, 구성 요소를 교체하거나, 인터페이스를 재고하거나, 혹은 그냥 어떤 일이 일어나는지 보기 위해 아이디어를 시도해 보세요.
직접 해킹(hacked)하도록 설계되었습니다. 아키텍처 가이드를 따라가고, 코드에 손을 대고, 자신만의 아이디어로 풍성하게 만드세요. 이 시스템들이 어떻게 작동하는지 배우는 데 도움이 되고, 스스로 무언가를 구축할 장소를 제공하기를 바랍니다.
Postal를 설치하고, OpenRouter를 연결한 다음, 자신의 리포지토리에서 에이전트를 시작하세요:
pip install postalcli
postal login # OpenRouter와 인증하려면 브라우저가 열립니다
postal # 대화형 TUI를 시작합니다
작업을 수행하고 싶은 프로젝트 폴더에서 postal을 실행한 다음, 일반 언어로 작업을 설명하세요. 코드베이스 탐색부터 시작하거나, 계획을 요청하거나, 특정 변경 사항으로 바로 뛰어들 수 있습니다.
이 프로젝트가 어떻게 구성되어 있는지, 그리고 주요 진입점은 어디인지 설명해 보세요.
테스트 실패의 원인을 찾고 수정하세요.
어떤 변경을 가하기 전에 인증 모듈 리팩토링 계획을 세우세요.
...
Postal는 관련 파일을 읽고, 도구를 사용하며, 터미널에 진행 상황을 스트리밍합니다. 액션 승인이 필요할 때에는 실행하기 전에 검토할 수 있습니다. /help를 입력하여 사용 가능한 명령어를 확인하고, /model <이름>으로 모델을 전환하거나, /config로 설정을 검사할 수 있습니다.
단일 작업을 위해 프롬프트를 직접 전달하세요:
postal "이 프로젝트가 어떻게 구성되어 있는지 설명해 주세요"
작업 디렉토리를 선택하거나 저장된 대화로 돌아갈 수도 있습니다:
postal --cwd /path # 다른 작업 디렉토리에서 실행
postal --continue # 이 디렉토리의 마지막 세션 재개
postal --resume 3f2a1c # ID를 사용하여 특정 세션 재개
...
설정은 ~/.config/postal/config.toml에 있으며, 프로젝트별 오버라이드는 .postal/config.toml에서 이루어지고, AGENTS.md는 자동으로 불러옵니다.
전체 CLI 참고 자료 | 설정 참고 자료
| 페이지 | 내용 |
|---|
| CLI reference | 설치, 로그인, 모든 명령어 및 플래그 |
| ... | |
모든 모델을 가져오세요. OpenRouter를 백엔드로 사용한다는 것은 다재다능함을 의미합니다. 하나의 로그인을 통해 대형 모델인 Claude, OpenAI, Deepseek, Kimi는 물론 더 작은 무료 모델에도 접근할 수 있습니다.안전성은 최상위 기능입니다. 6가지 승인 정책, 위험 명령어 거부, 그리고 작업 디렉토리 외부의 모든 것에 대한 확인 절차가 있습니다. 에이전트가 아닌 사용자가 위험 수준을 선택합니다. 'Approvals'를 참조하세요.긴 세션에서도 살아남습니다. 컨텍스트 프루닝(Context pruning)은 오래된 도구 출력에서 토큰을 회수하며, 창이 가득 차면 Postal은 히스토리를 연속성 요약본(continuation brief)으로 압축하여 오류를 내는 대신 계속 진행합니다.터미널을 닫아도 아무것도 사라지지 않습니다. 세션은 매 턴마다 체크포인트가 생성되므로 postal --continue는 사용자가 있던 정확한 곳으로 되돌아가게 하며, /rewind | |
대화의 이전 체크포인트로 되돌아갈 수 있습니다. 세션(Sessions)을 확인하세요.
설정 가능하도록 설계됨. Rich, Click, Pydantic을 기반으로 구축된 읽기 쉬운 객체 지향 Python 코드베이스입니다. 모든 도구는 공유 추상 기본 클래스 뒤에 하나의 클래스로 되어 있어, 도구나 하위 에이전트를 추가하는 것이 작고 잘 표시된 변경 사항만 필요합니다. 아키텍처(Architecture)를 확인하세요.
컴포넌트 기반 UI 디자인. Postal은 시각적 요소(스피너, 거터, 마크다운 렌더링, 도구 표시, 확인 메시지 등) 각각에 대해 별도의 컴포넌트를 사용하는 모듈식, 컴포넌트 기반 UI 시스템을 사용하므로 인터페이스를 유지 관리, 사용자 정의 및 확장하기 쉽습니다.
파일(Files)
read, write, edit, apply_patch, grep, glob, 그리고 list_directories는 코드베이스 작업을 위한 기능입니다. apply_patch는 여러 파일에 걸쳐 생성, 업데이트, 삭제 및 이름 변경을 하나의 모두 성공/실패(all-or-nothing) 호출로 일괄 처리합니다.
| Bash |
The bash 도구는 작업 디렉토리에서 명령어를 실행합니다. 어떤 셸 명령어를 실행해야 할지 자동으로 OS를 감지합니다.
| Planning |
plan 도구는 에이전트 루프 전반에 걸쳐 단계(할 일 목록)를 추적합니다.
네트워크 및 메모리
DuckDuckGo를 통한 웹 검색, URL 가져오기, 그리고 세션 간에 유지되는 키-값 저장소를 제공합니다.
하위 에이전트(Sub-agents)
주요 에이전트가 위임할 수 있는 전문화된 에이전트들: codebase_investigator, code_reviewer, software_architect, test_writer, debugger
MCP
추가 도구 및 데이터 소스를 위해 외부 MCP 서버에 연결합니다.
스킬(Skills)
첫 번째 프롬프트 중에 자동으로 SKILLS.md 파일을 확인하여, 다른 어떤 하네스에서 사용했던 스킬들을 가져올 수 있습니다.
대화형 TUI(Interactive TUI)
Rich를 기반으로 구축된 전체 화면 터미널 인터페이스로, 스트리밍 응답, 실시간 도구 호출 출력, 가시적인 모델 추론 과정, 토큰 사용량 추적 기능을 제공합니다.
단일샷 모드(Single-shot mode)
비대화형 실행을 위해 프롬프트를 인수로 전달할 수 있어 스크립팅에 적합합니다.
| 명령어 | 기능 |
|---|
/help | 모든 명령어 표시 |
/model <이름> | 세션 중간에 모델 전환 |
/approval <모드> | 세션 중간에 승인 정책 전환 |
| `/thinking [on | off |
/clear | 새로운 대화 시작 (이전 내용은 저장됨) |
/config | 활성 구성 보기 |
/stats | 세션 통계: 토큰, 경과 시간, 도구 호출 |
/tools | 사용 가능한 도구 목록 표시 |
/mcp | MCP 서버 상태 표시 |
/sessions [all] | 저장된 세션 목록 (최신순) |
| `/sessions rm <n | id>` |
| `/resume <n | id>` |
/checkpoint [레이블] | 선택적 이름과 함께 체크포인트 저장 |
/checkpoints | 이 세션의 체크포인트 목록 표시 |
| `/rewind <n | id>` |
/exit, /quit | 에이전트 종료 |
입력하는 동안 명령어 자동 완성 기능: / 입력
모든 명령어를 나열하며, 계속 입력할수록 목록이 좁혀지고, ↑/↓를 사용하여 선택한 후 Enter를 누르면 하이라이트된 명령어가 실행됩니다 (Tab 키는 인수를 추가하고 싶을 때 채워줍니다).
Postal은 매 턴마다 대화 내용을 디스크에 작성하므로 터미널을 닫아도 대화가 끊기지 않습니다. 모든 대화는 재개 가능하며, 아래에 표시된 명령어를 실행하여 접근할 수 있습니다.
postal --continue # 이 디렉토리의 가장 최근 세션 재개
postal --resume 3f2a1c # 특정 세션 재개 (ID 접두사만으로 충분)
postal sessions # 이 디렉토리에 저장된 내용 확인
...
TUI(Text User Interface) 내에서 /sessions는 저장된 목록을 보여주고, /resume은 실행 중인 에이전트에 하나를 로드하며, 대화 기록과 토큰 합계가 포함됩니다. 시스템 프롬프트는 복원되지 않습니다. 이는 현재 구성 및 도구 세트로부터 재구성되기 때문이며, 따라서 재개된 세션은 이후에 수행한 모든 모델, 승인 정책 또는 AGENTS.md 변경 사항을 반영합니다.
각 저장(save)은 체크포인트이며, 해당 시점의 대화 전체 스냅샷입니다. 턴(Turns)은 자동으로 체크포인트되며, 위험한 작업을 시도하기 전에 수동으로 /checkpoint <label>을 표시할 수 있습니다:
❯ /checkpoint before the refactor
Saved before the refactor · 24 messages · session 3f2a1c8b
❯ /checkpoints
...
되감기(Rewinding)는 모델이 보는 대화를 대체하며, 이는 방향을 잘못 틀었던 턴에서 빠져나오는 방법이 됩니다. 우회 전으로 되돌아가 다시 시도할 수 있습니다. 이는 대화만 되돌릴 뿐, 파일은 되돌리지 않습니다 — 디스크에 이미 쓰인 것은 그대로 유지됩니다.
세션은 ~/.config/postal/sessions/<id>/에 존재하며, 세션당 하나의 디렉터리에 전사(transcripts)가 JSONL 파일로, 작은 meta.json 파일 옆에 저장됩니다. 오래된 체크포인트는 세션이 max_checkpoints를 초과하면 정리되며 (자동 저장본이 먼저 삭제되고, 이름 지정된 것은 유지됨), 가장 오래된 세션은 max_sessions을 넘으면 삭제됩니다. 대화를 디스크에 전혀 저장하고 싶지 않다면 [session] 아래에 enabled = false로 설정할 수 있습니다.
Postal가 상태를 변경하는 어떤 작업을 실행하기 전에, 승인 정책(approval policy)이 진행 여부를 결정하며, 사용자에게 물어보거나 아예 거부합니다. 읽기 전용 도구(read, grep, glob, list_directories, plan)는 절대 프롬프트를 띄우지 않으므로, 정책은 쓰기 작업, bash 명령어, 네트워크 호출, 메모리 쓰기, MCP 도구 및 서브 에이전트 실행에만 영향을 미칩니다.
| Value | Badge | Behaviour |
|---|
on_request (default) | ask | 모든 변경을 유발하는 도구 호출에 대해 확인합니다. 알려진 안전한 명령어(ls, git status, grep 등)로 일치하는 명령어는 확인 없이 실행됩니다. |
auto_edit | auto-edit | 작업 디렉터리 내의 파일 편집 및 쓰기는 프롬프트 없이 진행되지만, 알려진 안전한 명령어가 아닌 bash 명령어는 여전히 확인이 필요합니다. |
auto | auto | 위험한 명령어를 제외하고 모든 것이 실행됩니다. 위험한 명령어만 거부됩니다. |
on_fail | on fail | 현재 auto와 동일합니다. 실패한 도구 호출 후 프롬프트를 요청하는 용도로 예약되었으나, 아직 구현되지 않았습니다. |
never | read-only | 알려진 안전한 명령어가 아닌 것은 모두 거부합니다. 아무것도 쓰여지지 않으며, 절대로 프롬프트가 표시되지 않습니다. |
yolo | yolo | 위험하다고 분류된 명령어까지 포함하여 모든 것을 승인합니다. 샌드박스나 컨테이너에서만 사용해야 합니다. |
정책 위에 두 가지 규칙이 적용되며, yolo를 제외한 어떤 정책도 이들을 재정의하지 않습니다:
위험한 명령어는 거부됩니다. rm -rf /, dd if=, mkfs, shutdown, curl … | bash, 포크 폭탄(fork bombs) 및 유사 패턴은 bash가 보기 전에 거부됩니다 (전체 목록은 safety/approval.py의 DANGEROUS_PATTERNS에 있습니다).작업 디렉터리 외부 경로를 건드리는 모든 것은 확인됩니다, 정책이 아무리 관대하더라도 (never는 대신 거부합니다).
현재 작업 중인 내용:
병렬 서브 에이전트 (Parallel Subagents) - 서브 에이전트가 다른 서브 에이전트의 인스턴스를 호출하여 더 전문화된 에이전트에게 작업을 위임할 수 있도록 합니다.Git 통합 (Git Integration) - 사용자가 postal을 사용하여 git 명령어를 사용할 수 있게 합니다.추가 자산 (More assets) - 로고, 배너 등
아이디어가 있으신가요? 이슈를 열어주세요. 기능 논의는 언제나 환영합니다.
모든 크기의 기여(오타 수정부터 새로운 도구 및 서브 에이전트까지)가 감사하게 받아들여집니다. 시작하려면 CONTRIBUTING.md를 읽고, 해결할 것이 있는지 확인하려면 열린 이슈를 살펴보세요!
Postal이 유용하다면, 레포지토리에 별점을 주는 것이 프로젝트가 더 많은 개발자에게 도달하는 데 진정으로 도움이 됩니다. ⭐