# Caveman Wrap Command-Line Options: How to Configure Agent Sessions with Flags > Learn Caveman wrap command-line options to configure agent sessions with flags like --off --pixel --workflow and --full-auto. Control your agent's behavior efficiently. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: how-to-guide - Published: 2026-09-06 --- **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`](https://github.com/JuliusBrussee/caveman/blob/main/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. ```bash caveman wrap [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. ```bash caveman wrap --off codex ``` This flag cannot be combined with `--pixel`. The parser at [CLI source line ≈4901](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/src/index.ts#L4901) 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. ```bash 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](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/src/index.ts#L4901) of [`packages/cli/src/index.ts`](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/src/index.ts). ### `--workflow `: 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. ```bash 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](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/src/index.ts#L4922). ### `--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. ```bash caveman wrap --full-auto codex ``` Per the [agent-wrapping documentation](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/agent-wrapping.md#full-auto-example), 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`](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/src/index.ts) handles these checks before proxy injection occurs. --- ## Practical Usage Examples Run a standard wrapped Claude session: ```bash caveman wrap claude ``` Meter raw traffic from an OpenCode session: ```bash caveman wrap --off opencode ``` Generate pixel-dense output for Gemini Vision with workflow tagging: ```bash caveman wrap --pixel --workflow gemini-vision-task gemini ``` Wrap an arbitrary script with proxy injection: ```bash 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`](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/src/index.ts)** — Implements `caveman wrap`, flag parsing, proxy injection, and validation logic - **[`docs/technical/cli-reference.md`](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/cli-reference.md)** — Official CLI documentation with complete usage tables - **[`docs/technical/agent-wrapping.md`](https://github.com/JuliusBrussee/caveman/blob/main/docs/technical/agent-wrapping.md)** — Architecture overview and agent-specific wrapper behaviors - **[`agents/profiles/schema.json`](https://github.com/JuliusBrussee/caveman/blob/main/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 `** 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/schema.json), `--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](https://github.com/JuliusBrussee/caveman/blob/main/packages/cli/src/index.ts#L4922) before any proxy connection is established.