Skip to main content
← Back to list
01Issue
FeatureOpenSwamp ClubPublic
AssigneesNone

Relationships

#1977 AI-Friendly CLI Manual Dump

Opened by jeremy_schulman · 9/3/2026

Feature Request: AI-Friendly CLI Manual Dump

Problem Statement

When AI Agents (like Google Antigravity or Claude) interact with the swamp CLI, they frequently hallucinate the exact syntax for commands, flags, and arguments. Because the CLI surface area is large and complex, agents often guess the syntax based on standard POSIX conventions rather than reading the help menus proactively.

This results in an inefficient "trial-and-error" loop where the AI runs a malformed command, encounters a syntax error (e.g., Unknown option), reads the error, runs swamp help <command>, and then finally runs the correct command.

The Cost of Hallucination

By way of example, during a single session building with swamp the AI agent experienced the following CLI syntax hallucinations:

  • swamp model create: The agent used --type and --arg as flags instead of using positional arguments and --global-arg.
  • swamp vault create: The agent omitted the required type positional argument.
  • swamp model method run: The agent frequently guessed the JSON input schemas for custom methods without querying the model definition first.

Estimated Cost Metrics (Single Session):

  • Re-tries: ~5 to 6 failed CLI executions requiring correction loops.
  • Time Wasted: ~3 to 4 minutes of idle time spent waiting for failing terminal commands, reading the errors, and retrying.
  • Token Waste: ~1,500 - 2,000 wasted tokens (roughly $0.05 in API costs per session) generating the bad tool calls, processing the terminal error responses, and running subsequent help lookups.

Across hundreds of developers and thousands of AI sessions per week, this trial-and-error friction creates significant API cost waste and degrades the user experience.

Proposed Solution: swamp dump-manual

We request the addition of a swamp dump-manual (or similar) command.

While swamp help --json currently provides excellent machine-readable schemas for individual commands, AI agents need a way to ingest the entire CLI surface area, including global arguments, model schemas, and vault operations, in a single optimized payload.

Requirements:

  1. Single Execution: Running swamp dump-manual should output a highly-compressed, token-efficient JSON or Markdown representation of every single available command, sub-command, and required argument.
  2. System Prompt Injection: By having this command, developers can include a rule in their .cursorrules or AGY AGENTS.md file that says: "Run swamp dump-manual at the start of the session to learn the CLI." The AI will parse it once and never hallucinate a command again.
  3. Model Awareness: Optionally, if run within a repository, the dump should include the input schemas for all locally registered model methods, preventing the AI from guessing method arguments.

Conclusion

By explicitly catering to AI agents with a one-shot "brain dump" of the CLI capabilities, Swamp will become the most reliable and cost-efficient orchestration tool for agentic workflows.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

9/3/2026, 11:50:00 AM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.