Skip to content
fsuite

📖 fread

Budgeted reading with symbol + line-range resolution

Section titled “Budgeted reading with symbol + line-range resolution”

fread is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.

fread Budgeted reading · symbol & line-range resolution · PDF + image media
RoleREAD
Chain position5 (read)
Pipeconsumer (--from-stdin)
MediaPDF · image · diff

fread is cat with a brain. It can read a whole file (uncapped by default — you control budget), an exact line range, the first N or last N lines, context windows around a literal pattern, or one specific symbol resolved by name in a file or directory.

It also reads media: PDF text extraction, PDF page rasterization, image base64 with auto-resize, and unified-diff hunks from git pipe. The token-budget flags (--max-lines, --max-bytes, --token-budget) cap output before it hits the agent’s context.

Canonical chains

Section titled “Canonical chains”
Terminal window
# Read exactly one symbol — no scrolling, no guessing
fread /project/src/auth.py --symbol authenticate


# Resolve a symbol from a directory scope
fread /project/src --symbol authenticate -o json


# Precise line range
fread /project/src/server.py -r 120:220


# Context window around a pattern
fread /project/src/auth.py --around "def authenticate" -B 5 -A 20


# Pipe currency consumer — fsearch produces, fread consumes first 5
fsearch -o paths '*.py' /project \
  | fread --from-stdin --stdin-format=paths --max-files 5 -o json


# Read git diff context
git diff | fread --from-stdin --stdin-format=unified-diff -B 3 -A 10


# PDF and image reading
fread invoice.pdf
fread paper.pdf --render --pages 1:5
fread screenshot.png

Terminal sample

Section titled “Terminal sample”
fread(--around teleport) · 66 lines · -829 tokens vs full read
fread(/home/user/Projects/nightfox/src/discord/commands/teleport.ts | head: 80)
  [ 66 lines | -829 tokens ]
     1  import { ChatInputCommandInteraction } from 'discord.js';
     2  import { discordChatId } from '../id-mapper.js';
     3  import { sessionManager } from '../../claude/session-manager.js';
     4  import { config } from '../../config.js';
     5  import path from 'path';
     6
     7  export async function handleTeleport(interaction: ChatInputCommandInteraction): Promise<void> {
     8     const chatId = discordChatId(interaction.user.id);
     9
     10 // Try active in-memory session first, then fall back to most recent from history
     11 let session = sessionManager.getSession(chatId);
     12 if (!session) {
     13    session = sessionManager.resumeLastSession(chatId) ?? undefined;
     14 }
·

Help output

Section titled “Help output”

The content below is the live --help output of fread, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.

fread — budgeted file reading with line numbers, token estimates, and pipeline integration.


USAGE
  fread <file>                                   Read file (uncapped by default)
  fread <file> --symbol authenticate             Read one exact symbol block
  fread <dir> --symbol authenticate              Resolve one exact symbol within a directory scope
  fread <file> -r 120:220                        Line range
  fread <file> --head 50                         First N lines
  fread <file> --tail 30                         Last N lines
  fread <file> --around-line 150 -B 5 -A 10      Context around line
  fread <file> --around "pattern" -B 5 -A 10     Context around literal pattern
  fread --paths "~/.codex/auth.json,~/.config/codex/auth.json"   Try paths in order
  ... | fread --from-stdin --stdin-format=paths
  git diff | fread --from-stdin --stdin-format=unified-diff -B 3 -A 10


  fread <image>                                  Read image with auto-resize (PNG/JPEG/GIF/WEBP)
  fread <pdf>                                    Extract PDF text (default mode)
  fread <pdf> --render --pages 1:5               Rasterize PDF pages to images
  fread <pdf> --meta-only                        PDF metadata only


OPTIONS
  --paths P1,P2,...           Comma-separated file paths to try in order (first existing wins)
  -r, --lines START:END       Line range (1-based, inclusive)
  --head N                    Read first N lines
  --tail N                    Read last N lines
  --around-line N             Context around specific line number
  --around PATTERN            Context around first literal pattern match
  --all-matches               With --around: include all matches up to caps
  --symbol NAME               Read exactly one exact symbol match within file or directory scope
  -B, --before N              Lines before (default 5)
  -A, --after N               Lines after (default 10)
  --max-lines N               Cap total emitted lines (0/default = uncapped)
  --max-bytes N               Cap total emitted bytes (0/default = uncapped)
  --token-budget N            Cap by estimated tokens (conservative bytes/3)
  --no-truncate, --full       Disable line, byte, and token caps
  --max-files N               Cap files from stdin paths mode (default 10)
  --from-stdin                Read input from stdin
  --stdin-format FMT          Required with --from-stdin: paths|unified-diff
  --force-text                Read even if binary is detected
  -o, --output FMT            pretty (default), json, paths
  -q, --quiet                 Suppress pretty headers
  --project-name NAME         Override telemetry project name
  --self-check                Verify dependencies
  --install-hints             Print install commands
  --version                   Print version
  -h, --help                  Show help


MEDIA OPTIONS (image + PDF reading)
  --render                    PDF: render pages as images instead of extracting text
  --pages START:END           PDF: page range (1-based, inclusive)
  --meta-only                 Return metadata only (no body / base64)
  --no-resize                 Image: emit raw base64 without auto-resize
  --max-pages N               PDF render: raise 10-page cap
  --max-tokens N              Image: resize-loop token budget (default 6000)
  --no-ingest                 Skip ShieldCortex memory ingest for this read


NOTES
  Budget precedence: token_budget > max_bytes > max_lines
  --symbol is strict: exactly one exact symbol match succeeds; ambiguous or missing matches fail
  --stdin-format=unified-diff reads NEW-side hunk ranges from +++ path and @@ +start,count

See also

Section titled “See also”