Skip to content
fsuite

🔀 fs

Universal search orchestrator — auto-routes to the right fsuite tool

Section titled “Universal search orchestrator — auto-routes to the right fsuite tool”

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

fs Unified search orchestrator · the front door
RoleRECON
Chain position1 (entry)
Auto-routes tofsearch · fcontent · fmap
Intent modesauto · file · content · symbol · nav

fs is the meta-tool — feed it any query and it classifies the intent (filename pattern, in-file content, symbol name, or path navigation), builds the right chain of underlying tools, and returns ranked, enriched hits with a next_hint for follow-up.

When in doubt, start here. When you know the exact tool you need, skip it.

Canonical chains

Section titled “Canonical chains”

fs is the entry point of every recon chain. It does not pipe — it returns final ranked hits with a next_hint you call next.

Terminal window
# Symbol scout — returns hits + next_hint to fread the right block
fs "renderTool"


# Filename intent forced — looks for files literally named like *.log
fs --intent file "*.log" /var/log


# Scoped symbol search — narrow to TypeScript only
fs --scope "*.ts" McpServer


# Pipe to jq — JSON mode auto-engages on pipe
fs -o json "*.rs" | jq '.hits'

Terminal sample

Section titled “Terminal sample”
fs(teleport) · symbol intent · 328ms · ~80 tokens
● Now let me find the teleport code:
·
fs(teleport | path: "/home/user/Projects/nightfox/src" | intent: "symbol" | scope: "*.ts")
  └─ symbol (high) via fsearch → fcontent → fmap
     explicit intent=symbol
     50 candidates, 1 enriched, 328ms
·
     nightfox/src/claude/command-parser.ts (1 matches)
       50  · '/teleport'  // Move session to terminal (forked)
·
     next → fread(path: "/home/user/.../command-parser.ts", around: teleport)
·

Help output

Section titled “Help output”

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

fs — unified search meta-tool


USAGE
  fs [OPTIONS] <query> [path]


OPTIONS
  -s, --scope GLOB     Glob filter for file narrowing (e.g. "*.py")
  -i, --intent MODE    Override: auto|file|content|symbol|nav (default: auto)
  --config-only        Narrow file/nav searches to config-like roots under [path]
  -c, --compact        Nav-only compact JSON: relative paths, no next_hint
  -o, --output MODE    pretty|json (default: pretty for tty, json for pipe)
  -p, --path PATH      Search root (default: .). Overrides positional [path].
  --max-candidates N   Override candidate file cap (default: 50)
  --max-enrich N       Override enrichment file cap (default: 15)
  --timeout N          Override wall time cap in seconds (default: 10)
  -h, --help           Show help
  --version            Show version


DESCRIPTION
  Classifies your query as file / symbol / content intent, then builds
  and runs the optimal fsuite tool chain. Returns ranked hits with
  enrichment and a next_hint for follow-up refinement.


EXAMPLES
  fs "*.py"                         # file search — glob
  fs renderTool                     # symbol search — camelCase detected
  fs "error loading config" src/    # content search — multi-word
  fs -s "*.ts" McpServer            # symbol search, scoped to .ts files
  fs -i symbol authenticate         # force symbol intent
  fs -i nav docs                    # explicit path navigation
  fs --config-only opencode.json ~  # fast config-file lookup under HOME
  fs -i nav -c docs                 # nav-only compact JSON/result shaping
  fs -o json "*.rs" | jq '.hits'    # JSON output for piping

See also

Section titled “See also”