Claude Code Integration

How It Works

You talk to Claude. Claude runs Pontius commands. That's the whole workflow.

No copying and pasting. No memorizing commands. Just tell Claude what you want, and it handles the rest.

First-Time Setup

Start Claude Code in your terminal:

claude

Then ask Claude to set up Pontius:

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

Claude 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 a CLAUDE.md file for future sessions

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

Daily Workflow

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

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

Claude runs the blitz command to load your knowledge base and preferences, then starts triaging your inbox. You stay in control of how much autonomy to grant.

The Three Commands

Pontius is designed around three commands. You don't need to memorize them—just ask Claude to run them:

pontius setup

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

pontius blitz

Starts an email session. This gives Claude your preferences, the full command reference, and points it at your knowledge base. Say "let's clear email" and Claude knows to run this.

pontius help

The full command reference. Claude can run this anytime it needs to check syntax or discover features. Designed for both humans and AI.

The CLAUDE.md File

During setup, Claude creates a CLAUDE.md file that teaches it how to operate Pontius in future sessions. Here's a solid starting point:

# 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. This is what makes Pontius
smarter over time. 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 Claude Code sessions. Claude reads it automatically and knows how to operate Pontius without being told each time.

Permissions

Claude Code will ask permission to run Pontius commands. You can:

• Approve each command individually
• Approve all pontius commands for the session
• Add Pontius to allowed tools in Claude Code settings

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.

Claude searches it automatically during blitz sessions—finding context about contacts, using your templates, following your rules. But the real magic happens when Claude updates it after each session:

• New person emailed? Add them to contacts with relationship notes
• Wrote a good response? Save it as a template
• Noticed a pattern? Add it so future sessions handle it automatically
• You corrected something? Update the relevant file so it doesn't happen again

After a few weeks, Pontius knows your email world better than you do.

Troubleshooting

Claude Can't Find Pontius

• Ask Claude to check: "Run which pontius"
• If not found, install Pontius first
• Restart Claude Code after installing

Permission Denied

• Approve the command when Claude asks
• Or add pontius to allowed commands in settings

Context Too Long

• Start fresh sessions for new blitzes
• Claude uses pontius list for summaries, pontius read only when needed