Skip to main content
Glama
README.md
# sangkar

A read-only MCP server over one repository's call graph, and the `sangkar` command that serves the
same seven tools from a shell. It indexes the tree into a SQLite database and answers what changed,
who calls what, what a change reaches, and what the index could not cover. The repository is bound
at startup, so no tool takes a project argument.

## Install

Bun 1.4.4 or newer. The app is a Bun program — `bun:sqlite`, `bun build`, `Bun.spawn` — so Node
cannot run it.

```sh
bun add -g sangkar-mcp@beta   # or: npm i -g sangkar-mcp@beta
```

`0.1.0-beta.0` publishes under the `beta` tag. Pin it explicitly — `latest` on the registry is a
moving target: when npm first claimed this name it created a `0.0.0-stage` holding version that took
`latest`, and the real version took it over on publish, so an untagged install happens to get the
prerelease today. That is a property of the registry's staged-publish flow, not of this package, and
it stops being true as soon as a non-prerelease ships. `sangkar-mcp@beta` is the stable address.

The package ships TypeScript, so the `sangkar` binary runs under Bun through its shebang; the Bun
prerequisite is not optional. Installing creates no database and writes nothing outside Bun's global
directory.

### From a checkout

```sh
bun install
bun link            # puts `sangkar` on PATH
```

`bun link` is the only global step: it registers `bin/sangkar.ts` as `sangkar` and touches nothing
else. Skip it and invoke the entry point directly, which is the same program:

```sh
bun run bin/sangkar.ts status
```

Installing creates no database and writes nothing outside `node_modules`.

## First run

`sangkar index` is the bootstrap: the one command that builds the graph by itself, with no client
attached and no file change needed to start it.

```sh
cd /path/to/repo
sangkar index        # index the tree into <repo>/.sangkar/graph.db
```

It is the same work as the MCP `index` tool, with identical arguments. Until it has published once
there is no store for a tool call to answer from, so every other command answers `bootstrapping`
and exits 1. `status` is the one exception: it prints the single line naming the missing database
and exits 0, because "no index yet" is the fact it exists to report. Once the graph exists, any tool
answers:

```sh
sangkar status
```

The repository is found by walking up from the current directory: the nearest ancestor holding
`.sangkar`, else the nearest holding `.git`, else the current directory itself. `--repo-root`
states it explicitly, which is what a script should do:

```sh
sangkar status --repo-root /path/to/repo
```

## CLI usage

```sh
sangkar <tool> [arguments] [global flags] — the name comes first
```

| Example | What it does |
|---|---|
| `sangkar status` | The five human lines described below. |
| `sangkar status --json` | The same answer as the envelope. |
| `sangkar search 'handleRequest'` | Symbols matching a keyword. |
| `sangkar trace 'db.write' --depth 1 --direction out` | Callees of one symbol, one hop. |
| `sangkar impact` | What the working-tree diff reaches. |
| `sangkar index --mode fast --force` | Force a fast re-index. |
| `sangkar trace --help` | `trace`'s own usage, exit 0. |

Output:

- `status` prints five human lines — the status line, then `project`, `database`, `graph` and
  `health`. On a tree with no index yet it prints the one-line reason instead, and exits 0.
- Every other tool prints one JSON envelope.
- `--json` is accepted by any tool and is the default output for all of them; it is `status` alone
  that swaps the envelope for human lines when the flag is absent.
- `--repo-root <path>` and `--data-dir <path>` are globals: they follow the tool name and may sit
  anywhere among that tool's own arguments, in `--flag value` or `--flag=value` form; `--json` and
  `--help` are globals in the same sense. The name comes first — a global written before it is read
  as the tool name and refused with exit 2.
- `--help` exits 0 with that tool's usage block, or, on a verb, the verb's own usage line:
  `sangkar mcp --help`, `sangkar index --help`, `sangkar worker --help`. It is answered before any
  argument is checked, so it works with a required argument still missing.
- `sangkar index` streams progress as JSON log lines on stderr and exits 0 once it publishes.
  Nothing else reaches stdout.

Exit codes, from the envelope's status: `0` for `ok`, `ambiguous` and `not_found` — a negative
answer is still an answer — `1` for `error` and `bootstrapping`, and `2` for a usage refusal
(unknown tool, unknown option, missing value, bad type). `sangkar index` has two of its own, because
it is the worker rather than a tool call: `2` when nothing changed and there was nothing to publish,
and `75` when another indexer holds the lock.

## MCP

The command a client registers as its stdio server:

```sh
sangkar mcp --repo-root /path/to/repo
```

`--data-dir /path/to/dir` is the optional second flag. stdout carries the MCP protocol and nothing
else; diagnostics are JSON lines on stderr, one record per event.

## The seven tools

| Tool | What it answers |
|---|---|
| `status` | The generation being served, how stale the tree is, per-path coverage and the language census. Call it before saying something does not exist. |
| `summary` | The situation in a few hundred tokens: the working-tree diff (default), the whole repo, or one area, with risk, blast radius and test gaps. |
| `trace` | Callers, callees, implementers, importers and tests for one query, grouped by edge and tier; several matches come back as candidates, not a guess. |
| `search` | Symbols by keyword (BM25) with file:line and in/out degree — locations and shape, not source. |
| `impact` | What a change set reaches: dependents, affected entry points, the tests that cover them, and a risk score; defaults to the working-tree diff. |
| `expand` | More detail for one item from an earlier answer — `members`, `edges`, short `source`, or `coverage`. |
| `index` | Force a full or fast re-index, or repair a graph the watcher could not fix. Not for normal use. |

Registered names are exactly these seven, in this order: no `_tool` suffix, no aliases, and no
eighth name. MCP and the `sangkar` command publish the same surface; the instructions tell an agent
to call `index` only when `status` reports a broken graph.

Six of the seven take an optional `budget` in tokens, defaulted per tool (`status` 800, `summary`
1200, `trace` 3200, `search` 2000, `impact` 2500, `expand` 2500); `index` has none, because a
repair call has no payload worth paging. Above 32000 the call is refused with `budget_too_large`; so
is a budget below the smallest size an answer can take, with a hint naming that floor — one refusal
instead of a payload several times what you asked for.

## `.sangkar`

One directory per working tree, beside the code it describes:

```
<repo>/.sangkar/graph.db          the graph
<repo>/.sangkar/graph.db-wal      WAL sidecars, never committed
<repo>/.sangkar/graph.db-shm
<repo>/.sangkar/write.lock        single-writer flock, outside the database
<repo>/.sangkar/.gitignore        a single `*`, written on first index
```

The data dir carries its own `.gitignore` holding one `*`, so git ignores everything inside without
the repository's tracked `.gitignore` being edited. `.sangkar` is excluded from discovery the way
`.git` is — otherwise each index would index the previous database. One database belongs to one
working tree, including a linked `git worktree`; the database answering the session is always
reported at `status.payload.project.db_path`.

## Moving the data directory

`--data-dir` is the only override; a relative value resolves against the repository root. It exists
because the checkout is not always somewhere you can write:

- **read-only mounts.** A source tree mounted read-only, an image layer, or a CI checkout cannot hold
  `.sangkar/` at all. Indexing into a writable directory leaves the tree byte-for-byte untouched.
- **network filesystems.** SQLite needs working locks and a local filesystem for WAL; NFS, SMB, most
  FUSE mounts and synced folders do not provide that, and a half-checkpointed `graph.db-wal` is a
  corrupt graph. Keep the database on local disk and serve the tree over the mount.

A data dir holding an index of a different tree is refused rather than answered from, so a
mis-pointed override is an error, not a quietly wrong answer.

## Environment

Two settings remain, and both are read from the environment rather than a flag:

| Variable | Default | Meaning |
|---|---|---|
| `SANGKAR_CURSOR_KEY` | empty | HMAC key for pagination cursors, 32 bytes or more; when unset the process generates its own key, so cursors do not survive across invocations — set it to share cursors between processes |
| `SANGKAR_NO_WATCH` | unset | any value stops the watcher; set by tests |

## Distribution

The order is TECH-SPEC.md §15's, and it is deliberate:

1. **Ship the Bun package first.** A `#!/usr/bin/env bun` entry point is a small artifact, needs no
   rebuild per platform, and only requires Bun on the user's machine (102 MB itself). This is the
   route the seven tools are exercised through today.
2. **Add the compiled binary once the grammar set is fixed.** `bun build --compile` produces a single
   file with no Bun prerequisite, but it is large and must be rebuilt per platform: 104 MB measured
   for a hello-world on Bun 1.4.4, 105.1 MB for this app (393 modules), and roughly 1–3 MB per
   embedded WASM grammar — an estimated 130–160 MB for the 12-language v1 set. Compiling grammars
   in is what makes the artifact big, so it waits until the language list stops moving.

Two facts about the standalone artifact today:

- **Migrations must be embedded.** The migration runner reads `.sql` files from
  `import.meta.dir/migrations`; inside a compiled binary that directory is the virtual
  `/$bunfs/root`, which holds only what the build put there. Without `--asset` the binary ships zero
  migrations, computes a shipped schema version of 0, and refuses every existing index with
  `schema_too_new`. The working build command is:

  ```sh
  bun build --compile bin/sangkar.ts \
    --asset "$PWD/src/shared/store/migrations" \
    --outfile dist/sangkar
  ```

  `bun run build` passes exactly this flag, so `dist/sangkar` can read and serve an index.
  `dist/sangkar mcp --repo-root /path/to/repo` is the same command line the Bun install answers,
  with the binary in place of `sangkar`, and `dist/sangkar status --repo-root /path/to/repo`
  answers from it too. `tests/binary-smoke.test.ts` builds and drives that artifact, which is the
  evidence the flag is required rather than merely tidy.
- **Grammar WASM is not embedded.** Grammars load lazily from `web-tree-sitter` and
  `tree-sitter-wasms` in `node_modules` at index time, never at startup, so a compiled binary serves
  an index with no `node_modules` beside it but cannot build one. Until the grammars are compiled in,
  indexing stays with the Bun install and the binary serves the graph it produced.

## Publishing to npm

```sh
bun run release:beta          # npm publish --tag beta
```

Two traps, both hit on 2026-11-18 and both proven with `npm publish --dry-run`:

- **`--tag beta` is not optional.** `publishConfig.tag` is *ignored* by npm 11 (it only suppresses
the "you must specify a tag" guard for prereleases): without the flag on the command line the
publish goes to `latest` anyway, which is the one tag a `0.1.0-beta.0` must never take.
- **The `bin` warning is cosmetic.** npm prints
`bin[sangkar] script name bin/sangkar.ts was invalid and removed` when it rewrites the field to
strip a leading `./`; the entry survives as `bin/sangkar.ts`. `npm pkg fix` shows the same result,
so the canonical form is written in `package.json` and the warning no longer appears.

Publishing then needs two-factor authentication: either `--otp <code>` from an authenticator app,
or a granular access token with 2FA bypass in `~/.npmrc`. Without one the registry answers
`E403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required`,
and nothing is published.

## Checks

```sh
bun test                            # fixtures plus temp dirs; no network, no writes into the repo
bun run typecheck                   # tsc --noEmit, strict
bun run lint                        # biome check src tests bin
bun test tests/binary-smoke.test.ts  # builds the standalone artifact and drives one tools/call
```

## License

MIT — see [LICENSE](LICENSE). The grant covers the package as published, including the migration
SQL it ships; `tree-sitter-wasms`, `web-tree-sitter`, `drizzle-orm` and the MCP SDK keep their own
licenses.