batless 0.2.4

A non-blocking, LLM-friendly code viewer inspired by bat
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# PRD.md

## Product Requirements Document  
**Project Name:** `batless` – A Minimal, AI-Safe Syntax Code Viewer  
**Status:** Draft  
**Author:** Thomas  
**Target Users:** LLM-based code agents (e.g., Claude Code, Gemini), developers using automation, non-interactive CI pipelines.

---

## 1. Purpose

To build a fast, syntax-aware, non-interactive code viewer CLI for AI coding agents. Unlike traditional pagers (`less`, `more`) or developer-centric tools (`bat`), `batless` provides clean, syntax-highlighted output with no blocking, no decoration, and perfect predictability.

---

## 2. Problem Statement

Tools like `bat` often block on `less`, break in CI, or output too much formatting. Even with `--paging=never`, output is inconsistent across platforms. Claude and other code assistants fail or hang when pagers expect interaction.

---

## 3. Goals

- ✅ Always non-blocking and streaming
- ✅ Tree-sitter or Syntect-based syntax highlighting
- ✅ Clean, machine-readable output
- ✅ Optional JSON/token/tokenized output
- ✅ Extremely fast and small footprint

---

## 4. Features

### Required (MVP)
- `--plain`: Raw content, no decorations
- `--language=auto|<lang>`: Auto-detect or force syntax
- `--mode=highlight|plain|json`: Output format modes
- `--max-lines`, `--max-bytes`: Output limiting
- Streamed output (never loads entire file)

### Highlighting and Color Output
- ANSI syntax highlighting
- `--color=never` or `--strip-ansi` support
- Configurable theme (basic light/dark)

### Optional (Post-MVP)
- `--ast`: Emit syntax structure
- `--summary`: Show top-level code only
- `--llm-mode`: Safe defaults for agents

---

## 5. Non-Goals

- No interactive paging
- No Git integration or headers
- No line numbers unless explicitly requested

---

## 6. Users / Use Cases

| User          | Use Case                                         |
|---------------|--------------------------------------------------|
| Claude Code   | Show code in non-blocking view                   |
| CI systems    | Print source during failure/debugging            |
| Devs w/scripts| A safe, pretty `cat` for code output             |

---

## 7. Technical Architecture

- **Language:** Rust
- **Highlighting:** Tree-sitter or Syntect
- **Output:** Terminal ANSI, plain text, or JSON
- **CLI Parsing:** `clap`

---

## 8. Risks and Mitigations

| Risk                  | Mitigation                  |
|------------------------|-----------------------------|
| Blocked I/O            | Force streaming + buffering |
| Memory overload        | Enforce limits              |

---

## 9. Milestones

| Milestone           | Date      |
|---------------------|-----------|
| MVP core viewer     | Week 1    |
| Syntax highlighting | Week 2    |
| JSON support        | Week 3    |
| Claude test         | Week 4    |
| v0.1 release        | Week 5    |

---

## 10. Inspiration

- [`sharkdp/bat`](https://github.com/sharkdp/bat) — inspiration but heavier
- Claude & Gemini — agents that need clean, controlled output
- Unix tools like `cat`, `less`, and `ripgrep`

---

## 11. License

MIT or Apache 2.0

---

## 12. Future Ideas

- `--format=json+tokens`
- WASM/HTTP mode for web use
- Claude plugin wrapper