# wrap, raw and filter

> tokenade wrap runs a command and compacts its output; raw runs it untouched; filter compacts output you already captured.

Source: https://tokenade.net/en/docs/wrap-raw-filter · Updated: 2026-10-07

`tokenade wrap` runs a shell command and returns a compacted version of its output, with the exit code unchanged. It is what your agent's hook calls for every shell command, and you can call it by hand for any agent. `raw` is the escape hatch that runs a command without compaction; `filter` compacts output you captured earlier.

## wrap

```text
tokenade wrap [--shell <posix|powershell|cmd>] [--split-streams] <shell-cmd>
```

Alias: `exec-compact`. Quote the command as one argument: `tokenade wrap 'git log --stat -20'`.

| Flag | Effect |
| --- | --- |
| `--shell posix` | Default. `sh -c` (Git Bash on Windows) |
| `--shell powershell` | `powershell.exe -Command` (or `pwsh`) |
| `--shell cmd` | `cmd.exe /C` |
| `--split-streams` | Compact stdout and stderr separately and return each to its own stream, so redirections behave as without the wrapper. Chronological interleaving is lost |

Without `--shell`, the shell is detected from the environment and falls back to `posix`. Pass it when you wrap a PowerShell or cmd command by hand.

What `wrap` does, in order:

1. Runs the command and captures stdout and stderr together (caps: 16 MB stdout, 4 MB stderr).
2. Redacts secrets.
3. Compacts the output with a compactor that knows that command, or that recognises its format (JSON, logs, diffs, tables and the like).
4. If the result is still large, stashes the complete output on disk and returns a preview with a hash you can query. See [output compaction and the stash](https://tokenade.net/en/docs/compaction).
5. Exits with the inner command's exit code (`128 + signal` when it was killed by a signal).

```text
$ tokenade wrap 'seq 1 20000'
[tokenade:seq] 20000 line(s)
1
2
3
…
19999
20000
[tokenade:seq 85479 tokens folded away; the stash holds the COMPLETE output — this blob is ~85690 tokens — too large to dump whole. recover with `tokenade expand-ref f6351f5ead9a` · `--prompt "q1, q2"` to ask (RAG, several at once) · `--grep <pat>` exact lines. …]
```

```text
$ tokenade wrap 'exit 7'; echo $?
7
```

### Gotcha: stderr is merged

`wrap` merges stderr into stdout before compacting. `tokenade wrap 'cmd' 2>err.log` therefore writes an empty `err.log`. Redirect inside the wrapped command (`tokenade wrap 'cmd 2>err.log'`) or use `--split-streams`.

## raw

```text
tokenade raw <command> [args...]
tokenade raw '<command line>'
```

Aliases: `bypass`, `noproxy`. Runs the command with no compaction and sets `TOKENADE_HOOK_DISABLED=1` so the agent hooks let it through too. Output streams are inherited, the exit code matches the inner command, and nothing is written to the savings ledger.

You usually don't need it. If you already ran a command through Tokenade and need the exact bytes, `tokenade expand-ref <hash>` returns them from the stash instantly, without re-running anything. `raw` is for what the stash can't give you: re-executing without compaction, interactive runs, or debugging a compactor.

For commands whose output folds well (`grep`, `rg`, `ag`, `find`, `ls`, `wc`, `head`, `tail`, `awk`, `sed`, `cat`), `raw` refuses and exits `2`, because re-running would spend the original call's tokens a second time:

```text
$ tokenade raw ls
[tokenade] refusing bypass for `ls` — re-running it would spend the original call's tokens again.
  Most of what you want is already recoverable: `tokenade expand-ref <hash>` …
```

Override with `TOKENADE_FORCE_BYPASS=1 tokenade raw …` when you really need the original stream.

From the 10th bypass within 24 hours (`raw`, or any hook skipped through `TOKENADE_HOOK_DISABLED=1`, counted in `~/.tokenade/bypass-counter`), each bypass prints a one-line reminder on stderr pointing at `expand-ref`. The reminder cannot be silenced.

## filter

```text
<cmd> 2>&1 | tokenade filter <argv...>
```

Compacts stdin as if it had been produced by the command you name. Useful when the output is already captured:

```bash
cargo build 2>&1 | tokenade filter cargo build
cat /tmp/log.txt | tokenade filter git log
```

| Flag | Effect |
| --- | --- |
| `--deliver` | Also run the second stage: stash what is still too big and point back at what was dropped, exactly as `wrap` does |

Without `--deliver`, `filter` applies only the per-command compactor and does not stash. On output that compactor leaves alone it returns the input unchanged where `wrap` would still fold it. `tokenade read -` is different again: it detects the format without a command hint.

## Auto-wrapping in your shell

`tokenade shell-init` prints a shell fragment that routes noisy commands through `tokenade wrap` when stdin is not a terminal, which means for agents, not for you typing at a prompt. It covers the commands Tokenade knows how to compact, limited to what is actually on your `PATH`.

```bash
eval "$(tokenade shell-init)"                 # sh, bash, zsh
tokenade shell-init --shell fish | source      # fish
```

```powershell
Invoke-Expression (& tokenade shell-init --shell powershell | Out-String)
```

Flags: `--shell sh|bash|zsh|fish|powershell|nushell|csh|cmd`, `--all` (skip the `PATH` filter). On csh/tcsh and cmd.exe, aliases go through `tokenade shellwrap`, which passes through at a terminal and wraps otherwise. `tokenade install` sets this up for you; you only need it by hand for an agent Tokenade can't hook.

## Related

- [Output compaction and the stash](https://tokenade.net/en/docs/compaction)
- [Get folded output back](https://tokenade.net/en/docs/expand-ref-disclose)
- [How hooks intercept tool calls](https://tokenade.net/en/docs/hooks)
- [Run scripts with execute](https://tokenade.net/en/docs/execute)
