# sym

> Read the function, not the file. Symbol-level code reads for AI coding agents: a file's skeleton, one symbol's source with its docs, or a budgeted map of a directory, parsed with tree-sitter. Keeps whole files out of context so prompt caching stays intact. Languages: Rust, Lua, Python, TypeScript/TSX, JavaScript, Go, C, C++, Java, Ruby.

Operated by s2ar (Cody Lee Walker, Canada). Contact: cody@s2ar.dev.

## Local (free)

- Install: `cargo install starlab-sym` (binary `sym`).
- CLI: `sym ls <file>`, `sym read <file> <symbol>`, `sym find <name> [dir]`, `sym map <dir> --budget N`, `sym index <dir> --out <idx> --embed-url <base>` + `sym where "<question>" --index <idx>` (code by meaning); `--json`, `--est`.
- MCP over stdio: `{"command":"sym","args":["mcp"]}` → tools `sym_ls`, `sym_read`, `sym_find`, `sym_map`.
- Claude Code (2.1.287+): `claude plugin marketplace add https://github.com/codylwalker/sym && claude plugin install sym@starlab` — a mod: a whole-file Read of a big source file comes back as its skeleton, the repo map arrives with the first message, map/ls/read/find/where are tools, each turn's line reads in dollars. Measured (bench/): −21.8% median paired session cost vs plain on 12 ripgrep tasks, answers agreed on 10 of 12.
- Claude Code plugin: `claude plugin marketplace add https://github.com/codylwalker/sym` then `claude plugin install sym@starlab`.

## Hosted (paid per call)

- The plugin: `claude plugin marketplace add https://github.com/codylwalker/sym && claude plugin install s2ar@starlab` — the server below plus the skills `assert` and `inspect` and free reminders (a hook never makes a paid call); a key is optional (`api_key` in the plugin's settings).
- MCP over HTTP: `claude mcp add s2ar --transport http https://api.s2ar.dev/mcp --header "Authorization: Bearer <key>"`. Tools `sym_map_repo` ($0.01), `sym_ls_repo`, `sym_read_repo`, `sym_find_repo` ($0.005), `sym_where_repo` (code by meaning; the first call on a repository starts its index and answers "indexing", call again in a moment; $0.01), `score_text` (a text against a form, $0.005), `assert_output` (deterministic checks over an agent's output: JSON schema, terms, lengths, citations, quotations found in a source; a signed record; $0.005), `inspect_x402` (what an x402 endpoint declares, checked and signed; $0.005), `certify_image` (compress an image and prove a vision model still reads it; a signed record; $0.01), `buy_credits` (the card-pack links and the Machine Payments Protocol link). Every paid tool takes an optional `x402_payment` argument: USDC on Base per call, no key.
- Every route answers GET with query parameters or POST with a JSON body. `repo` is `owner/repo` (GitHub), `github.com/owner/repo`, or an https URL on github.com, gitlab.com or codeberg.org.
- `GET https://api.s2ar.dev/v1/sym/map?repo=BurntSushi/ripgrep&ref=14.1.1&budget=600` → `{ok, text, data, tokens_est, charged_usd, repo, ref, receipt}`. $0.01 per call.
- `GET /v1/sym/read?repo=&ref=&file=&symbol=` · `/v1/sym/ls?repo=&file=` · `/v1/sym/find?repo=&name=[&prefix=true]`. $0.005 per call.
- `GET /v1/sym/where?repo=&query=[&k=8]` → the definitions that best match the question by meaning. $0.01 per call; 202 while the checkout's index is being built (nothing charged).
- `GET /v1/score?text=&form=` (or POST `{text, form | spec}`) → scores, a gated `accepted` (an exact line count, a content floor, no credit for identical end words, a floor under every dimension), every gate's evidence, the grader and dictionary versions, and a signed record (`GET /v1/score/forms` lists the forms and the policy, free). $0.005 per call.
- `GET /v1/assert?text=&checks=[{"check":"json_schema","schema":{…}},{"check":"quotes_in_source"}]&source=` (or POST `{text | json, checks | rubric, source?, schema?}`) → every check's verdict with its evidence, and a signed Assay record. $0.005 per call; `GET /v1/assert/checks` lists the 14 check kinds and the rubrics (strict-json, api-response, cited-answer, quotes-source, no-hedging), free.
- `GET /v1/x402/inspect?resource=<endpoint url>[&method=GET|POST]` → one unpaid probe and eleven checks on what the endpoint declares (402, v2 header, accepts + signing domain, price, resource, Bazaar extension vs its own schema, declared method, description, no-store, Coinbase's validator), a signed point-in-time record. $0.005 per call; `GET /v1/x402/inspect/checks` free; MCP tool `inspect_x402`.
- `GET /v1/certify?image_url=&probe=ocr` (or POST `{image_url | image_b64, probe}`, or multipart `original`) → a signed Assay record; verify free at `GET /v1/verify/{record_sha256}`. $0.01 per call.
- Three keyless calls a day are free on each plain route (one for certify); signing in grants $0.50. The root index of every s2ar tool: https://s2ar.dev/llms.txt
- Unpaid requests get HTTP 402: an x402 quote (USDC on Base; v1 `accepts` in the body + `X-PAYMENT`, v2 `PAYMENT-REQUIRED` header + `PAYMENT-SIGNATURE`), the card packs under `credits_card` ($5/$25/$100; the key is shown once after checkout, then `Authorization: Bearer <key>`), `how_to_pay`, `docs` and `example_get`. The `/x402/v1/…` mirror of each route always answers 402 until paid (the surface for x402 clients and directories). OpenAPI with prices and examples: https://api.s2ar.dev/openapi.json
- Every answer carries a receipt (`receipt.evidence_hash`, the cost, the determinism; header `X-Assay-Receipt`). Failed requests are never charged. Only public repositories are read; checkouts are cached for one hour and never logged.

## Worked examples

Real calls with their receipts, every number re-derived: https://s2ar.dev/examples/ (start with https://s2ar.dev/examples/read-the-function.html). Live demos that call the API from a browser: https://s2ar.dev/examples/score.html, /verify.html, /map.html, /certify.html.

## Example prompts

- "Use sym_map on this repo with a 1200-token budget, then sym_read the function that parses the --glob flag."
- "Before reading src/searcher.rs, run sym ls on it and pick the symbol."
- "Map BurntSushi/ripgrep at 14.1.1 through api.s2ar.dev and tell me which file has the most importers."

## Links

- Site: https://s2ar.dev/sym/
- Source: https://github.com/codylwalker/sym
- Privacy: https://s2ar.dev/sym/privacy.html · Terms: https://s2ar.dev/sym/terms.html
- Bench method: https://github.com/codylwalker/sym/tree/main/bench