Caveman Wrap Command-Line Options: How to Configure Agent Sessions with Flags

The caveman wrap command accepts four primary flags (--off, --pixel, --workflow, --full-auto) plus positional arguments passed through to the agent binary.

Caveman provides a lightweight proxy wrapper for LLM-coding agents, and the wrap subcommand is the standard entry point for running single sessions without persisting configuration changes. According to the Caveman source code, all flag validation and argument forwarding are implemented in packages/cli/src/index.ts.

---

Core Command Structure

The caveman wrap command requires an agent identifier as the first positional argument. Everything after the agent name is forwarded unchanged to that agent's binary.

caveman wrap <agent> [args...]

If the supplied identifier is not a known agent, Caveman falls back to "wrap any command" mode and injects the proxy into the arbitrary command.

---

Available Command-Line Flags

--off: Byte-Identical Local Metering

The --off flag runs the wrapped session with byte-identical local metering only, bypassing compression and pixel rendering. Use this when you need raw traffic recording without processing overhead.

caveman wrap --off codex

This flag cannot be combined with --pixel. The parser at CLI source line ≈4901 throws a usage error if both are supplied.

--pixel: Vision-Model Output Rendering

The --pixel flag renders agent output as dense text optimized for vision models such as Gemini Vision. This produces compact, pixel-friendly representations suitable for multimodal LLMs.

caveman wrap --pixel gemini

Like --off, this is mutually exclusive with its counterpart. The validation logic resides in the same parser block around line 4901 of packages/cli/src/index.ts.

--workflow <slug>: Session Tagging for Analytics

The --workflow flag attaches a workflow identifier to the session for spend tracking in Caveman Cloud. The slug must match the pattern: lower-case letters, digits, and dashes only, maximum 96 characters.

caveman wrap --workflow review opencode

Workflow slugs appear in dashboards to categorize and filter session costs. The workflow validation is handled at CLI source line ≈4922.

--full-auto: Maximum Automation Shortcut

The --full-auto flag is an agent-specific shortcut that enables all available automatic behaviors for supported agents. Agents like Codex expose this as a convenience over toggling individual automation flags.

caveman wrap --full-auto codex

Per the agent-wrapping documentation, this is not universal—availability depends on the agent profile.

---

Flag Compatibility and Validation Rules

Caveman enforces strict compatibility rules that trigger usage errors at parse time:

Combination	Result
--off + --pixel	Error: mutually exclusive
--workflow without valid slug	Error: validation fails
--full-auto with unsupported agent	Warning or no-op (agent-dependent)

The parser in packages/cli/src/index.ts handles these checks before proxy injection occurs.

---

Practical Usage Examples

Run a standard wrapped Claude session:

caveman wrap claude

Meter raw traffic from an OpenCode session:

caveman wrap --off opencode

Generate pixel-dense output for Gemini Vision with workflow tagging:

caveman wrap --pixel --workflow gemini-vision-task gemini

Wrap an arbitrary script with proxy injection:

caveman wrap my-script.sh --some-flag value

---

Key Source Files

Understanding where these features are implemented helps with debugging and extending Caveman:

• packages/cli/src/index.ts — Implements caveman wrap, flag parsing, proxy injection, and validation logic
• docs/technical/cli-reference.md — Official CLI documentation with complete usage tables
• docs/technical/agent-wrapping.md — Architecture overview and agent-specific wrapper behaviors
• agents/profiles/schema.json — Agent profile schema defining supported flags per agent

---

Summary

• caveman wrap requires an agent identifier and forwards remaining arguments to the underlying binary
• --off enables raw metering without compression or rendering
• --pixel produces vision-model-optimized dense text output
• --workflow <slug> tags sessions for Caveman Cloud spend analytics
• --full-auto activates all automation features for compatible agents
• Flag conflicts are caught early in packages/cli/src/index.ts before proxy startup

---

Frequently Asked Questions

Can I use --off and --pixel together in the same command?

No. These flags are mutually exclusive. The parser in packages/cli/src/index.ts validates this combination and prints a usage error if both are present.

What happens if I specify an unknown agent name?

Caveman falls back to "wrap any command" mode. The proxy is still injected, but no agent-specific shortcuts or profiles are applied. Everything after the first argument is executed as a shell command.

Is --auto-recall available in the current CLI release?

No. According to the agent profile schema, --auto-recall is defined as a future flag for enabling automatic snippet recall via the Caveman Mem hook, but it is not yet exposed in the CLI interface.

Are workflow slugs validated before the session starts?

Yes. The CLI validates that workflow slugs contain only lower-case letters, digits, and dashes, with a maximum length of 96 characters. Invalid slugs trigger an error at CLI source line ≈4922 before any proxy connection is established.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}