🦇 batless

The Ultimate Non-Blocking Code Viewer

Built for automation, AI assistants, and modern CLI workflows

🎯 Why batless?

Transform code viewing from blocking interactive pagers to predictable streaming output:

❌ Before: bat file.rs → hangs in CI/CD, requires terminal, blocks automation
✅ After:  batless file.rs → streams immediately, works everywhere, never blocks

Key Advantages:

🚀 Never Blocks: Guaranteed non-blocking operation for CI/CD and automation
🤖 AI-Optimized: JSON output, summaries, and tokens for LLM processing
⚡ Blazing Fast: <5ms typical startup (modern hardware), streaming architecture, ~2MB binary
🔧 Automation-First: Clean defaults, predictable behavior, perfect for scripts
📊 Smart Output: Multiple modes including summary extraction and token analysis

batless is a minimal, blazing-fast syntax viewer that never blocks, never pages, never hangs. While bat is a feature-rich "cat with wings" for human users, batless is purpose-built for:

🤖 AI code assistants that need predictable, streaming output
🔄 CI/CD pipelines where interactive pagers would hang forever
📜 Automation scripts that require guaranteed non-blocking behavior
🚀 Modern workflows where JSON output and code summaries matter more than line numbers

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

🚀 Quick Start

Installation

Option A: Pre-built Binaries (Fastest)

# 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

Option B: Via Cargo

cargo install batless

Option C: Homebrew (macOS/Linux)

brew tap docdyhr/batless
brew install batless

Basic Usage

# View a file with syntax highlighting
batless src/main.rs

# Plain text output (no colors)
batless --plain file.py

# With line numbers (cat -n compatibility)
batless -n file.py

# JSON output for structured processing
batless --mode=json --max-lines=100 src/lib.rs

# Extract code summary (functions, classes, imports)
batless --mode=summary src/main.rs

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

🌟 What Makes batless Special

🏆 Feature Comparison

Feature	`batless`	`bat`	`cat`
Never Blocks	✅ Guaranteed	❌ Uses pager	✅ Simple output
Syntax Highlighting	✅ 100+ languages	✅ Rich highlighting	❌ None
JSON Output	✅ First-class	❌ Not supported	❌ Not supported
Summary Mode	✅ AI-optimized	❌ Not supported	❌ Not supported
Memory Usage	✅ Streaming	⚠️ Loads full file	✅ Streaming
Binary Size	✅ ~2MB	⚠️ ~10MB	✅ System binary
Startup Time	✅ <5ms (typical)	⚠️ ~180ms	✅ <10ms

🚀 Core Capabilities

Non-Blocking Guarantees

🚫 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)

Syntax & Language Support

🎨 Syntax highlighting for 100+ languages via syntect
🔍 Language auto-detection with manual override support
🎭 Theme support - Multiple color schemes available
🌐 Universal support - Works with any text-based file format

Smart Output Modes

📊 Multiple output modes: plain, highlighted, JSON, summary
📏 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

Built for Automation

🤖 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

🚫 What batless is NOT

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

Features We Don't Implement (By Design)

Feature	Why Not?	Use Instead
Pattern Search	That's `grep`'s job	`grep -rn "pattern" path/`
Arbitrary Line Ranges	Beyond our scope	`sed -n '10,50p' file`
File Globbing	Shell handles this	`batless *.py` (shell expands)
Interactive Paging	We're non-blocking	Use `bat` or `less`
Git Integration	Keep it simple	Use `git diff` or `bat`
File Management	Not a file browser	`ls`, `find`, `fd`
Text Editing	Viewer only	Use your editor

Common Misconceptions

❌ "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

When NOT to Use batless

👤 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

Our Philosophy

Do ONE thing well: Stream code with syntax highlighting, never block.
Everything else? There's already a better tool for that.

📖 Usage Examples

Basic File Viewing

# 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

AI & Automation Workflows

# 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

Pipeline Integration

# 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

Custom Profiles

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

# Interactive configuration wizard
batless --configure

# List available profiles
batless --list-profiles

🎨 Configuration

Themes

# List available themes
batless --list-themes

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

Language Detection

# Auto-detect (default)
batless file.txt

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

# List supported languages
batless --list-languages

Custom Profiles

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

🔧 CLI Options

Output Modes

--mode <MODE> - Output mode: plain, highlight, json, summary
--plain - Plain text output (equivalent to --mode=plain)
--mode=json - Structured JSON output for automation
--mode=summary - Extract only key code structures

Limiting Output

--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:)

Display Options

-n, --number - Show line numbers (cat -n compatibility)
-b, --number-nonblank - Number non-blank lines only (cat -b compatibility)
--theme <THEME> - Color scheme to use
--language <LANG> - Force specific language syntax

AI/Automation Features

--include-tokens - Include token analysis in JSON output
--summary - Add code summary to JSON output
--profile <PROFILE> - Use AI-optimized profile (claude, copilot, chatgpt)
--custom-profile <PATH> - Load custom profile from file

Configuration

--configure - Launch interactive configuration wizard
--list-profiles - Show all available custom profiles
--list-themes - Show all available color themes
--list-languages - Show all supported languages

Utility

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

🤖 AI Assistant Integration

batless is designed to work seamlessly with AI coding assistants:

Claude Code

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

GitHub Copilot CLI

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

ChatGPT / Other LLMs

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

See docs/AI_INTEGRATION.md for detailed integration guides.

🏗️ Architecture

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.

🤝 Contributing

We welcome contributions! Please see:

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

Development Setup

# 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

📊 Performance

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.

📜 License

MIT License - see LICENSE for details.

🔗 Links

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

🙏 Acknowledgments

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

Built with ❤️ for automation, AI assistants, and modern CLI workflows

⭐ Star on GitHub | 📦 Install Now | 📖 Read the Docs

batless 0.3.1

🦇 batless

The Ultimate Non-Blocking Code Viewer

🎯 Why batless?

🚀 Quick Start

Installation

Option A: Pre-built Binaries (Fastest)

Option B: Via Cargo

Option C: Homebrew (macOS/Linux)

Basic Usage

🌟 What Makes batless Special

🏆 Feature Comparison

🚀 Core Capabilities

Non-Blocking Guarantees

Syntax & Language Support

Smart Output Modes

Built for Automation

🚫 What batless is NOT

Features We Don't Implement (By Design)

Common Misconceptions

When NOT to Use batless

Our Philosophy

📖 Usage Examples

Basic File Viewing

AI & Automation Workflows

Pipeline Integration

Custom Profiles

🎨 Configuration

Themes

Language Detection

Custom Profiles

🔧 CLI Options

Output Modes

Limiting Output

Display Options

AI/Automation Features

Configuration

Utility

🤖 AI Assistant Integration

Claude Code

GitHub Copilot CLI

ChatGPT / Other LLMs

🏗️ Architecture

🤝 Contributing

Development Setup

📊 Performance

📜 License

🔗 Links

🙏 Acknowledgments