pop: Instructions file for Codex

AGENTS.md

Guide for AI agents working on the Pop codebase.

What is Pop?

Pop is a command-line email client built in Go. It supports two delivery methods — Resend (OAuth or API key) and SMTP — and provides both an interactive TUI (Bubble Tea) and non-interactive CLI sending.

Build & Development Commands

task build       # Build the project
task lint        # Run golangci-lint (strict config in .golangci.yml)
task lint:fix    # Auto-fix lint issues
task vet         # Run go vet
task test        # Run tests
task fmt         # Format code (gofumpt + goimports)
task tidy        # Tidy go modules
task             # Run the project (go run . {{.CLI_ARGS}})

Always run task lint before committing. The linter enables gofumpt and goimports formatters, wrapcheck (errors from external packages must be wrapped with fmt.Errorf("...: %w", err)), goconst (repeated string literals should be constants), gosec, revive, and others.

Architecture

Source Layout

All source files are in the package root (no sub-packages):

• main.go — Root cobra command, flag definitions, delivery method detection, non-interactive send path
• model.go — Bubble Tea TUI model (Model), state machine, view rendering
• keymap.go — TUI key bindings and help
• email.go — Email sending logic (SMTP via go-simple-mail, Resend via resend-go), Markdown-to-HTML conversion (goldmark)
• attachments.go — Attachment list item type and delegate for the TUI
• auth.go — OAuth 2.0 with PKCE: token storage, client registration, token exchange, refresh, callback server
• auth_cli.go — Non-interactive OAuth flow (stdin not a terminal)
• auth_ui.go — Interactive OAuth flow (Bubble Tea TUI with spinner states)
• style.go — Lipgloss styles and charmtone color palette
• skill.go — pop skill command (prints skill definition)
• skill.md — Embedded skill body (via go:embed)
• install_skill.go — pop install-skill command with per-agent subcommands

CLI vs TUI