fsuite

FIELD DISPATCHEP 0 · ORIGINSSTATUS: DRONES OPERATIONALv2.4.0

14tools

516tests

50languages

MCPnative

0flooded contexts

What if the agent had real reconnaissance instead of a flashlight?

The native filesystem tools every coding agent reaches for — grep, find, cat, sed, bash — were built for humans, on terminals, in 1979. They do not cap their output. They do not rank their results. They do not know what a token costs.

fsuite does. Fourteen tools, one mental model: recon → read → edit → replay → measure. Designed for headless agents, kept human-friendly so the engineer holding the leash never gets lost either.

The four things it fixes

Recon without floods

fs, ftree, fsearch, fcontent return ranked, capped, structured results. No 10,000-line grep dumps. No walking entire directory trees to find one file.

Reading without guessing

fread --symbol NAME reads exactly one function by name. fread --lines 120:150 reads an exact range. fmap extracts the symbol skeleton before you even open a file.

Editing without ambiguity

fedit --lines 120:124 replaces exact line ranges. fedit --function_name foo scopes edits to a symbol without needing huge unique context strings. No more failed matches on whitespace drift.

Continuity across sessions

fcase is an investigation ledger. Track findings, evidence, and handoff state so the next agent (or the next you) starts with context, not from zero.

The chain

The agent only has to remember one flow:

fsftreefsearch │ fcontentfmapfreadfcasefedit

↑ fs auto-routes through fsearch + fcontent — you usually don’t call them by hand↑ fmap is the keystone — symbol cartography is the gap native tools don’t fill

flsfwritefbashfreplayfmetricsfprobe

fls structured ls · fwrite atomic create · fbash budgeted shell · freplay deterministic rerun · fmetrics tool-chain prediction · fprobe binaries

Internalize the discipline →

Native vs fsuite

The same investigation, two tool stacks. fsuite’s columns hand back exactly the slice the agent needs.

grep / find / cat ~12k tokens

$ grep -rn “authenticate” src/
src/auth.py:14:def authenticate(user):
src/auth.py:42:    return authenticate_with_db(user)
src/legacy.py:8:# old authenticate logic, kept for…
src/tests/test_auth.py:3:def test_authenticate_basic():
src/tests/test_auth.py:19:def test_authenticate_invalid():
… (217 more lines)
———————————————————————————
$ cat src/auth.py
# dumps all 480 lines into context

fs / fmap / fread ~480 tokens

$ fs “authenticate” -o json
“intent”: “symbol”,
“hits”: [{ “path”: “src/auth.py”, “line”: 42 }],
“next_hint”: “fread src/auth.py —symbol authenticate”
———————————————————————————
$ fread src/auth.py —symbol authenticate -B 2 -A 12
→ exact 14-line block, nothing else

See it in the wild

A real opening move on a fresh repo. fs auto-classifies. fmap bridges to symbols. fread hands back the exact neighborhood. fcase preserves the seam for the next agent. Four calls.

# 01  Auto-route the opening move
$ fs "renderTool" -o json | jq .
{
  "intent": "symbol",
  "hits": [{ "path": "src/tools/render.ts", "line": 42, "score": 0.97 }],
  "next_hint": "fread src/tools/render.ts --symbol renderTool"
}

# 02  Map the neighborhood before reading
$ fmap -o json src/tools/render.ts | head
→ renderTool        function   line 42
→ resolveContext    function   line 18
→ ToolRenderer      class      line 7

# 03  Read exactly the symbol — no surrounding noise
$ fread src/tools/render.ts --symbol renderTool -B 2 -A 12

# 04  Preserve the seam, hand off to the next agent
$ fcase init render-seam --goal "Trace renderTool denial path"
✓ case opened   ~/.fsuite/fcase.db · session 0xa72f

The fourteen tools

Tool	Purpose
fs	Universal search orchestrator — auto-routes your query to the right tool
ftree	Territory scout — full tree + recon data in one call
fls	Structured directory listing with recon mode
fsearch	File / glob discovery
fcontent	Bounded content search (token-capped ripgrep)
fmap	Symbol cartography — functions, classes, imports, 50 languages
fread	Budgeted reading with symbol & line-range resolution; PDF + image media
fedit	Surgical editing (line-range, symbol-scoped, anchor-based)
fwrite	Atomic file creation
fbash	Token-budgeted shell with classification + session state
fcase	Investigation continuity ledger
freplay	Derivation chain replay
fprobe	Binary / bundle inspection + patching
fmetrics	Telemetry analytics + tool-chain prediction

Why it exists

fsuite was always supposed to be CLI-first. The MCP server came later, the hooks came later, and the whole thing is still catching up to the lightbulb moment that probably should have come first.

“The gap isn’t in any single tool. It’s in the reconnaissance layer. I have no native way to answer the question: ‘What is this project, how big is it, and where should I look first?’”

— Claude Code (Opus 4.5), unprompted self-assessment

Read the full story →