Postal

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

get started view on github

postal: ~/Documents
Demo of Postal running in the terminal

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 & 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 right where you left off.

OpenRouter

Built on OpenRouter. Authenticate once with postal login.

A session, at a glance

Postal streams what it is doing as it goes: reading files, proposing edits, and pausing for approval before anything mutating runs.

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.

read-only

Rejects anything that is not known safe.

Safe

ask

Confirms every mutating tool call.

Default Safe

auto-edit

Edits freely, confirms shell commands.

Safe

on fail

Runs freely and only asks after a failure.

Caution

auto

Runs everything except dangerous commands.

Caution

yolo

Approves everything, including dangerous commands.

Dangerous

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

Getting Started

  1. Install Postal 
    pip install postalcli
  2. Log in

    Authorize with OpenRouter in your browser (or paste an API key manually).

    postal login

    Use postal login --paste to enter an API key directly.

  3. Run it 
    postal                 # interactive mode
    postal "your prompt"   # single-shot mode
    postal --cwd /path     # run against a different directory

Usage

Interactive TUI

Launch the full-screen terminal UI for an interactive session.

postal

Single-Shot Mode

Run a single prompt without the interactive interface.

postal "Refactor the auth module"

Custom Working Directory

Point Postal at a different directory than your current one.

postal --cwd /path/to/project

Account Management

Log out to remove your saved API key.

postal logout

Tooling Architecture

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

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

Network

  • search: Web search via DuckDuckGo
  • fetch: Fetch URL content

Memory

  • memory: Store and retrieve persistent key-value data

MCP

  • Connect to external MCP servers for custom tools and data

Commands

Slash 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

Session Management

  • /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.

View the project on GitHub or install it from PyPI.