cli-wrapper

CLI Wrapper

Bridge between AI harness and external CLIs. Captures, documents, optimizes.

Why

Raw CLI help output floods context. A single docker --help = ~3KB. Wrapped digest = ~300 bytes. 10x savings per invocation. Multiply by every CLI the harness calls.

Quick Start

/cli-wrapper wrap <cli-name>           — capture CLI help + build digest
/cli-wrapper invoke <cli-name> <args>  — run command, return compact output
/cli-wrapper audit <cli-name>          — show token savings for this CLI
/cli-wrapper list                      — list all wrapped CLIs
/cli-wrapper unwrap <cli-name>         — remove wrapper, restore raw access

Workflow

1. Wrap a CLI (discovery)

Claude will:

1. Run <cli> --help (and <cli> <subcommand> --help recursively)
2. Parse flag types, defaults, required vs optional
3. Build a compact digest — only what the harness needs to know
4. Save digest to .claude/cli-wrappers/<cli-name>.json
5. Report token savings: raw vs wrapped

2. Invoke via wrapper

Instead of raw CLI calls, the harness uses the wrapper interface:

/cli-wrapper invoke docker ps --filter status=running

The wrapper:

1. Validates flags against the digest (catches typos early)
2. Runs the command
3. Post-processes output (dedup, truncate, format)
4. Returns only essential output to context
5. Logs token metrics

3. Audit savings

/cli-wrapper audit docker

Returns:

CLI WRAPPER AUDIT — docker
===========================
Wrapped:    2026-06-15
Commands:   27 subcommands indexed
Help size:  3.2KB raw → 0.3KB digest (90% savings)
Invocations: 12
Tokens saved: ~18,400
Avg savings:  ~1,533 tokens/call

Digest Format

Each wrapped CLI produces a machine-readable digest:

{
  "name": "docker",
  "version": "27.3.1",
  "wrapped_at": "2026-06-15T10:30:00Z",
  "subcommands": {
    "ps": {
      "description": "List containers",
      "flags": {
        "--all": { "type": "bool", "description": "Show all containers" },
        "--filter": { "type": "string", "description": "Filter output", "repeatable": true },
        "--format": { "type": "string", "description": "Go template" },
        "--quiet": { "type": "bool", "description": "Only IDs" }
      }
    },
    "build": {
      "description": "Build image from Dockerfile",
      "flags": {
        "--tag": { "type": "string", "description": "Name:tag", "repeatable": true },
        "--file": { "type": "string", "description": "Dockerfile path" },
        "--build-arg": { "type": "string", "description": "Build-time var", "repeatable": true },
        "--no-cache": { "type": "bool", "description": "Don't use cache" },
        "--platform": { "type": "string", "description": "Target platform" }
      }
    }
  },
  "global_flags": {
    "--config": { "type": "string", "description": "Config file location" },
    "--context": { "type": "string", "description": "Docker context" },
    "--debug": { "type": "bool", "description": "Debug mode" },
    "--host": { "type": "string", "description": "Daemon socket" },
    "--log-level": { "type": "string", "description": "Log level", "choices": ["debug", "info", "warn", "error"] }
  },
  "stats": {
    "help_raw_bytes": 3247,
    "digest_bytes": 312,
    "savings_pct": 90.4
  }
}

Token Savings — How It Works

Phase	Without Wrapper	With Wrapper
Discovery	Run cmd --help each session → 3KB tokens	Load digest → 0.3KB tokens
Validation	Harness guesses flags → retries	Digest validates → first try
Output	Raw output → possibly 10KB+	Post-processed → essential only
Documentation	Harness re-discovers each time	Digest persists across sessions

Supported CLI Patterns

Works with any CLI that supports --help:

• Posix-style: command --help, command subcommand --help
• Subcommand trees: git, docker, kubectl, aws, gcloud
• Single-binary tools: ffmpeg, curl, jq, gh
• Node/npm tools: npx, pnpm, bun

Post-Processing Rules

To minimize context bloat, the wrapper applies:

1. Dedup: remove repeated lines (stack traces, warnings)
2. Truncate: cap output at 500 lines by default (--max-lines overrides)
3. Filter: strip ANSI escape codes, progress bars, spinners
4. Summarize: for known CLIs, extract structured summary (e.g., docker ps → table of container names + status only)

Files

• .claude/cli-wrappers/<name>.json — digest (machine-readable)
• .claude/cli-wrappers/<name>.md — human-readable reference (optional)

Example Session

User: /cli-wrapper wrap gh
Claude:
  Running gh --help … 2.1KB
  Running gh issue --help … 1.8KB
  Running gh pr --help … 2.4KB
  Running gh repo --help … 1.6KB

  ✓ gh wrapped — 4 subcommands, 47 flags indexed
  Digest: 0.4KB (94% savings vs 7.9KB raw)
  Saved to .claude/cli-wrappers/gh.json

User: /cli-wrapper invoke gh issue list --state open --limit 5
Claude: [validates flags ✓] [runs command] [output: 5 issues, compact table]
  Tokens used: 142 (vs ~800 raw — 82% savings)