Codex CLI Integration

How It Works

You talk to Codex. Codex runs Pontius commands. That's it.

The workflow is identical to Claude Code and Gemini CLI. Pontius doesn't care which AI you use—it works with any tool that can execute shell commands.

First-Time Setup

Start Codex CLI in your terminal:

codex

Then ask Codex to set up Pontius:

You: Can you run pontius setup? I want to connect my email.

Codex runs the setup command and gets a step-by-step guide. It will:

Check your license status (and activate if needed)
Walk you through creating an app password for your email provider
Guide you through adding your account in the Pontius TUI
Set up any aliases you send from
Initialize your knowledge base
Create an AGENTS.md file for future sessions

The only thing you type directly is your app password (for security—it goes straight to your system keychain). Codex handles everything else.

Daily Workflow

Once you're set up, just tell Codex to clear your email:

You: Let's clear email.
Codex: Running 'pontius blitz'...
I've loaded your preferences and knowledge base. Running 'pontius list'...
Work Account (3 new):
 UID    FROM                      SUBJECT
 37801  [email protected]      Question about pricing
 37800  [email protected]         Payment received
 37799  [email protected]        Weekly digest
I see:
- 1 customer question → needs response
- 1 billing receipt (Stripe) → moving to billing folder
- 1 newsletter → archiving
Stabilizers on (learning) or auto (autonomous)?

The Three Commands

Same three commands as every other AI integration:

pontius setup

Connects your email accounts. Codex gets a detailed guide and walks you through each step. Run this once per account.

pontius blitz

Starts an email session. This gives Codex your preferences, the full command reference, and points it at your knowledge base.

pontius help

The full command reference. Codex can run this anytime it needs to check syntax or discover features.

The AGENTS.md File

Codex CLI reads from AGENTS.md in your working directory. During setup, create this file to teach Codex how to operate Pontius in future sessions:

AGENTS.md

# Email Assistant
You are my AI email assistant. You operate Pontius on my behalf.
## How Pontius Works
Pontius is a CLI email client designed for AI-first workflows. Three commands matter:
- `pontius setup` - Connect email accounts (run if not configured)
- `pontius blitz` - Start an email session (run when I want to clear email)
- `pontius help` - Full command reference (run anytime you need syntax)
## When I Say "Let's Clear Email"
1. Run `pontius blitz` to load my preferences and the session prompt
2. Run `pontius list` to see my inbox
3. Categorize: noise (archive/move), needs response, needs my input
4. Handle noise autonomously based on my patterns
5. Draft responses for my approval (or send if you know the pattern)
6. Ask about anything you're unsure of
## The Knowledge Base
Location: ~/.config/pontius/knowledge/
This is critical. Before responding to any email, check the relevant folders:
- contacts/ - Who this person is, our relationship, their preferences
- templates/ - My proven responses for common situations
- rules/ - Per-account behavior (Work vs Personal)
- policies/ - Hard rules that override everything
- patterns/ - Triggers for automatic actions
## After Each Email Session
Update the knowledge base with what you learned:
- New contacts → add to contacts/contacts.json
- Repeated responses → create a template
- New patterns → add to patterns/patterns.json
- Corrections I made → update the relevant file
The knowledge base should grow every session. Don't skip this step.
## Accounts
- [email protected] (Work) - Professional tone, check policies
- [email protected] (Personal) - Casual tone
## My Preferences
- Sign off: "Best," followed by my name on a new line
- Default tone: Professional but warm
- Always ask before: Anything financial, customer-facing, or to new contacts
- Archive autonomously: Billing receipts, shipping notifications, newsletters

Put this file wherever you typically start Codex CLI sessions.

Universal Config

AGENTS.md works with multiple AI tools. If you switch between Codex, Gemini, and others, you only need one config file.

Growing the Knowledge Base

The knowledge base at ~/.config/pontius/knowledge/ is what makes Pontius different from stateless AI tools. Every session should leave it smarter than before.

Codex searches it automatically during blitz sessions. After each session, make sure Codex updates it with new contacts, templates, and patterns.

Codex CLI Integration

How It Works

First-Time Setup

Daily Workflow

The Three Commands

pontius setup

pontius blitz

pontius help

The AGENTS.md File

Growing the Knowledge Base

Troubleshooting

Codex Can't Find Pontius

Permission Denied