Agent DX Guide for CLI Projects

A pattern language for designing command-line tools that agents can use effectively.

Core Principles

Minimal Ceremony

One command for the common case.

Bad:

mytool init --config ./config.yaml
mytool start
mytool create entry --type log
mytool entry set-field --field title --value "Fixed bug"
mytool entry commit

Good:

mytool log "Fixed bug" --body "Details..."

Guidelines:

• •Collapse multi-step workflows into single commands
• •Use positional arguments for the most common parameter
• •Provide sensible defaults for everything else
• •Reserve subcommand trees for genuinely distinct operations

Clear Next Action

Tell agents what to do next.

Bad:

$ mytool status
Repository initialized.
3 items tracked.

Good:

$ mytool status
Repository initialized.
3 items tracked.

Run: mytool pending    # See what needs attention
Run: mytool process    # Handle pending items

Patterns:

• •pending / ready commands that surface work
• •Include suggested next commands in output
• •JSON output includes next_action or suggested_commands fields
• •Exit messages guide toward logical next steps

Context Injection

Provide a prime command that outputs workflow state AND guidance for session bootstrapping.

Prime = State + Workflow Guidance, not just State.

$ mytool prime
MyTool workflow context
=======================
Repo: my-project
Branch: main

Pending: 5 items need attention

## Session Protocol
- At session end: run `mytool pending` to check for undocumented work
- Never skip: always log completed work before ending

## Core Rules
- Use CLI commands, not internal files
- Trust --json output over manual parsing

## Quick Commands
  mytool pending     # See pending items
  mytool show --last # View last action

Patterns:

• •--export flag to dump default prime content for customization
• •Override file support (e.g., .mytool/PRIME.md replaces default)
• •Include session close protocol, not just current state
• •Essential rules and quick reference for agent context

Why this matters:

• •Agents lose context on session boundaries
• •/clear and compaction wipe working memory
• •prime restores workflow state AND behavioral guidance in one call

JSON Everywhere

Every command supports --json for structured output.

{
  "status": "created",
  "id": "tb_2026-01-15_abc123",
  "anchor": "abc1234def5678...",
  "commits": 3
}

Guidelines:

• •--json flag on every command, no exceptions
• •Errors also return JSON: {"error": "message", "code": 1}
• •Include machine-readable fields (full SHAs, IDs, counts)

Sensible Defaults

Commands work without flags for the common case.

mytool log "Message"
# Anchor defaults to HEAD
# Range defaults to since-last-entry
# Format defaults to human-readable

• •Defaults should match 80% of use cases
• •Never require configuration before first use

Token Efficiency

Batch Operations

Instead of:

mytool process item1
mytool process item2
mytool process item3
# 3 tool calls, 3 permission prompts

Provide:

mytool process --batch
# 1 tool call, processes all pending

Patterns:

• •--batch flag for processing multiple items
• •Accept multiple positional arguments
• •Batch JSON input via stdin

Compact Output Modes

mytool query --last 5 --oneline   # Compact for scanning
mytool query --last 5 --ids-only  # IDs only for scripting

Allowlist-Friendly Commands

Design commands that can be pre-approved:

• •Prefer declarative over imperative commands
• •Avoid eval/exec patterns
• •Make destructive operations explicit: mytool delete --confirm
• •Support --dry-run for write operations

Time-based Filtering

Consistent temporal queries across commands.

mytool query --since 7d        # Human-readable duration
mytool export --since 24h      # Hours
mytool query --since 2w        # Weeks
mytool export --since 2026-01-15  # Date string
mytool query --range main..HEAD   # Commit range

Patterns:

• •--since for duration-based filtering (24h, 7d, 2w)
• •--range for commit ranges
• •Accept ISO dates as well as relative durations
• •Consistent across query/export/prompt commands

LLM Piping

Provide a prompt command for rendering templates to pipe to LLMs.

Enable mytool <data> | llm "<task>" workflows:

mytool prompt changelog --since 7d | claude
mytool prompt pr-description --range main..HEAD | llm
mytool prompt devblog --last 10 --append "Focus on physics" | claude

Discovery and customization:

mytool prompt --list              # Discover available templates
mytool prompt changelog --show    # Preview template without rendering

Patterns:

• •--list to discover available templates
• •--show to preview template content without rendering
• •--append to add extra instructions dynamically
• •Template resolution order: project-local → user global → built-in
• •Built-in templates for common use cases (changelog, pr-description, exec-summary)

This complements prime (session state) with reusable prompts for common agent tasks.

Error Handling

Structured Errors

{
  "error": "Missing required flag: --why",
  "code": 1,
  "hint": "Use --minor for trivial changes"
}

Exit Codes

Recoverable Failures

Bad:

Error: Entry already exists.

Good:

Error: Entry already exists for anchor abc1234.
Use --replace to overwrite, or --anchor <sha> to target another commit.

Self-Documentation

Help Text with Command Grouping

Group commands by purpose in help output.

$ mytool --help
A development ledger for capturing what/why/how.

Core Commands:
  log       Record work with what/why/how
  pending   Show items needing attention
  status    Show repository state

Query Commands:
  export    Export entries in various formats
  query     Search and filter entries
  show      Display entry details

Agent Commands:
  prime     Output workflow context for agents
  prompt    Render templates for LLM piping
  skill     Output skill documentation

Admin Commands:
  clean     Remove artifacts from scope
  init      Initialize repository

All commands support --json for structured output.

Patterns:

• •Group by purpose: Core, Query, Agent, Admin
• •Helps agents understand command purposes at a glance
• •Consistent ordering across related CLIs

Skill Generation

Provide a command that outputs content for agent skills:

mytool skill
mytool skill --format json

Agent Execution Contract

Include in CLI documentation:

1. •Use CLI, not internals - Call commands, consume JSON output
2. •Trust the tool - Don't parse config files directly
3. •Use --dry-run - Validate before writing
4. •Check pending - Know what needs attention before starting
5. •Prime on session start - Restore context after /clear

Integration Patterns

Provide workflow snippets for CLAUDE.md:

## Workflow

At session start:
  mytool prime

After completing work:
  mytool log "what" --why "why" --how "how"

At session end:
  mytool pending    # Check for undocumented work

Artifact Cleanup

Provide a clean command to remove tool artifacts from a given scope.

mytool clean                  # Remove artifacts from current project
mytool clean --global         # Remove user-level artifacts
mytool clean --dry-run        # Preview what would be removed
mytool clean --force          # Skip confirmation

Patterns:

• •Scope-based cleanup: project, user global, or both
• •--dry-run to preview what would be removed
• •--force to skip confirmation prompts
• •List exactly what will be deleted before proceeding
• •Focus on tool-generated artifacts (caches, state files), not user data

This helps agents understand cleanup options and manage tool state across projects.

Unix Composability

Pipe-Friendly Output

Commands should compose with standard Unix tools.

# Pipe to other CLIs
mytool export --json | jq '.entries[]'
mytool export --json | claude "Summarize this work"

# Use in scripts
for id in $(mytool query --ids-only); do
  mytool show "$id" --json
done

Guidelines:

• •JSON to stdout (not stderr) when --json specified
• •Human-readable to stdout, diagnostics to stderr
• •Support stdin for batch input where sensible
• •Exit codes follow conventions (0=success, 1=user error, 2=system error)

Output Destination Control

Separate stdout behavior from file output.

# To stdout (for piping)
mytool export --json

# To files (for persistence)
mytool export --json --out ./exports/

Don't conflate these—agents need both patterns.

Anti-Patterns to Avoid

Checklist

See references/checklist.md for the full design checklist.