Postal

An open-source AI coding agent that lives in your terminal.
Plans, edits, runs, and reviews code with any model on OpenRouter.

Postal connects to LLMs through OpenRouter, reads and edits your code with a built-in tool set, runs shell commands, delegates to specialized sub-agents, and streams everything through a full-screen TUI. Every mutating action goes through an approval policy you control, so it is as autonomous or as careful as you want it to be.

Quickstart ↴

Two commands and you are talking to an agent in your own repo:

pip install postalcli
postal login    # opens your browser to authorize with OpenRouter
postal          # start the interactive TUI

More ways to run it:

postal "your prompt"     # single-shot mode, great for scripting
postal --cwd /path       # run against a different working directory
postal --continue        # pick up the last session in this directory
postal --resume 3f2a1c   # resume a specific session by id
postal sessions          # list saved sessions

Configuration lives in ~/.config/postal/config.toml, with per-project overrides in .postal/config.toml, and AGENTS.md is picked up automatically.

Full CLI reference | configuration reference

Documentation

Why Postal?

• Bring any model. OpenRouter as the backend means versatility. One login gives you large models Claude, OpenAI, Deepseek, Kimi, and even access to smaller free models.
• Safety is a first-class feature. Six approval policies, dangerous-command rejection, and confirmation for anything outside the working directory. You choose the risk level, not the agent. See Approvals.
• It survives long sessions. Context pruning reclaims tokens from stale tool output, and when the window fills up, Postal compacts history into a continuation brief and keeps going instead of erroring out.
• Nothing is lost when you close the terminal. Sessions are checkpointed after every turn, so postal --continue puts you back exactly where you were, and /rewind walks the conversation back to any earlier checkpoint. See Sessions.
• Configurable by design. A readable, object-oriented Python codebase built on Rich, Click, and Pydantic. Every tool is one class behind a shared abstract base, so adding a tool or a sub-agent is a small, well-marked change. See Architecture.
• Component-based UI design. Postal uses a modular, component-based UI system with separate components for every visual element (spinners, gutters, markdown rendering, tool displays, confirmations, etc.), making it easy to maintain, customize, and extend the interface.

What it can do

Slash commands

Commands autocomplete as you type: hitting / lists every command, the list narrows as you keep typing, and ↑/↓ select while Enter runs the highlighted one (Tab fills it in if you want to add arguments first).

Sessions

Postal writes the conversation to disk after every turn, so closing the terminal does not kill your conversation. All conversations are resumable and can be accessed by running a command shown below.

postal --continue        # resume the most recent session in this directory
postal --resume 3f2a1c   # resume a specific session (a prefix of the id is enough)
postal sessions          # what is saved for this directory
postal sessions --all    # every directory
postal sessions rm 3f2a1c

Inside the TUI, /sessions lists what is saved and /resume loads one into the running agent, transcript and token totals included. The system prompt is not restored: it is rebuilt from the current config and tool set, so a resumed session picks up any model, approval, or AGENTS.md changes you have made since.

Checkpoints

Each save is a checkpoint, a full snapshot of the conversation at that point. Turns are checkpointed automatically, and /checkpoint <label> marks one by hand before you try something risky:

❯ /checkpoint before the refactor
Saved before the refactor · 24 messages · session 3f2a1c8b

❯ /checkpoints
1  a41f9c02  turn 3                 18 msgs  22m ago
2  7d2b1e55  turn 4                 24 msgs  4m ago
3  e0c34a91  before the refactor    24 msgs  just now

❯ /rewind 1
Rewound to turn 3 · 18 messages · turn 3

Rewinding replaces the conversation the model sees, which makes it the way out of a turn that went sideways: roll back to before the detour and take another run at it. It only rewinds the conversation, not your files — anything already written to disk stays written.

Sessions live in ~/.config/postal/sessions/<id>/, one directory per session, with the transcripts in a JSONL file next to a small meta.json. Old checkpoints are trimmed once a session passes max_checkpoints (autosaves go first, named ones are kept), and the oldest sessions are dropped past max_sessions. Set enabled = false under [session] to keep conversations off disk entirely.

Approvals

Before Postal runs anything that changes state, the approval policy decides whether it goes ahead, asks you, or is refused outright. Read-only tools (read, grep, glob, list_directories, plan) never prompt, so a policy only affects writes, bash commands, network calls, memory writes, MCP tools, and sub-agent runs.

Two rules apply on top of the policy, and no policy except yolo overrides them:

• Dangerous commands are rejected. rm -rf /, dd if=, mkfs, shutdown, curl … | bash, fork bombs, and similar patterns are refused before bash ever sees them (the full list is DANGEROUS_PATTERNS in safety/approval.py).
• Anything touching a path outside the working directory is confirmed, however permissive the policy is (never rejects it instead).

Roadmap

Currently being worked on:

• Parallel Subagents - allows sub-agents to call instances of other sub-agents to delegate more work to specialized agents.
• Git Integration - allows users to use git commands with postal.
• More assets - Logo, banner, etc

Have an idea? Open an issue, feature discussions are very welcome.

Contributing

Contributions of every size are appreciated, from typo fixes to new tools and sub-agents. Read CONTRIBUTING.md to get started, and check the open issues for something to pick up!

If Postal is useful to you, a star on the repo genuinely helps the project reach more developers. ⭐

License

GNU GENERAL PUBLIC LICENSE v3.0