{"id":31829350,"url":"https://github.com/docdyhr/batless","last_synced_at":"2026-02-27T11:46:59.751Z","repository":{"id":305955030,"uuid":"1024493391","full_name":"docdyhr/batless","owner":"docdyhr","description":"Minimal, blazing-fast syntax viewer for the terminal — never blocks, never pages, never hangs. Perfect for code, logs, and AI pipelines.","archived":false,"fork":false,"pushed_at":"2026-02-26T23:27:55.000Z","size":1142,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T05:43:47.727Z","etag":null,"topics":["ai-friendly","blazing-fast","cat-alternative","cli","code-viewer","less-alternative","log-viewer","no-dependencies","pager","rust","syntax-highlighting","terminal","tool"],"latest_commit_sha":null,"homepage":"https://github.com/docdyhr/batless","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docdyhr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"docdyhr"}},"created_at":"2025-07-22T19:36:29.000Z","updated_at":"2026-02-26T23:27:59.000Z","dependencies_parsed_at":"2026-01-06T01:04:46.350Z","dependency_job_id":null,"html_url":"https://github.com/docdyhr/batless","commit_stats":null,"previous_names":["docdyhr/batless"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/docdyhr/batless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docdyhr%2Fbatless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docdyhr%2Fbatless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docdyhr%2Fbatless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docdyhr%2Fbatless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docdyhr","download_url":"https://codeload.github.com/docdyhr/batless/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docdyhr%2Fbatless/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29892428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T09:48:51.284Z","status":"ssl_error","status_checked_at":"2026-02-27T09:48:43.992Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-friendly","blazing-fast","cat-alternative","cli","code-viewer","less-alternative","log-viewer","no-dependencies","pager","rust","syntax-highlighting","terminal","tool"],"created_at":"2025-10-11T20:02:05.640Z","updated_at":"2026-02-27T11:46:59.737Z","avatar_url":"https://github.com/docdyhr.png","language":"Rust","readme":"# 🦇 batless\n\n\u003cdiv align=\"center\"\u003e\n\n## The Ultimate Non-Blocking Code Viewer\n\nBuilt for automation, AI assistants, and modern CLI workflows\n\n[![Crates.io](https://img.shields.io/crates/v/batless?logo=rust\u0026logoColor=white)](https://crates.io/crates/batless)\n[![Crates.io Downloads](https://img.shields.io/crates/d/batless?logo=rust\u0026logoColor=white)](https://crates.io/crates/batless)\n[![GitHub Downloads](https://img.shields.io/github/downloads/docdyhr/batless/total?logo=github\u0026logoColor=white)](https://github.com/docdyhr/batless/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green?logo=opensource\u0026logoColor=white)](https://opensource.org/licenses/MIT)\n[![GitHub Release](https://img.shields.io/github/v/release/docdyhr/batless?include_prereleases\u0026logo=github\u0026logoColor=white)](https://github.com/docdyhr/batless/releases)\n\n[![Health Check](https://github.com/docdyhr/batless/actions/workflows/health-check.yml/badge.svg?branch=main)](https://github.com/docdyhr/batless/actions/workflows/health-check.yml)\n[![Security](https://github.com/docdyhr/batless/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/docdyhr/batless/actions/workflows/security.yml)\n[![Fuzz Testing](https://github.com/docdyhr/batless/actions/workflows/fuzz.yml/badge.svg?branch=main)](https://github.com/docdyhr/batless/actions/workflows/fuzz.yml)\n[![Codecov](https://codecov.io/gh/docdyhr/batless/branch/main/graph/badge.svg?logo=codecov\u0026logoColor=white)](https://codecov.io/gh/docdyhr/batless)\n\n[![Rust](https://img.shields.io/badge/Rust-100%25-orange?logo=rust\u0026logoColor=white)](https://github.com/docdyhr/batless)\n[![Security Tests](https://img.shields.io/badge/security%20tests-passing-brightgreen?logo=shield\u0026logoColor=white)](https://github.com/docdyhr/batless)\n[![Performance](https://img.shields.io/badge/startup-\u003c5ms*-brightgreen?logo=speedtest\u0026logoColor=white)](https://github.com/docdyhr/batless)\n[![Binary Size](https://img.shields.io/badge/binary%20size-~2MB-blue?logo=filetype\u0026logoColor=white)](https://github.com/docdyhr/batless)\n\n\u003c/div\u003e\n\n## 🎯 Why batless?\n\n**Transform code viewing** from blocking interactive pagers to predictable streaming output:\n\n```text\n❌ Before: bat file.rs → hangs in CI/CD, requires terminal, blocks automation\n✅ After:  batless file.rs → streams immediately, works everywhere, never blocks\n```\n\n**Key Advantages:**\n\n- 🚀 **Never Blocks**: Guaranteed non-blocking operation for CI/CD and automation\n- 🤖 **AI-Optimized**: JSON output, summaries, and tokens for LLM processing\n- ⚡ **Blazing Fast**: \u003c5ms typical startup (modern hardware), streaming architecture, ~2MB binary\n- 🔧 **Automation-First**: Clean defaults, predictable behavior, perfect for scripts\n- 📊 **Smart Output**: Multiple modes including summary extraction and token analysis\n\n**batless** is a minimal, blazing-fast syntax viewer that **never blocks, never pages, never hangs**. While [`bat`](https://github.com/sharkdp/bat) is a feature-rich \"cat with wings\" for human users, `batless` is purpose-built for:\n\n- 🤖 **AI code assistants** that need predictable, streaming output\n- 🔄 **CI/CD pipelines** where interactive pagers would hang forever\n- 📜 **Automation scripts** that require guaranteed non-blocking behavior\n- 🚀 **Modern workflows** where JSON output and code summaries matter more than line numbers\n\n**Core guarantee**: `batless` will NEVER wait for user input or block your pipeline.\n\n## 🚀 Quick Start\n\n### Installation\n\n#### Option A: Pre-built Binaries (Fastest)\n\n```bash\n# Linux (x86_64)\ncurl -L https://github.com/docdyhr/batless/releases/latest/download/batless-x86_64-unknown-linux-gnu.tar.gz | tar xz\n\n# macOS (Intel)\ncurl -L https://github.com/docdyhr/batless/releases/latest/download/batless-x86_64-apple-darwin.tar.gz | tar xz\n\n# macOS (Apple Silicon)\ncurl -L https://github.com/docdyhr/batless/releases/latest/download/batless-aarch64-apple-darwin.tar.gz | tar xz\n```\n\n#### Option B: Via Cargo\n\n```bash\ncargo install batless\n```\n\n#### Option C: Homebrew (macOS/Linux)\n\n```bash\nbrew tap docdyhr/batless\nbrew install batless\n```\n\n### Basic Usage\n\n```bash\n# View a file with syntax highlighting\nbatless src/main.rs\n\n# Plain text output (no colors)\nbatless --plain file.py\n\n# With line numbers (cat -n compatibility)\nbatless -n file.py\n\n# JSON output for structured processing\nbatless --mode=json --max-lines=100 src/lib.rs\n\n# Extract code summary (functions, classes, imports)\nbatless --mode=summary src/main.rs\n\n# Get version info as JSON\nbatless --version-json\n```\n\n## 🌟 What Makes batless Special\n\n### 🏆 Feature Comparison\n\n| Feature | `batless` | `bat` | `cat` |\n|---------|-----------|-------|-------|\n| **Never Blocks** | ✅ **Guaranteed** | ❌ Uses pager | ✅ Simple output |\n| **Syntax Highlighting** | ✅ 100+ languages | ✅ Rich highlighting | ❌ None |\n| **JSON Output** | ✅ **First-class** | ❌ Not supported | ❌ Not supported |\n| **Summary Mode** | ✅ **AI-optimized** | ❌ Not supported | ❌ Not supported |\n| **Memory Usage** | ✅ **Streaming** | ⚠️ Loads full file | ✅ Streaming |\n| **Binary Size** | ✅ **~2MB** | ⚠️ ~10MB | ✅ System binary |\n| **Startup Time** | ✅ **\u003c5ms (typical)** | ⚠️ ~180ms | ✅ \u003c10ms |\n\n### 🚀 Core Capabilities\n\n#### Non-Blocking Guarantees\n\n- 🚫 **NEVER uses a pager** - no `less`, no `more`, no blocking\n- ⚡ **NEVER waits for input** - always streams output immediately\n- 🔄 **NEVER hangs in pipes** - safe for `|`, `\u003e`, and subprocess calls\n- 📊 **ALWAYS returns quickly** - even on huge files (streaming architecture)\n\n#### Syntax \u0026 Language Support\n\n- 🎨 **Syntax highlighting** for 100+ languages via syntect\n- 🔍 **Language auto-detection** with manual override support\n- 🎭 **Theme support** - Multiple color schemes available\n- 🌐 **Universal support** - Works with any text-based file format\n\n#### Smart Output Modes\n\n- 📊 **Multiple output modes**: plain, highlighted, JSON, summary\n- 📏 **Smart limiting** by lines (`--max-lines`) and/or bytes (`--max-bytes`)\n- 💾 **Memory efficient** - true streaming, never loads full files\n- 🎯 **Predictable behavior** - same output in terminal or pipe\n- 🧠 **Dual-view summaries** - `lines` always retains the full file while `summary_lines` carries the condensed view\n- 🔢 **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\n\n#### Built for Automation\n\n- 🤖 **AI-optimized JSON** output with metadata, tokens, and summaries\n- 📋 **Summary mode** extracts functions, classes, imports only\n- 🔤 **Token extraction** for LLM context processing\n- 🚫 **Clean defaults** - no decorations unless requested\n- 📦 **Single ~2MB binary** with minimal dependencies\n\n## 🚫 What batless is NOT\n\n**batless** has a focused design philosophy. It intentionally does NOT provide:\n\n### Features We Don't Implement (By Design)\n\n| Feature | Why Not? | Use Instead |\n|---------|----------|-------------|\n| **Pattern Search** | That's `grep`'s job | `grep -rn \"pattern\" path/` |\n| **Arbitrary Line Ranges** | Beyond our scope | `sed -n '10,50p' file` |\n| **File Globbing** | Shell handles this | `batless *.py` (shell expands) |\n| **Interactive Paging** | We're non-blocking | Use `bat` or `less` |\n| **Git Integration** | Keep it simple | Use `git diff` or `bat` |\n| **File Management** | Not a file browser | `ls`, `find`, `fd` |\n| **Text Editing** | Viewer only | Use your editor |\n\n### Common Misconceptions\n\n❌ **\"batless is a drop-in replacement for bat\"**\n✅ **Reality**: batless is purpose-built for automation and AI, not interactive use\n\n❌ **\"batless should add grep-like search\"**\n✅ **Reality**: Unix philosophy - do one thing well. Use `grep` for searching\n\n❌ **\"batless needs more features like bat\"**\n✅ **Reality**: Less is more. Our constraints are features for automation\n\n### When NOT to Use batless\n\n- 👤 **Interactive code review**: Use `bat` - it has better human-focused features\n- 🔍 **Searching code**: Use `grep`, `rg` (ripgrep), or `ag` (silver searcher)\n- 📝 **Editing files**: Use your favorite editor\n- 📊 **Complex analysis**: Use language-specific tools (pylint, rust-analyzer, etc.)\n- 🎨 **Pretty printing**: Use `bat` with its full decoration suite\n\n### Our Philosophy\n\n```text\nDo ONE thing well: Stream code with syntax highlighting, never block.\nEverything else? There's already a better tool for that.\n```\n\n## 📖 Usage Examples\n\n### Basic File Viewing\n\n```bash\n# Syntax highlighted output\nbatless main.rs\n\n# Plain text (no colors)\nbatless --plain main.rs\n\n# With line numbers\nbatless -n main.rs\n\n# Limit output\nbatless --max-lines=50 large-file.py\nbatless --max-bytes=10000 huge-file.log\n```\n\n### AI \u0026 Automation Workflows\n\n```bash\n# JSON output for LLM processing\nbatless --mode=json --include-tokens --summary src/main.rs | jq\n\n# Extract code structure only\nbatless --mode=summary src/*.rs\n\n# CI/CD context generation\nbatless --mode=json --max-lines=100 failing-test.rs \u003e context.json\n\n# Machine-readable metadata\nbatless --version-json\n```\n\n\u003e **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.\n\n### Pipeline Integration\n\n```bash\n# Use as PAGER replacement\nPAGER=\"batless --plain\" gh pr view 42\n\n# Process multiple files\nfind src -name \"*.rs\" -exec batless --mode=summary {} \\;\n\n# Combine with grep\ngrep -l \"TODO\" src/*.py | xargs batless -n\n\n# Stream stdin\ncat file.rs | batless --language=rust\n```\n\n### Custom Profiles\n\n```bash\n# Use AI-optimized profile\nbatless --profile=claude main.rs\n\n# Interactive configuration wizard\nbatless --configure\n\n# List available profiles\nbatless --list-profiles\n```\n\n## 🎨 Configuration\n\n### Themes\n\nbatless supports multiple color themes for syntax highlighting:\n\n```bash\n# List available themes\nbatless --list-themes\n\n# Use specific theme\nbatless --theme=\"Solarized (dark)\" file.py\n```\n\n#### Available Themes\n\nbatless currently includes 7 carefully curated themes:\n\n- **InspiredGitHub** - Clean, GitHub-inspired light theme\n- **Solarized (dark)** - Popular dark theme with excellent contrast\n- **Solarized (light)** - Light variant of the Solarized theme\n- **base16-eighties.dark** - Retro 80s-inspired dark theme\n- **base16-mocha.dark** - Warm, chocolate-toned dark theme\n- **base16-ocean.dark** - Cool, oceanic dark theme\n- **base16-ocean.light** - Light variant of the ocean theme\n\nTry different themes to find the one that works best for your workflow:\n\n```bash\n# Try each theme with your code\nbatless --theme=\"InspiredGitHub\" examples/theme-showcase.rs\nbatless --theme=\"Solarized (dark)\" examples/theme-showcase.rs\nbatless --theme=\"base16-mocha.dark\" examples/theme-showcase.rs\n```\n\n\u003e **Note**: Theme examples are available in [docs/themes/](docs/themes/) and can be regenerated with `./scripts/generate-theme-showcase.sh`\n\n### Language Detection\n\n```bash\n# Auto-detect (default)\nbatless file.txt\n\n# Force specific language\nbatless --language=python unknown.file\n\n# List supported languages\nbatless --list-languages\n```\n\n### Custom Profiles\n\nCreate custom profiles in `~/.batless/profiles/`:\n\n```toml\n# ~/.batless/profiles/my-profile.toml\nname = \"my-profile\"\nmax_lines = 1000\nsummary_level = \"medium\"\ninclude_tokens = true\n```\n\nUse with:\n\n```bash\nbatless --custom-profile ~/.batless/profiles/my-profile.toml file.rs\n```\n\n### Shell Completions\n\nbatless includes built-in shell completion support for bash, zsh, fish, and PowerShell.\n\n#### Bash\n\n```bash\n# Generate and install completions\nbatless --generate-completions bash \u003e ~/.local/share/bash-completion/completions/batless\n\n# Or for system-wide installation\nsudo batless --generate-completions bash \u003e /usr/share/bash-completion/completions/batless\n\n# Then reload your shell or source the completion file\nsource ~/.local/share/bash-completion/completions/batless\n```\n\n#### Zsh\n\n```bash\n# Generate and install completions\nbatless --generate-completions zsh \u003e ~/.zsh/completions/_batless\n\n# Add to your ~/.zshrc (if not already present)\nfpath=(~/.zsh/completions $fpath)\nautoload -Uz compinit \u0026\u0026 compinit\n\n# Then reload your shell\nexec zsh\n```\n\n#### Fish\n\n```bash\n# Generate and install completions\nbatless --generate-completions fish \u003e ~/.config/fish/completions/batless.fish\n\n# Completions are automatically loaded in new fish shells\n```\n\n#### PowerShell\n\n```powershell\n# Generate and add to your profile\nbatless --generate-completions powershell | Out-String | Invoke-Expression\n\n# Or save to your profile for persistence\nbatless --generate-completions powershell \u003e\u003e $PROFILE\n```\n\n## 🔧 CLI Options\n\n### Output Modes\n\n- `--mode \u003cMODE\u003e` - Output mode: `plain`, `highlight`, `json`, `summary`\n- `--plain` - Plain text output (equivalent to `--mode=plain`)\n- `--mode=json` - Structured JSON output for automation\n- `--mode=summary` - Extract only key code structures\n\n### Limiting Output\n\n- `--max-lines \u003cN\u003e` - Limit output to N lines\n- `--max-bytes \u003cN\u003e` - Limit output to N bytes\n- `--lines \u003cSTART:END\u003e` - Select specific line range (e.g., `10:50`, `:100`, `50:`)\n\n### Display Options\n\n- `-n, --number` - Show line numbers (cat -n compatibility)\n- `-b, --number-nonblank` - Number non-blank lines only (cat -b compatibility)\n- `--theme \u003cTHEME\u003e` - Color scheme to use\n- `--language \u003cLANG\u003e` - Force specific language syntax\n\n### AI/Automation Features\n\n- `--include-tokens` - Include token analysis in JSON output\n- `--summary` - Add code summary to JSON output\n- `--profile \u003cPROFILE\u003e` - Use AI-optimized profile (claude, copilot, chatgpt)\n- `--custom-profile \u003cPATH\u003e` - Load custom profile from file\n\n### Configuration\n\n- `--configure` - Launch interactive configuration wizard\n- `--list-profiles` - Show all available custom profiles\n- `--list-themes` - Show all available color themes\n- `--list-languages` - Show all supported languages\n\n### Utility\n\n- `--version` - Show version information\n- `--version-json` - Machine-readable version metadata\n- `--help` - Show detailed help information\n\n## 🤖 AI Assistant Integration\n\nbatless is designed to work seamlessly with AI coding assistants:\n\n### Claude Code\n\n```bash\n# Use batless in Claude Code workflows\nbatless --profile=claude --max-lines=500 src/main.rs\n```\n\n### GitHub Copilot CLI\n\n```bash\n# Generate context for Copilot\nbatless --mode=json --summary src/ | gh copilot suggest\n```\n\n### ChatGPT / Other LLMs\n\n```bash\n# Generate structured context\nbatless --mode=json --include-tokens --max-lines=1000 file.rs \u003e context.json\n```\n\nSee [docs/AI_INTEGRATION.md](docs/AI_INTEGRATION.md) for detailed integration guides.\n\n## 🏗️ Architecture\n\nbatless is built with:\n\n- **Rust** - Memory safety and performance\n- **syntect** - Syntax highlighting engine\n- **Streaming architecture** - Memory-efficient processing\n- **Modular design** - Clean separation of concerns\n\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for technical details.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see:\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines\n- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Community standards\n- [docs/PHILOSOPHY_AND_SCOPE.md](docs/PHILOSOPHY_AND_SCOPE.md) - Project philosophy\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/docdyhr/batless.git\ncd batless\n\n# Build\ncargo build\n\n# Run tests\ncargo test\n\n# Run with example\ncargo run -- src/main.rs\n```\n\n## 📊 Performance\n\n- **Startup time**: \u003c5ms typical on modern hardware\n- **Binary size**: ~2MB (minimal dependencies)\n- **Memory usage**: Constant (streaming architecture)\n- **Throughput**: Limited only by syntax highlighting speed\n\n*Note: Performance varies by hardware. Benchmarks on typical developer workstation.*\n\n## 📜 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🔗 Links\n\n- **Documentation**: [docs/](docs/)\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md)\n- **Releases**: [GitHub Releases](https://github.com/docdyhr/batless/releases)\n- **Issues**: [GitHub Issues](https://github.com/docdyhr/batless/issues)\n- **Crates.io**: [crates.io/crates/batless](https://crates.io/crates/batless)\n\n## 🙏 Acknowledgments\n\n- Inspired by [`bat`](https://github.com/sharkdp/bat) by @sharkdp\n- Built with [`syntect`](https://github.com/trishume/syntect) by @trishume\n- Community feedback and contributions\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ for automation, AI assistants, and modern CLI workflows**\n\n[⭐ Star on GitHub](https://github.com/docdyhr/batless) | [📦 Install Now](#-quick-start) | [📖 Read the Docs](docs/)\n\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/docdyhr"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocdyhr%2Fbatless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocdyhr%2Fbatless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocdyhr%2Fbatless/lists"}