sources/bespoke-cli-for-agents-pattern.md

Summary

This source captures a practical operating pattern: when an agent repeatedly works against noisy, oversized, or awkward sources, it is often better to give it a thin purpose-built CLI plus a companion skill than to keep handing it raw source material or generic connector output.

The durable point is not merely "build more tools." It is that agents perform especially well when the interface is command-shaped: explicit arguments, stable JSON, predictable errors, help text, and safe approval boundaries. Access alone is not enough; the interface needs to fit how the agent actually operates.

Key points

  • Connectors and MCP servers solve the access problem, but they do not automatically solve the composability problem.
  • Repeated agent workflows often improve when the raw source is reshaped into a narrow command surface with flags, exact reads, search, pagination, and file output.
  • A companion skill matters almost as much as the CLI itself. The skill teaches future runs which commands to start with, how to keep output small, and which actions require approval.
  • The command shape fits native agent strengths: inspect --help, search, narrow, retry, pipe output, write full artifacts to a file, then compose the next command from the last result.
  • Good agent-facing CLIs should expose:
    • stable command surface
    • JSON output or a reliable machine mode
    • predictable errors
    • small focused verbs per workflow
    • exact read-by-ID behavior
    • clear write boundaries and safety defaults

Concrete examples from the source material

1. codex-threads

A local searchable index over old Codex sessions. The use case is not just retrieval for retrieval's sake; it is pattern extraction. Old high-quality sessions can be searched, resolved, read, and turned into reusable skills.

2. slack-cli

A thin command surface for Slack search, permalink resolution, thread reads, and local context retrieval. It does not expand permissions; it reshapes the same access model into a form an agent can compose repeatedly.

3. typefully-cli

A small CLI over a handful of high-value social drafting operations. The crucial detail is the companion rule layer: draft by default, use structured body files when needed, and never publish/schedule/delete unless explicitly requested.

Why it matters

This pattern reinforces several wiki-level beliefs:

  • interface design is part of the agent system, not a cosmetic wrapper
  • narrow command surfaces can outperform generic access surfaces for repeated work
  • skills are durable operating memory for tool use, not just documentation
  • safe defaults belong in the interface layer rather than being re-explained every run

It is also a useful counterweight to the idea that bigger context windows alone eliminate tool/interface design. Even if raw-context handling improves, repeated work still benefits from cleaner retrieval, deterministic formatting, and approval-aware commands.

Risks and constraints

  • This can become over-tooling if every small task gets its own wrapper.
  • A bad CLI can simply freeze bad assumptions into a brittle interface.
  • There is a maintenance cost: auth, output contracts, docs, installation, and drift control all matter.
  • This pattern is strongest where the source is reused often, not where the task is genuinely one-off.
  • It is not a replacement for connectors/MCP; it is often a layer beside them.

Implications

For this wiki, the main implication is a practical doctrine:

If an agent keeps revisiting the same messy source, the right move may be to stop explaining the source and start compiling an agent-native interface to it.

That pushes the system toward command-shaped retrieval and action surfaces, backed by skills that encode defaults and approval rules.

Open questions

  • Where is the threshold where a repeated workflow deserves a bespoke CLI rather than direct plugin/MCP access?
  • Which recurring surfaces in our own environment would benefit most from a CLI + skill wrapper?
  • How should we evaluate whether a bespoke CLI reduces token usage, improves determinism, or improves output quality enough to justify maintenance?

Sources

  • Dotey summary post: https://x.com/dotey/status/2042777337398210713
  • Nick Baumann post: https://x.com/nickbaumann_/status/2042705384306336083
  • OpenAI Codex use case: https://developers.openai.com/codex/use-cases/agent-friendly-clis