Skip to content
fsuite

🗺️ fmap

Symbol cartography — functions, classes, imports, constants

Section titled “Symbol cartography — functions, classes, imports, constants”

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

fmap Symbol cartography · the keystone — the gap native CLI doesn't fill
RoleKEYSTONE
Chain position4 (bridge to read)
Pipeconsumer (stdin paths)
Languages50+

fmap is the headliner. Native CLI has nothing like it. Given a file or a directory, fmap extracts the structural skeleton — every function, class, import, type, constant — with line numbers, in seconds, across 50+ languages.

Why it matters: an agent that runs fmap first reads ~1% of a file’s bytes and learns what’s in it. Then it picks the symbol it actually wants and freads exactly that block. Compare that to cat-ing a 3000-line module to figure out which function to look at.

This is the keystone of every investigation chain.

Canonical chains

Section titled “Canonical chains”
Terminal window
# Map a single file
fmap /project/src/auth.py


# Map every source file in a project
fmap /project


# Filter by symbol-name match — surgical
fmap --name authenticate -o json /project


# Pipe currency — fsearch produces, fmap consumes
fsearch -o paths '*.py' /project | fmap -o json


# Filter symbol type
fmap -t function /project
fmap -t class /project


# Triple chain — narrow text first, then map structure
fcontent -o paths "TODO" /project | fmap -o json


# Followed by surgical fread
fmap --name handleRequest -o json /project | jq '.symbols[0]'
fread /project/src/server.ts --symbol handleRequest

Terminal sample

Section titled “Terminal sample”
fmap(reconciler.ts) · 27 symbols · typescript ~98K tokens saved vs cat
fmap(path: "/home/user/Projects/brane-code/src/ink/reconciler.ts")
  [ 27 symbols | typescript ]
     3    import     import { appendFileSync } from 'fs'
     4    import     import createReconciler from 'react-reconciler'
     5    import     import { getYogaCounters } from 'src/native-ts/yoga-layout/index'
     28   import     import applyStyles, { type Styles, type TextStyles } from './styles'
     60   type       type AnyObject = Record<string, unknown>
     92   function   const diff = (before: AnyObject, after: AnyObject): AnyObject
     95   function   const cleanupYogaNode = (node: DOMElement | TextNode): void
     114  function   function setEventHandler(node: DOMElement, key: string, value: unknown)
     158  function   export function getOwnerChain(fiber: unknown): string[] {
     191  constant   const COMMIT_LOG = process.env.CLAUDE_CODE_COMMIT_LOG
     205  export     export function recordYogaMs(ms: number): void
     217  function   export function resetProfileCounters(): void
·

Help output

Section titled “Help output”

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

fmap — code cartography: extract structural skeleton from source files (agent-friendly)


USAGE
  fmap [OPTIONS] [path]


MODES
  1) Directory mode:
     fmap /project
     - Scans all recognized source files under /project


  2) Single file mode:
     fmap /project/file.js
     - Extracts symbols from one file


  3) Piped file-list mode (best with fsearch):
     fsearch -o paths '*.py' /project | fmap -o json
     - Reads file paths from stdin


OPTIONS
  -o, --output pretty|paths|json
      pretty: human-readable grouped by file (default)
      paths:  unique file paths with symbols, one per line
      json:   structured JSON with symbol metadata


  -m, --max-symbols N
      Cap total symbols shown. Default: 500


  -n, --max-files N
      Cap files processed. Default: 500 (directory), 2000 (stdin)


  -L, --lang <lang>
      Force language (auto-detect by default).
                   Supported: python, javascript, typescript, kotlin, swift, rust, go, java,
                   c, cpp, ruby, lua, php, bash, dockerfile, makefile, yaml, toml, ini, cuda,
                   mojo, hcl, protobuf, graphql, csharp, zig, env, compose, packagejson,
                   gemfile, gomod, requirements, sql, css, html, xml, perl, rlang, elixir,
                   scala, zsh, dart, objc, haskell, julia, powershell, groovy, ocaml,
                   clojure, wasm, markdown


  -t, --type <type>
      Filter symbol types: function, class, import, type, export, constant


  --name <symbol>
      Rank/filter extracted symbols by exact then substring symbol-name match.


  --no-imports
      Skip import lines. Overridden by -t import.


  --no-default-ignore
      Disable built-in ignore list in directory mode.


  -q, --quiet
      Suppress header lines in pretty mode.


  --project-name <name>
      Override project name in telemetry.


  --self-check
      Verify grep is available.


  --install-hints
      Print how to install grep and exit.


  -h, --help
      Show help and exit.


  --version
      Print version and exit.


  SUPPORTED LANGUAGES
    Python, JavaScript, TypeScript, Kotlin, Swift, Rust, Go, Java, C, C++,
    Ruby, Lua, PHP, Bash/Shell, Dockerfile, Makefile, YAML, Markdown


HEADLESS / AI AGENT USAGE
  fmap -o json /project
  fmap --name authenticate -o json /project/src
  fsearch -o paths '*.py' /project | fmap -o json
  fmap -t function -o json /project

See also

Section titled “See also”