Skip to content
fsuite

First Contact

FIRST CONTACT Ten minutes from install to "I get it"
Prereqfsuite installed
Time~10 min
Outputworking mental model
Nextreal investigation

You’ve just installed fsuite. Here’s the shortest path to understanding what it actually does. Run these in order on any project you have on disk.

1. Load the mental model

Section titled “1. Load the mental model”
Terminal window
fsuite

fsuite itself is the suite-level guide. It prints the chain, the discipline, and the tool list in one shot. Read it once. This is the same content you’ll find on the Mental Model page — same source, different surface.

2. Scout any project

Section titled “2. Scout any project”
Terminal window
cd /path/to/any/project
ftree --snapshot -o json .

ftree returns the full tree AND recon data (sizes, types, flags) in one call. Note how it caps output automatically — no 10,000-line floods. The --snapshot mode is what you want for an agent’s “first look” because it gets the recon inventory plus the tree excerpt in a single envelope.

ftree --snapshot · recon + tree in one call 410ms
ftree("." | mode: "snapshot")
  └─ Snapshot(./, depth=3)
     12 directories, 87 files
·
     src/                       —    42 files
     tests/                     —    12 files
     docs/                      —    8 files
     node_modules/              —    [excluded]
     dist/                      —    [excluded]
·
     next → fsearch // narrow files  |  fcontent // narrow content
·
Section titled “3. Run a one-shot search”
Terminal window
fs "TODO" --scope '*.py'

fs auto-classifies your query. Given a string + glob scope, it routes to content search. Given a path glob, it routes to file search. Given a code identifier, it routes to symbol search. One call instead of three.

The next_hint line at the bottom of every fs response tells you the strongest follow-up. Take the hint — it’s drawn from fmetrics combo data.

4. Map a file before reading it

Section titled “4. Map a file before reading it”
Terminal window
fmap src/some_file.py

fmap lists the symbol skeleton — functions, classes, imports, constants — with line numbers. You’ll know the structure before opening the file. For a 600-line module, this is ~50 lines of output instead of 600. That’s the keystone — see the Mental Model for why.

5. Read exactly one function

Section titled “5. Read exactly one function”
Terminal window
fread src/some_file.py --symbol name_of_function

fread reads exactly the function you asked for. Not the file. Not a guess. The function. If the symbol is ambiguous (multiple matches), fread errors explicitly — it doesn’t pick one for you.

When you don’t know the symbol name yet but have a line number from fmap:

Terminal window
fread src/some_file.py -r 120:150

6. Open a case

Section titled “6. Open a case”
Terminal window
fcase init first-contact --goal "Explore fsuite on this project"
fcase note first-contact --body "Scouted, mapped, read one function"
fcase resolve first-contact --summary "Got the vibe. Moving on."

fcase preserves investigation state across sessions. Your notes survive context compaction and you can re-load them with fcase list next time. This is the most underrated tool in the suite — when an agent comes back tomorrow, fcase is what makes it pick up where you left off instead of starting over.

What you should notice

Section titled “What you should notice”
SignalWhy it matters
Every output is cappedNo flood, ever. The agent’s context window stays clean.
-o json works on every toolProgrammatic parsing is first-class, not an afterthought.
-q exists for silent existence checksUseful in shell scripts and conditional chains.
Several commands return next_hintThe toolchain tells you what to call next. Take the hint.
fmap and fread --symbol are not in any other CLIThis is the gap fsuite was built to fill.

What to do next

Section titled “What to do next”