High-performance CLI proxy that reduces LLM token consumption by 60-90%
Website • Install • Troubleshooting • Architecture
bdo filters and compresses command outputs before they reach your LLM context. Single Rust binary, 100+ supported commands, <10ms overhead.
| Operation | Frequency | Standard | bdo | Savings |
|---|---|---|---|---|
ls / tree |
10x | 2,000 | 400 | -80% |
cat / read |
20x | 40,000 | 12,000 | -70% |
grep / rg |
8x | 16,000 | 3,200 | -80% |
git status |
10x | 3,000 | 600 | -80% |
git diff |
5x | 10,000 | 2,500 | -75% |
git log |
5x | 2,500 | 500 | -80% |
git add/commit/push |
8x | 1,600 | 120 | -92% |
cargo test / npm test |
5x | 25,000 | 2,500 | -90% |
ruff check |
3x | 3,000 | 600 | -80% |
pytest |
4x | 8,000 | 800 | -90% |
go test |
3x | 6,000 | 600 | -90% |
docker ps |
3x | 900 | 180 | -80% |
| Total | ~118,000 | ~23,900 | -80% |
Estimates based on medium-sized TypeScript/Rust projects. Actual savings vary by project size.
brew tap tedorigawa001/tap && brew install bdocurl -fsSL https://raw.githubusercontent.com/tedorigawa001/TokenReductionTool/refs/heads/master/install.sh | shInstalls to
~/.local/bin. Add to PATH if needed:echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc
cargo install --git https://github.com/tedorigawa001/TokenReductionToolDownload from releases:
- macOS:
bdo-x86_64-apple-darwin.tar.gz/bdo-aarch64-apple-darwin.tar.gz - Linux:
bdo-x86_64-unknown-linux-musl.tar.gz/bdo-aarch64-unknown-linux-gnu.tar.gz - Windows:
bdo-x86_64-pc-windows-msvc.zip
Windows users: Extract the zip and place
bdo.exesomewhere in your PATH (e.g.C:\Users\<you>\.local\bin). Run Bushido from Command Prompt, PowerShell, or Windows Terminal — do not double-click the.exe(it will flash and close). For the best experience, use WSL where the full hook system works natively. See Windows setup below for details.
bdo --version # Should show "bdo 0.43.0"
bdo gain # Should show token savings stats# 1. Install for your AI tool
bdo init -g # Claude Code / Copilot (default)
bdo init -g --gemini # Gemini CLI
bdo init -g --codex # Codex (OpenAI)
bdo init -g --agent cursor # Cursor
bdo init -g --agent windsurf # Windsurf
bdo init --agent cline # Cline / Roo Code
bdo init --agent kilocode # Kilo Code
bdo init --agent antigravity # Google Antigravity
bdo init -g --agent pi # Pi
bdo init --agent hermes # Hermes
# 2. Restart your AI tool, then test
git status # Automatically rewritten to bdo git statusHook-based agents rewrite Bash commands (e.g., git status -> bdo git status) before execution. Plugin-based agents, including Hermes, use their plugin API to rewrite commands before execution. The agent receives compact output without needing to call bdo explicitly.
Important: the hook only runs on Bash tool calls. Claude Code built-in tools like Read, Grep, and Glob do not pass through the Bash hook, so they are not auto-rewritten. To get Bushido's compact output for those workflows, use shell commands (cat/head/tail, rg/grep, find) or call bdo read, bdo grep, or bdo find directly.
Without bdo: With bdo:
Claude --git status--> shell --> git Claude --git status--> Bushido --> git
^ | ^ | |
| ~2,000 tokens (raw) | | ~200 tokens | filter |
+-----------------------------------+ +------- (filtered) ---+----------+
Four strategies applied per command type:
- Smart Filtering - Removes noise (comments, whitespace, boilerplate)
- Grouping - Aggregates similar items (files by directory, errors by type)
- Truncation - Keeps relevant context, cuts redundancy
- Deduplication - Collapses repeated log lines with counts
bdo ls . # Token-optimized directory tree
bdo read file.rs # Auto: light cleanup, smart truncation for large source files
bdo read file.rs -l none # Full content when exact text matters
bdo read file.rs -l aggressive # Heavier cleanup (drops more boilerplate)
bdo read file.rs -l outline # Signatures only — every fn/struct/trait, bodies elided
bdo map src/ # Repo map: top-level signatures of every file under a dir
bdo smart file.rs # 2-line heuristic code summary
bdo find "*.rs" . # Compact find results
bdo grep "pattern" . # Grouped search results
bdo diff file1 file2 # Condensed difffind/grep always print the true total and a +N more — use --all … line
when the display is capped, so matches are never dropped silently; --all
lifts every cap (the result count and grep's per-file cap).
Get the API surface of an entire directory in one shot — every file's top-level declarations, function bodies elided. Ideal for onboarding an agent to a new codebase without reading (and paying for) every file.
$ bdo map src/core
runner.rs
pub fn run(cmd: Command, tool_name: &str, args_display: &str, mode: RunMode<'_>, opts: RunOptions<'_>) -> Result<i32> { … }
pub struct RunOptions<'a> { … }
pub enum RunMode<'a> { … }
stream.rs
pub trait StreamFilter { … }
pub fn run_streaming(cmd: &mut Command, stdin_mode: StdinMode, stdout_mode: FilterMode<'_>) -> Result<StreamResult> { … }
…
— 16 files, 245 signatures (full source: 9,188 lines)On this repo that's ~74,000 tokens of source rendered in ~3,500 (≈95%
reduction) with the complete top-level API intact. Supports Rust, Go, JS/TS, C,
C++, Java, and Python; respects .gitignore.
bdo map --changed narrows the map to the git change set (add
--against origin/main for the whole-branch diff) — the API surface you touched,
ideal alongside bdo review.
For Python, function bodies are elided with a … marker (the analogue of
{ … }), async def is handled like def, and multi-line signatures are
folded onto one line:
async def run(task: Task, retries: int = 3) -> Result: …
class Config: …A one-shot summary of a change set for human + agent review — what you'd
otherwise assemble by hand from git status, rg, and cargo test:
$ bdo review # working-tree changes (default)
$ bdo review --against origin/main # whole-branch diff vs a ref
bdo review — 3 changed file(s) (uncommitted)
CHANGED
M src/core/filter.rs
?? src/cmds/system/review.rs
⚠ ARTIFACTS (0)
✓ none
⚠ STALE MARKERS (1) — verify before commit
scripts/x.sh:27 broken install URL (blob serves HTML)
🧪 SUGGESTED TESTS
cargo test -- filter reviewIt flags stray build artifacts (__pycache__, target/, .bak …), high-signal
stale markers (legacy names, broken install URLs), and the inline test modules
worth running for the changed Rust files.
Where bdo review checks the change set, bdo stale audits the whole tracked
tree for residue — generated artifacts that slipped into git and high-signal
stale strings (legacy names, broken install URLs) — and exits non-zero when any
are found, so it can gate CI:
$ bdo stale # whole repo (or: bdo stale <path>)
bdo stale — scanned 312 tracked files
⚠ TRACKED ARTIFACTS (0)
✓ none
⚠ STALE MARKERS (1)
scripts/x.sh:27 broken install URL (blob serves HTML)
✗ 1 residue item(s) foundAdd a .bdostaleignore (gitignore-style globs) for files that legitimately
document residue — a changelog or rename ledger — so they aren't flagged.
bdo git status # Compact status
bdo git log -n 10 # One-line commits
bdo git diff # Condensed diff
bdo git add # -> "ok"
bdo git commit -m "msg" # -> "ok abc1234"
bdo git push # -> "ok main"
bdo git pull # -> "ok 3 files +10 -2"bdo gh pr list # Compact PR listing
bdo gh pr view 42 # PR details + checks
bdo gh issue list # Compact issue listing
bdo gh run list # Workflow run statusbdo jest # Jest compact (failures only)
bdo vitest # Vitest compact (failures only)
bdo playwright test # E2E results (failures only)
bdo pytest # Python tests (-90%)
bdo go test # Go tests (NDJSON, -90%)
bdo cargo test # Cargo tests (-90%)
bdo rake test # Ruby minitest (-90%)
bdo rspec # RSpec tests (JSON, -60%+)
bdo err <cmd> # Filter errors only from any command
bdo test <cmd> # Generic test wrapper - failures only (-90%)
bdo test --changed # Run only tests for changed Rust files (+ --against <ref>)bdo test --changed derives cargo test -- <stems> from the git change set
(file stem = inline test module, e.g. src/core/outline.rs → outline) and
runs just those, failures-only — pairs with bdo review/bdo map --changed.
bdo lint # ESLint grouped by rule/file
bdo lint biome # Supports other linters
bdo tsc # TypeScript errors grouped by file
bdo next build # Next.js build compact
bdo prettier --check . # Files needing formatting
bdo cargo build # Cargo build (-80%)
bdo cargo clippy # Cargo clippy (-80%)
bdo ruff check # Python linting (JSON, -80%)
bdo golangci-lint run # Go linting (JSON, -85%)
bdo rubocop # Ruby linting (JSON, -60%+)bdo pnpm list # Compact dependency tree
bdo pip list # Python packages (auto-detect uv)
bdo pip outdated # Outdated packages
bdo bundle install # Ruby gems (strip Using lines)
bdo prisma generate # Schema generation (no ASCII art)bdo aws sts get-caller-identity # One-line identity
bdo aws ec2 describe-instances # Compact instance list
bdo aws lambda list-functions # Name/runtime/memory (strips secrets)
bdo aws logs get-log-events # Timestamped messages only
bdo aws cloudformation describe-stack-events # Failures first
bdo aws dynamodb scan # Unwraps type annotations
bdo aws iam list-roles # Strips policy documents
bdo aws s3 ls # Truncated with tee recoverybdo docker ps # Compact container list
bdo docker images # Compact image list
bdo docker logs <container> # Deduplicated logs
bdo docker compose ps # Compose services
bdo kubectl pods # Compact pod list
bdo kubectl logs <pod> # Deduplicated logs
bdo kubectl services # Compact service listbdo json config.json # Structure without values
bdo deps # Dependencies summary
bdo env -f AWS # Filtered env vars
bdo log app.log # Deduplicated logs
bdo curl <url> # Truncate + save full output
bdo wget <url> # Download, strip progress bars
bdo summary <long command> # Heuristic summary
bdo proxy <command> # Raw passthrough + trackingbdo gain # Summary stats
bdo gain --graph # ASCII graph (last 30 days)
bdo gain --history # Recent command history
bdo gain --daily # Day-by-day breakdown
bdo gain --all --format json # JSON export for dashboards
bdo discover # Find missed savings opportunities
bdo discover --all --since 7 # All projects, last 7 days
bdo session # Show Bushido adoption across recent sessions-u, --ultra-compact # ASCII icons, inline format (extra token savings)
-v, --verbose # Increase verbosity (-v, -vv, -vvv)Directory listing:
# ls -la (45 lines, ~800 tokens) # bdo ls (12 lines, ~150 tokens)
drwxr-xr-x 15 user staff 480 ... my-project/
-rw-r--r-- 1 user staff 1234 ... +-- src/ (8 files)
... | +-- main.rs
+-- Cargo.toml
Git operations:
# git push (15 lines, ~200 tokens) # bdo git push (1 line, ~10 tokens)
Enumerating objects: 5, done. ok main
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
...
Test output:
# cargo test (200+ lines on failure) # bdo test cargo test (~20 lines)
running 15 tests FAILED: 2/15 tests
test utils::test_parse ... ok test_edge_case: assertion failed
test utils::test_format ... ok test_overflow: panic at utils.rs:18
...
The most effective way to use Bushido. The hook transparently intercepts Bash commands and rewrites them to bdo equivalents before execution.
Result: 100% bdo adoption across all conversations and subagents, zero token overhead.
Scope note: this only applies to Bash tool calls. Claude Code built-in tools such as Read, Grep, and Glob bypass the hook, so use shell commands or explicit bdo commands when you want Bushido filtering there.
bdo init -g # Install hook + Bushido.md (recommended)
bdo init -g --opencode # OpenCode plugin (instead of Claude Code)
bdo init -g --auto-patch # Non-interactive (CI/CD)
bdo init -g --hook-only # Hook only, no Bushido.md
bdo init --show # Verify installationAfter install, restart Claude Code.
Bushido works on Windows with some limitations. The auto-rewrite hook (bdo hook) requires a Unix shell, so on native Windows Bushido falls back to CLAUDE.md injection mode — your AI assistant receives Bushido instructions but commands are not rewritten automatically.
For the best experience, use WSL (Windows Subsystem for Linux). Inside WSL, Bushido works exactly like Linux — full hook support, auto-rewrite, everything:
# Inside WSL
curl -fsSL https://raw.githubusercontent.com/tedorigawa001/TokenReductionTool/refs/heads/master/install.sh | sh
bdo init -gOn native Windows (cmd.exe / PowerShell), Bushido filters work but the hook does not auto-rewrite commands:
# 1. Download and extract bdo-x86_64-pc-windows-msvc.zip from releases
# 2. Add bdo.exe to your PATH
# 3. Initialize (falls back to CLAUDE.md injection)
bdo init -g
# 4. Use bdo explicitly
bdo cargo test
bdo git statusImportant: Do not double-click bdo.exe — it is a CLI tool that prints usage and exits immediately. Always run it from a terminal (Command Prompt, PowerShell, or Windows Terminal).
| Feature | WSL | Native Windows |
|---|---|---|
| Filters (cargo, git, etc.) | Full | Full |
| Auto-rewrite hook | Yes | No (CLAUDE.md fallback) |
bdo init -g |
Hook mode | CLAUDE.md mode |
bdo gain / analytics |
Full | Full |
Bushido supports 14 AI coding tools. Each integration rewrites shell commands to bdo equivalents for 60-90% token savings where the agent supports command interception.
| Tool | Install | Method |
|---|---|---|
| Claude Code | bdo init -g |
PreToolUse hook (bash) |
| GitHub Copilot (VS Code) | bdo init -g --copilot |
PreToolUse hook — transparent rewrite |
| GitHub Copilot CLI | bdo init -g --copilot |
PreToolUse deny-with-suggestion (CLI limitation) |
| Cursor | bdo init -g --agent cursor |
preToolUse hook (hooks.json) |
| Gemini CLI | bdo init -g --gemini |
BeforeTool hook |
| Codex | bdo init -g --codex |
AGENTS.md + Bushido.md instructions |
| Windsurf | bdo init -g --agent windsurf |
.windsurfrules (project-scoped) |
| Cline / Roo Code | bdo init --agent cline |
.clinerules (project-scoped) |
| OpenCode | bdo init -g --opencode |
Plugin TS (tool.execute.before) |
| OpenClaw | openclaw plugins install ./openclaw |
Plugin TS (before_tool_call) |
| Pi | bdo init -g --agent pi (global) |
TypeScript extension (tool_call) |
| Hermes | bdo init --agent hermes |
Python plugin adapter (terminal command mutation via bdo rewrite) |
| Mistral Vibe | Planned (#800) | Blocked on upstream |
| Kilo Code | bdo init --agent kilocode |
.kilocode/rules/bdo-rules.md (project-scoped) |
| Google Antigravity | bdo init --agent antigravity |
.agents/rules/antigravity-bdo-rules.md (project-scoped) |
For per-agent setup details, override controls, and graceful degradation, see the Supported Agents guide. The Hermes plugin source and tests live in hooks/hermes/; installed Hermes runtime files still live under ~/.hermes/plugins/bdo-rewrite/.
~/.config/bdo/config.toml (macOS: ~/Library/Application Support/bdo/config.toml):
[hooks]
exclude_commands = ["curl", "playwright"] # skip rewrite for these
[tee]
enabled = true # save raw output on failure (default: true)
mode = "failures" # "failures", "always", or "never"When a command fails, Bushido saves the full unfiltered output so the LLM can read it without re-executing:
FAILED: 2/15 tests
[full output: ~/.local/share/bdo/tee/1707753600_cargo_test.log]
For the full config reference (all sections, env vars, per-project filters), see the Configuration guide.
bdo init -g --uninstall # Remove hook, Bushido.md, settings.json entry
cargo uninstall bdo # Remove binary
brew uninstall bdo # If installed via Homebrew- docs/guide — full user guide (installation, supported agents, what gets optimized, analytics, configuration, troubleshooting)
- INSTALL.md — detailed installation reference
- ARCHITECTURE.md — system design and technical decisions
- CONTRIBUTING.md — contribution guide
- SECURITY.md — security policy
Bushido can collect anonymous, aggregate usage metrics once per day. Telemetry is disabled by default and requires explicit opt-in consent (GDPR Art. 6, 7) during bdo init or via bdo telemetry enable. This data helps us build a better product: identifying which commands need filters, which filters need improvement, and how much value Bushido delivers. For the full list of fields, data handling, and contributor guidelines, see docs/TELEMETRY.md.
What is collected and why:
| Category | Data | Why |
|---|---|---|
| Identity | Salted device hash (SHA-256, not reversible) | Count unique installations without tracking individuals |
| Environment | Bushido version, OS, architecture, install method | Know which platforms to support and test |
| Usage volume | Command count (24h), total commands, tokens saved (24h/30d/total) | Measure adoption and value delivered |
| Quality | Top 5 passthrough commands (0% savings), parse failure count, commands with <30% savings | Identify missing filters and weak ones to improve |
| Ecosystem | Command category distribution (e.g. git 45%, cargo 20%, js 15%) | Prioritize filter development for popular ecosystems |
| Retention | Days since first use, active days in last 30 | Understand engagement and detect churn |
| Adoption | AI agent hook type (claude/gemini/codex), custom TOML filter count | Track integration coverage and DSL adoption |
| Configuration | Whether config.toml exists, number of excluded commands, project count | Understand user maturity and customization patterns |
| Features | Usage counts for meta-commands (gain, discover, proxy, verify) | Know which Bushido features are valued vs unused |
| Economics | Estimated USD savings (based on API token pricing) | Quantify the value Bushido provides to users |
All data is aggregate counts or anonymized command names (first 3 words, no arguments). Top commands report only tool names (e.g. "git", "cargo"), never full command lines.
What is NOT collected: source code, file paths, command arguments, secrets, environment variables, personal data, or repository contents.
Manage telemetry:
bdo telemetry status # Check current consent state
bdo telemetry enable # Give consent (interactive prompt)
bdo telemetry disable # Withdraw consent — stops all collection immediately
bdo telemetry forget # Withdraw consent + delete all local data + request server-side erasureOverride via environment:
export BDO_TELEMETRY_DISABLED=1 # Blocks telemetry regardless of consent- Patrick Szymkowiak — Founder GitHub · LinkedIn
- Florian Bruniaux — Core contributor GitHub · LinkedIn
- Adrien Eppling — Core contributor GitHub · LinkedIn
Contributions welcome! Please open an issue or PR on GitHub.
Apache License 2.0 - see LICENSE for details.
See DISCLAIMER.md.