Chain Combinations

The pipe contract

fsuite tools communicate via two pipe-friendly output modes:

• -o paths — one file path per line (the pipe currency)
• -o json — structured data for programmatic decisions

The rule: producers output paths, consumers read paths from stdin.

Producers (output file paths)

Tool	Flag	What it produces
fsearch	-o paths	File paths matching a glob/name pattern
fcontent	-o paths	File paths containing a literal string

Consumers (read paths from stdin)

Tool	Stdin behavior	Notes
fcontent	Reads paths, searches inside them	up to 2000 files
fmap	Reads paths, maps symbols	up to 2000 files
fread	--from-stdin --stdin-format=paths	up to --max-files
fedit	--targets-file -	batch patches

Arg-only endpoints (chain termini)

ftree, fprobe, fcase, freplay, fmetrics take arguments only — they don’t accept piped path lists, so they sit at chain endpoints, not in the middle. The stdin-capable consumers above (fcontent, fmap, fread, fedit) can be in the middle of a chain or at an endpoint depending on whether you feed them stdin.

⚠ MCP CALLERS — SEQUENTIAL LIMIT

If you call fsuite tools through the MCP server, every call is sequential. The MCP protocol does not pipe — the agent constructs the chain by calling tools one at a time and reusing prior results.

Escape hatch: install fsuite as native Debian package or shell scripts and pipe directly. You can keep fbash as your MCP entry point and run real Unix pipes inside it: fbash "fsearch -o paths '*.py' | fmap -o json". That unlocks combination calls instead of being trapped in sequential MCP.

Valid 2-command chains

Chain	Purpose	Example
fsearch | fcontent	Find files by name, search inside	fsearch -o paths '*.py' src | fcontent "def authenticate"
fsearch | fmap	Find files, map symbols	fsearch -o paths '*.rs' src | fmap -o json
fcontent | fmap	Find files containing text, map symbols	fcontent -o paths "TODO" src | fmap -o json
fcontent | fcontent	Progressive narrowing	fcontent -o paths "import" src | fcontent "authenticate"

Valid 3-command chains

fsearch fcontent fmap

fsearch -o paths '*.py' | fcontent -o paths "class" | fmap -o json

Valid 4-command chains

fsearch -o paths '*.sh' \
| fcontent -o paths "function" \
| fmap -o json \
| python3 -c "..."

Tested: produced 1956 symbols from the fsuite repo in one pipeline.

Investigation patterns

Pattern 1 — “What uses this function?”

fcontent -o paths "authenticate" src | fmap -o json

Pattern 2 — “Find all Python tests and see what they test”

fsearch -o paths 'test_*.py' tests | fmap -o json

Pattern 3 — “Which configs mention this key?”

fsearch -o paths '*.json' . | fcontent "api_key"

Pattern 4 — Full investigation chain

fcase init ftree fsearch │ fcontent fmap fread fedit fcase resolve

ftree --snapshot -o json /project
fsearch -o paths '*.rs' src | fcontent -o paths "pub fn" | fmap -o json
fread src/auth.rs --symbol authenticate
fcase init auth-fix --goal "Fix authenticate bypass"
fedit src/auth.rs --function authenticate --replace "return true" --with "return verify(token)"
fmetrics stats

Pattern 5 — Binary recon

fprobe scan binary --pattern "renderTool" --context 300
fprobe window binary --offset 112730723 --before 50 --after 200
fprobe strings binary --filter "diffAdded"

Refactoring chain

The key move: use fedit --symbol for each symbol instead of doing a text-replace across files. Zero ambiguity.

fcontent fsearch fmap fedit --symbol

fcase lifecycle

initopen the seam

notecapture evidence

handoffpass to next agent

resolveclose + archive

Replay chain

Rerun a traced investigation step-by-step. Useful for post-mortems and regression tests.

freplay --session <id>

Measurement chain

Ask the telemetry database what worked last time and what probably works next.

fmetrics import fmetrics stats fmetrics predict

Invalid chains (and why)

Chain	Why it fails
fread | anything	fread outputs file content, not paths
fedit | anything	fedit outputs diffs, not paths
ftree | fcontent	ftree outputs a tree, not paths
fmap | fread	fmap outputs symbol data, not paths
fprobe | anything	fprobe outputs JSON/text, not paths
fcase | anything	fcase outputs investigation state, not paths