symapper / reference

Command reference

Choose your focus. Set a budget. Read the map.

npx symapper .

Install

npm

Needs Node 18 or newer and git.

npx symapper <repo>
npm i -g symapper

Prebuilt binaries: macOS arm64/x64 and Linux x64/arm64 (static musl). Windows is not supported; use the Linux package in a Linux environment such as the Windows Subsystem for Linux.

Release archives

Download the archive and SHA256SUMS from GitHub Releases. Archives are named symapper-<version>-<target>.tar.gz, with target aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-musl or aarch64-unknown-linux-musl.

Verify, extract, and put symapper on your PATH:

sha256sum -c SHA256SUMS --ignore-missing         # Linux
shasum -a 256 -c SHA256SUMS --ignore-missing     # macOS

If macOS blocks the binary, run xattr -d com.apple.quarantine symapper.

From source

Needs Rust 1.90 or newer, git and a C compiler. Not on crates.io.

cargo install --git https://github.com/viewtools-app/symapper --tag v0.1.0 --locked
cargo install --path . --locked    # from a clone

Flags and focus

symapper <repo> [--focus <path|ident>] [--tokens N] [--exclude <glob>] [--no-cache]
symapper -V | --version
symapper -h | --help

<repo> is a git work tree or a directory inside one.

FlagMeaning
--focus <path|ident>Repeatable path or identifier used to personalize ranking
--tokens NPositive token budget; default 1500
--exclude <glob>Repeatable glob matching repository-relative paths
--no-cacheDisable cache reads and writes
-V, --versionPrint the version
-h, --helpPrint help

Choosing focus

  • Focus paths for files the task touches; identifiers or plain words for names in the task.
  • Budget: 500-1500 tokens for a task brief, 3000-4000 to orient in a new repository. Tokens are estimated as Unicode characters / 4, layout included.
symapper ./example-repo --focus src/lib.rs --focus calculate_total --tokens 1000
symapper ./example-repo --exclude 'tests/**' --exclude 'vendor/**' --no-cache

A focus path may be repository-relative (including ./), relative to the current directory, or absolute inside the repository. Only mapped source files match, and a tracked symlink matches by its own path. A matched file also adds its stem as a focus identifier. Other values are identifiers. Explicit focus files are omitted from the map; identifier-matched files can still appear.

Output layout

  • Sorted names of important root files (README, LICENSE, manifests, build and compose files, direct .github/workflows/*.yml and .forgejo/workflows/*.yml).
  • path: blocks with definition and enclosing scope lines, ... for gaps, lines cut at 100 characters.
  • Remaining source files by name only, by descending focus score, then file rank, then path.

Paths are relative to the repository root. The budget covers all three parts.

Exit codes

CodeMeaning
0Success, including help/version and nothing parsed
1Runtime or I/O failure, such as failing to start git
2Invalid arguments, invalid exclude glob, or a path that is not a git work tree

If no supported source file could be parsed, stdout is empty and stderr says symapper: no supported source files. Unreadable or vanished files are skipped with a stderr note; cache write failures warn without failing the map.

Using it with an agent

Run symapper once at the start of a task. It is a starting point, not a replacement for search.

  1. Pick focus words from the task: file names, identifiers, key words.
  2. Run the map once.
  3. Read the top files.
  4. Still search the task's identifiers with rg or grep, and read their callers, before editing.

The map shows signatures, not matched lines. Static parsing misses dynamic calls, re-exports and macros, so it can leave out files.

Paste this into an agent instruction file such as AGENTS.md. With npm i -g symapper, drop npx.

Before exploring the repository, run:
npx symapper . --tokens 1500 --focus <word from the task> --focus <another word>
The map is a starting point: read what it points to, then still search the code (rg/grep).
It can miss files.

Ranking

Graph

git ls-files lists tracked files; those in supported languages remain after --exclude. Binary files, files over 1 MiB and non-UTF-8 paths are skipped. Tree-sitter queries find where each name is defined and used; a file points to the files that define the identifiers it uses. Personalized PageRank runs over this graph. Without focus it is plain PageRank and no file contents are read.

Focus matching

  • Terms and names split on underscores, hyphens, dots, slashes, whitespace and case boundaries (SheetLayout -> sheet, layout; HTTPServer -> http, server), then lowercase. Digits stay in their word.
  • A term matches a contiguous run of name words. Symbols receive x10 for a case-insensitive whole-name match, otherwise x3 for a word-run match, never both.
  • Each distinct term contributes 1.0 for a match in a directory component, file stem or definition name, including exact full-path and file-name matches. Thus push matches every file under push/.
  • Otherwise a term contributes 0.75 for a content-only match, unless it occurs in more than half the mapped files.
  • Content matching covers identifiers, comments and strings of mapped source files, never README, Markdown, YAML or JSON. Content splits on every non-alphanumeric character with the same case rules; matches can cross punctuation and lines. Stems added from explicit focus files never match content.
  • Explicit focus files score the number of terms, at least one.

Ordering and budget

  • Files with a higher focus score come first, each led by its best-scoring definition (at most one promoted per file). Other definitions keep rank order.
  • The renderer trims signatures to --tokens; leftover room lists other file names.

Credits

The method follows Aider's repository map. Parsing uses tree-sitter. Ranking is PageRank (Page, Brin et al., 1999), personalized as in Haveliwala, "Topic-Sensitive PageRank" (2002).

Cache and safety

Cache

By default, with SYMAPPER_CACHE_DIR unset or empty, tags are cached at <git common dir>/symapper-cache.bin. Set SYMAPPER_CACHE_DIR to an absolute path of an existing directory to use <dir>/symapper-<hash>.bin. The hash is 16 lowercase hex digits of FNV-1a-64 over the canonical git common directory path bytes, so repositories can share one directory.

symapper never creates the directory. A relative path or a path that is not an existing directory prints one stderr note and disables cache reads and writes for that run, without falling back to the git directory. --no-cache always disables reads and writes. Atomic writes use a temporary file beside the selected cache file.

Unchanged relative path, nanosecond mtime and size reuse tags. Crate/tag-schema versions, queries and scope kinds invalidate the schema; corrupt or incompatible caches are ignored with a note and rebuilt. Gone entries are dropped; excluded entries remain cached. Linked worktrees share this cache, so equal path, mtime and size with different contents can reuse stale tags.

Safety

  • symapper makes no network requests; npx downloads the package on first use.
  • The repository is read-only except for the cache and its temporary file.
  • Only tracked files are considered. Canonical targets must be tracked, inside the work tree and outside the git common directory.
  • Non-UTF-8 paths, sources over 1 MiB and binary sources (NUL in the first 8 KiB) are skipped.

No repository code or hooks run. git runs only rev-parse and ls-files, with the fsmonitor hook disabled and GIT_DIR-style override variables removed. Git still reads repository configuration to discover and list files.

Languages

Extensions are case-sensitive.

LanguageExtensions
TypeScript.ts, .mts, .cts
TSX.tsx
JavaScript / JSX.js, .jsx, .mjs, .cjs
Python.py, .pyi
Go.go
Rust.rs
Swift.swift

Limits

  • Static tags miss dynamic calls, re-exports and macros, and can join unrelated same-name symbols.
  • Ranking weights may need tuning for a particular task.
  • Token counts are estimates rather than model-specific tokenizer counts.
  • Only tracked files in supported languages are mapped; unsupported languages have no definition map. New files must be git added to appear.
  • Content matching is case-insensitive for ASCII letters only.
  • Linked worktrees can reuse stale tags when path, size and nanosecond mtime coincide despite different contents; use --no-cache for a fresh run.