AI assistants like Claude Code have native tools for reading files, searching, and listing directories. What they don't have is structured analysis output:

# Symbol index — navigate code without loading full content
batless --mode=index src/main.rs | jq '.symbols[] | "\(.line_start): \(.kind) \(.name)"'

# Token estimation — gate context decisions before loading a file
batless --mode=json --profile=claude file.py | jq '.estimated_llm_tokens'

# Compressed context — language-aware comment and blank stripping
batless --mode=json --profile=claude --strip-comments --strip-blank-lines file.py

# Semantic chunks — split large files at declaration boundaries
batless --mode=json --streaming --chunk-strategy=semantic large_file.rs

# Content hash — detect changes without loading content
batless --mode=json --hash file.rs | jq '.file_hash'

These are the outputs batless is built for. For plain file viewing, use cat, bat, or your editor.

Core guarantee: batless will NEVER wait for user input or block your pipeline.

# Linux (x86_64)
curl -L https://github.com/docdyhr/batless/releases/latest/download/batless-x86_64-unknown-linux-gnu.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/docdyhr/batless/releases/latest/download/batless-x86_64-apple-darwin.tar.gz | tar xz

# macOS (Apple Silicon)
curl -L https://github.com/docdyhr/batless/releases/latest/download/batless-aarch64-apple-darwin.tar.gz | tar xz

cargo install batless

brew tap docdyhr/batless
brew install batless

# Symbol index — structure without loading full content
batless --mode=index src/main.rs

# Multi-file symbol index — walk directory, one NDJSON line per file
batless --mode=index src/ | jq -c 'select(.symbol_count > 0) | {file, symbol_count}'

# Raw AST — full tree-sitter parse tree for deep structural analysis
batless --mode=ast src/lib.rs | jq '.root.type'


# Token estimation — check size before loading into AI context
batless --mode=json --profile=claude file.py | jq '.estimated_llm_tokens'

# Compressed AI context
batless --mode=json --profile=claude --strip-comments --strip-blank-lines src/lib.rs

# Semantic streaming chunks for large files
batless --mode=json --streaming --chunk-strategy=semantic large_file.rs

# Plain text (for piping to other tools)
batless --plain file.py

# Get version info as JSON
batless --version-json

• 🚫 NEVER uses a pager - no less, no more, no blocking
• ⚡ NEVER waits for input - always streams output immediately
• 🔄 NEVER hangs in pipes - safe for |, >, and subprocess calls
• 📊 ALWAYS returns quickly - even on huge files (streaming architecture)

• 🔍 Language auto-detection with manual override (--language)
• 🌳 AST-backed analysis for Rust, Python, JavaScript, TypeScript (regex fallback for others)
• 🌐 Universal plain output — works with any text-based file format

• 📊 Multiple output modes: plain, JSON, summary, index, ast
• 📏 Smart limiting by lines (--max-lines) and/or bytes (--max-bytes)
• 💾 Memory efficient - true streaming, never loads full files
• 🎯 Predictable behavior - same output in terminal or pipe
• 🧠 Dual-view summaries - lines always retains the full file while summary_lines carries the condensed view
• 🔢 Token-aware JSON - token_count reflects the full file even when the sampled tokens array is capped (~2K entries) and tokens_truncated tells you when sampling kicked in

• 🤖 AI-optimized JSON output with metadata, tokens, and summaries
• 📋 Summary mode extracts functions, classes, imports only
• 🔤 Token extraction for LLM context processing
• 🚫 Clean defaults - no decorations unless requested
• 📦 Single ~2MB binary with minimal dependencies

batless has a focused design philosophy. It intentionally does NOT provide:

❌ "batless is a drop-in replacement for bat" ✅ Reality: batless is purpose-built for automation and AI, not interactive use

❌ "batless should add grep-like search" ✅ Reality: Unix philosophy - do one thing well. Use grep for searching

❌ "batless needs more features like bat" ✅ Reality: Less is more. Our constraints are features for automation

• 👤 Interactive code review: Use bat - it has better human-focused features
• 🔍 Searching code: Use grep, rg (ripgrep), or ag (silver searcher)
• 📝 Editing files: Use your favorite editor
• 📊 Complex analysis: Use language-specific tools (pylint, rust-analyzer, etc.)
• 🎨 Pretty printing: Use bat with its full decoration suite

Do ONE thing well: produce structured, machine-readable code analysis that
AI assistants can't generate themselves. For everything else — plain viewing,
searching, interactive use — there's already a better tool.

# Syntax highlighted output
batless main.rs

# Plain text (no colors)
batless --plain main.rs

# With line numbers
batless -n main.rs

# Limit output
batless --max-lines=50 large-file.py
batless --max-bytes=10000 huge-file.log

# JSON output for LLM processing
batless --mode=json --include-tokens --summary src/main.rs | jq

# Extract code structure only
batless --mode=summary src/*.rs

# CI/CD context generation
batless --mode=json --max-lines=100 failing-test.rs > context.json

# Machine-readable metadata
batless --version-json

JSON structure tips: lines always contains the full file content (even when --summary is enabled), while summary_lines carries the condensed view. The payload now exposes total_lines_exact, token_count, and tokens_truncated so downstream tools can distinguish between fully processed files and sampled metadata.

# Use as PAGER replacement
PAGER="batless --plain" gh pr view 42

# Process multiple files
find src -name "*.rs" -exec batless --mode=summary {} \;

# Combine with grep
grep -l "TODO" src/*.py | xargs batless -n

# Stream stdin
cat file.rs | batless --language=rust

# Use AI-optimized profile
batless --profile=claude main.rs

# Interactive configuration wizard
batless --configure

# List available profiles
batless --list-profiles

batless supports multiple color themes for syntax highlighting:

# List available themes
batless --list-themes

# Use specific theme
batless --theme="Solarized (dark)" file.py

batless currently includes 7 carefully curated themes:

• InspiredGitHub - Clean, GitHub-inspired light theme
• Solarized (dark) - Popular dark theme with excellent contrast
• Solarized (light) - Light variant of the Solarized theme
• base16-eighties.dark - Retro 80s-inspired dark theme
• base16-mocha.dark - Warm, chocolate-toned dark theme
• base16-ocean.dark - Cool, oceanic dark theme
• base16-ocean.light - Light variant of the ocean theme

Try different themes to find the one that works best for your workflow:

# Try each theme with your code
batless --theme="InspiredGitHub" examples/theme-showcase.rs
batless --theme="Solarized (dark)" examples/theme-showcase.rs
batless --theme="base16-mocha.dark" examples/theme-showcase.rs

Note: Theme examples are available in docs/themes/ and can be regenerated with ./scripts/generate-theme-showcase.sh

# Auto-detect (default)
batless file.txt

# Force specific language
batless --language=python unknown.file

# List supported languages
batless --list-languages

Create custom profiles in ~/.batless/profiles/:

# ~/.batless/profiles/my-profile.toml
name = "my-profile"
max_lines = 1000
summary_level = "medium"
include_tokens = true

Use with:

batless --custom-profile ~/.batless/profiles/my-profile.toml file.rs

batless includes built-in shell completion support for bash, zsh, fish, and PowerShell.

# Generate and install completions
batless --generate-completions bash > ~/.local/share/bash-completion/completions/batless

# Or for system-wide installation
sudo batless --generate-completions bash > /usr/share/bash-completion/completions/batless

# Then reload your shell or source the completion file
source ~/.local/share/bash-completion/completions/batless

# Generate and install completions
batless --generate-completions zsh > ~/.zsh/completions/_batless

# Add to your ~/.zshrc (if not already present)
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

# Then reload your shell
exec zsh

# Generate and install completions
batless --generate-completions fish > ~/.config/fish/completions/batless.fish

# Completions are automatically loaded in new fish shells

# Generate and add to your profile
batless --generate-completions powershell | Out-String | Invoke-Expression

# Or save to your profile for persistence
batless --generate-completions powershell >> $PROFILE

• --mode <MODE> - Output mode: plain, json, summary, index, ast
• --plain - Plain text output (equivalent to --mode=plain)
• --mode=json - Structured JSON output for automation
• --mode=summary - Extract only key code structures
• --mode=index - Machine-readable symbol table (kind, name, line ranges, visibility); pass a directory to walk it and emit one NDJSON line per file
• --mode=ast - Raw tree-sitter parse tree as JSON (Rust, Python, JavaScript, TypeScript, TSX; "root": null for other languages)

• --max-lines <N> - Limit output to N lines
• --max-bytes <N> - Limit output to N bytes
• --lines <START:END> - Select specific line range (e.g., 10:50, :100, 50:)

• -n, --number - Show line numbers (cat -n compatibility)
• -b, --number-nonblank - Number non-blank lines only (cat -b compatibility)
• --language <LANG> - Force specific language syntax

• --include-identifiers - Include extracted code identifiers in JSON output (--include-tokens still works as alias)
• --with-line-numbers - JSON lines array uses {"n": N, "text": "..."} objects instead of plain strings
• --hash - Include SHA-256 content hash in JSON output (for change detection)
• --strip-comments - Strip comment-only lines from output
• --strip-blank-lines - Strip blank lines from output
• --chunk-strategy <STRATEGY> - Streaming chunk strategy: line (default) or semantic (splits at top-level declaration boundaries for Rust/Python/JS/TS)
• --summary - Add code summary to JSON output
• --profile <PROFILE> - Use AI-optimized profile (claude 20K lines, claude-max 150K lines, copilot, chatgpt, gemini, assistant)
• --custom-profile <PATH> - Load custom profile from file

When using --mode=json, the output includes:

When using --mode=index, the output includes:

When using --mode=ast, the output includes:

• --list-languages - Show all supported languages

• --version - Show version information
• --version-json - Machine-readable version metadata
• --help - Show detailed help information

batless is designed to work seamlessly with AI coding assistants:

# Use batless in Claude Code workflows
batless --profile=claude --max-lines=500 src/main.rs

# Generate context for Copilot
batless --mode=json --summary src/ | gh copilot suggest

# Generate structured context
batless --mode=json --include-tokens --max-lines=1000 file.rs > context.json

See docs/AI_INTEGRATION.md for detailed integration guides.

batless is built with:

• Rust - Memory safety and performance
• syntect - Syntax highlighting engine
• Streaming architecture - Memory-efficient processing
• Modular design - Clean separation of concerns

See docs/ARCHITECTURE.md for technical details.

We welcome contributions! Please see:

• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Community standards
• docs/PHILOSOPHY_AND_SCOPE.md - Project philosophy

# Clone repository
git clone https://github.com/docdyhr/batless.git
cd batless

# Build
cargo build

# Run tests
cargo test

# Run with example
cargo run -- src/main.rs

• Startup time: <5ms typical on modern hardware
• Binary size: ~2MB (minimal dependencies)
• Memory usage: Constant (streaming architecture)
• Throughput: Limited only by syntax highlighting speed

Note: Performance varies by hardware. Benchmarks on typical developer workstation.

MIT License - see LICENSE for details.

• Documentation: docs/
• Changelog: CHANGELOG.md
• Releases: GitHub Releases
• Issues: GitHub Issues
• Crates.io: crates.io/crates/batless

• Inspired by bat by @sharkdp
• Built with syntect by @trishume
• Community feedback and contributions