Postal

An open-source, terminal-based AI coding agent. It reads your code, calls tools, and helps you build.

pip install postalcli

GitHub · PyPI

Features

Interactive TUI: full-screen terminal interface with streaming responses and real-time tool calls.
Single-shot mode: pass a prompt directly for quick, non-interactive runs.
Built-in tool set: read, write, edit, grep, glob, and run shell commands. Includes a todo plan tool.
Web search and fetch: search the web via DuckDuckGo and fetch URL content.
Persistent memory: store and retrieve key-value memories across sessions.
MCP support: connect to MCP servers for custom tools and data sources.
Sub-agents: specialized agents for codebase investigation, code review, architecture, testing, and debugging.
Approval flow: six approval modes, from strict read-only to full autonomy.
Session management: save sessions, create checkpoints, and resume where you left off.
OpenRouter: built on OpenRouter. Authenticate once with postal login.

Getting started

Install it:

pip install postalcli

postal login

Run it:

postal                 # interactive mode
postal "your prompt"   # single-shot mode
postal --cwd /path     # run against a different directory
postal logout          # remove your saved API key

Approval modes

Every mutating tool call passes through the approval flow first. The mode decides how much Postal asks about, from strictest to most permissive.

Mode	Behavior
`read-only`	Rejects anything that is not known safe.
`ask`	Confirms every mutating tool call. This is the default.
`auto-edit`	Edits freely, confirms shell commands.
`on fail`	Runs freely and only asks after a failure.
`auto`	Runs everything except dangerous commands.
`yolo`	Approves everything, including dangerous commands.

Set it with approval in .postal/config.toml, or switch mid-session with /approval <mode>.

Tools

Core:

read: read file contents with line numbers
write: create or overwrite files
edit: surgical text replacement
grep: regex search across files
glob: find files by pattern
shell: execute shell commands
list_directories: list directory contents
plan: todo list for task tracking
search: web search via DuckDuckGo
fetch: fetch URL content
memory: store and retrieve persistent key-value data

Sub-agents:

codebase_investigator: explore code structure
code_reviewer: review code for bugs and quality
software_architect: write and maintain clean code
test_writer: write tests for edge cases
debugger: find and fix bugs

Postal can also connect to external MCP servers for custom tools and data.

Commands

/help: show help
/exit or /quit: exit the agent
/clear: clear conversation history
/config: show current configuration
/model <name>: change the model
/approval <mode>: change approval mode
/stats: show session statistics
/tools: list available tools
/mcp: show MCP server status
/save: save the current session
/checkpoint [name]: create a checkpoint
/checkpoints: list available checkpoints
/restore <checkpoint_id>: restore a checkpoint
/sessions: list saved sessions
/resume <session_id>: resume a saved session

License

Postal is licensed under the GNU General Public License v3.0.