jambavan

<p align="center"> <img src="https://raw.githubusercontent.com/beingmartinbmc/jambavan/main/assets/jambavan.png" alt="Jambavan — the wise elder awakening latent power" width="640"> </p>

<h1 align="center">Jambavan</h1>

<p align="center"><em>The mentor that reminds your model of powers it already has.</em></p>

<p align="center"> <a href="https://www.npmjs.com/package/jambavan"><img src="https://img.shields.io/npm/v/jambavan.svg" alt="npm version"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/jambavan.svg" alt="node version"></a> <a href="https://github.com/beingmartinbmc/jambavan/commits/main"><img src="https://img.shields.io/github/last-commit/beingmartinbmc/jambavan.svg" alt="last commit"></a> <a href="https://github.com/beingmartinbmc/jambavan/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/beingmartinbmc/jambavan/ci.yml?branch=main" alt="CI status"></a> <a href="https://bundlephobia.com/package/jambavan"><img src="https://img.shields.io/bundlephobia/minzip/jambavan" alt="bundle size"></a> <a href="https://www.npmjs.com/package/jambavan"><img src="https://img.shields.io/npm/dm/jambavan.svg" alt="downloads"></a> <a href="./LICENSE"><img src="https://img.shields.io/npm/l/jambavan.svg" alt="license"></a> </p>

---

In the Ramayana, when the army despaired at the ocean's edge, it was Jambavan — the ancient, wise bear-king — who turned to Hanuman and reminded him of his own forgotten, immeasurable strength. Hanuman had the power all along. He only needed to be reminded. Then he crossed the ocean in a single leap.

A large language model is Hanuman. It can already reason, plan, and write code. What it lacks is not intelligence — it is awareness of the ground it stands on: which files exist, what calls what, what was decided last week, what it already tried.

Jambavan is the voice at the ocean's edge. It is a Model Context Protocol server that gives any coding model a live map of the codebase, a durable memory, and a set of surgical tools — so the model's existing power actually lands.

Jambavan does not call an LLM and is not an agent. The host model thinks. Jambavan gives it the ground to leap from.

The powers it hands over

Power	Tools	What it does
Sight	jambavan_index, jambavan_context, jambavan_watch, jambavan_diagnostics	AST-aware code index (tree-sitter, incremental, live-watched). Retrieve ranked, token-budgeted context instead of re-reading whole files. jambavan_context also takes compress_prose, include_diff (recent git changes per symbol), and include_tests (associated test files) — enrichments share the same token budget, not added on top.
The bridge	jambavan_graph_report, jambavan_graph_query, jambavan_graph_path	A lightweight inferred code graph — callers, callees, imports, mentions — built from AST-extracted references matched by symbol name (not scope-resolved). Direct import statements are resolved to their actual source file, so an ambiguous call between two same-named symbols links to the one actually imported; unresolved calls still fan out by name. Edges are labelled EXTRACTED (from the AST) or INFERRED (name mention); verify before large refactors.
Memory	jambavan_memory_store, _search, _recall, _mine_session, _invalidate, _delete, _status	Durable, human-readable memory as markdown files under .jambavan/memory/. BM25 search, no database, no embeddings, no external service. Decisions survive across sessions and models.
Session continuity	jambavan_failure_store, jambavan_failure_search, jambavan_session_export, jambavan_session_import	Structured failure records (command, symptom, root cause, do-not-retry advice) so a fresh session doesn't repeat a dead end. jambavan_session_export produces a single portable handoff document (recent memories, rin debt, git status) to resume work in a new session, host, or with a colleague.
Sankshipta (brevity)	jambavan_sankshipta	Deterministically compress prose and prompts to fewer tokens while preserving code, paths, versions, and facts.
Vibhishana Niti (wise counsel)	jambavan_vibhishana_niti, jambavan_rin_mochan	Activate an efficient-dev discipline mid-session, and audit deliberate shortcuts (// rin: markers) into a tracked debt ledger.
The hands	read_file, search, list_files (default) · write_file, patch_file, bash (opt-in)	Guarded file, search, and shell tools — confined to the project root. Read-only tools are on by default; mutating and shell tools are OFF unless you opt in (see Safety). bash has a best-effort footgun filter (not a security boundary).
The reminder	jambavan_awaken	Reminds the model of every power above, plus the session protocol and recent project memories. Call it first.

Install

One command. Finds every coding agent on your machine (Claude Code, Codex CLI, Cursor, Continue). Registers Jambavan as an MCP server for each one it finds.

# macOS · Linux · WSL · Git Bash
curl -fsSL https://raw.githubusercontent.com/beingmartinbmc/jambavan/main/install.sh | bash

# Windows · PowerShell 5.1+
irm https://raw.githubusercontent.com/beingmartinbmc/jambavan/main/install.ps1 | iex

~30 seconds. Needs Node ≥20. Skips agents you don't have. Safe to re-run. It never touches other MCP servers already in your config — read the script before piping it into a shell, as with anything on the internet.

Register manually

Prefer to wire it up yourself, or use an agent the installer doesn't know about? Same command everywhere: npx -y jambavan.

Claude Code

claude mcp add jambavan -- npx -y jambavan

Codex CLI

codex mcp add jambavan -- npx -y jambavan

Cursor (~/.cursor/mcp.json global, or .cursor/mcp.json per-project)

{
  "mcpServers": {
    "jambavan": { "command": "npx", "args": ["-y", "jambavan"] }
  }
}

Continue — drop a JSON file into ~/.continue/mcpServers/jambavan.json:

{ "command": "npx", "args": ["-y", "jambavan"] }

Troubleshooting (NVM, GUI apps, corporate npm)

npx -y jambavan works when the MCP host inherits a shell PATH containing node/npx and npm can reach the public registry. Two setups break that:

1. GUI-launched hosts (Cursor, etc.) don't see NVM. You'll see spawn npx ENOENT, or — after switching to an absolute npx — env: node: No such file or directory (because npx is a script with #!/usr/bin/env node). GUI apps launched outside your shell don't inherit NVM's PATH. Fix: run an absolute node against npm's npx-cli.js and set PATH explicitly.

2. Corporate npm registry / release-age policy. You'll see No versions available for jambavan (npm pointed at an internal mirror that doesn't proxy it) or No matching version found ... with a date before <date> (an --before / release-age policy rejecting a freshly published version). Fix: force the public registry, clear --before, and pin the version.

Find your paths:

command -v node                                   # → /abs/path/to/node
echo "$(npm prefix -g)/lib/node_modules/npm/bin/npx-cli.js"   # → npx-cli.js

Cursor config with all workarounds applied:

{
  "mcpServers": {
    "jambavan": {
      "command": "/abs/path/to/node",
      "args": [
        "/abs/path/to/npm/bin/npx-cli.js",
        "-y",
        "--registry=https://registry.npmjs.org",
        "--before=",
        "jambavan@0.3.0"
      ],
      "env": { "PATH": "/abs/path/to/node/dir:/usr/bin:/bin" }
    }
  }
}

Apply only the pieces you need: the absolute node + npx-cli.js + PATH fixes NVM/GUI PATH; --registry/--before/pinned version fix corporate npm policy.

Claude Code plugin

This repo is also a Claude Code plugin marketplace. Add it and install with two commands — no manual MCP config:

/plugin marketplace add beingmartinbmc/jambavan
/plugin install jambavan@jambavan

The plugin registers the same npx -y jambavan MCP server (read-only tools by default) and bundles a Vibhishana Niti skill — run /jambavan:vibhishana-niti to activate the efficient-dev discipline in any Claude Code session. Refresh later with /plugin marketplace update jambavan. The catalog lives in .claude-plugin/marketplace.json; the plugin manifest in plugins/jambavan/.claude-plugin/plugin.json.

Run directly

npm install
npm run build
node dist/index.js --help
node dist/index.js

Set JAMBAVAN_ROOT=/path/to/project when launching from outside the target repo.

The leap (recommended workflow)

1. jambavan_awaken — read the protocol and recent project memories.
2. jambavan_index — build the local SQLite code index.
3. jambavan_watch start — keep the index live while editing.
4. jambavan_context — pull ranked, token-budgeted context before touching unfamiliar code.
5. patch_file over write_file — surgical edits, cheaper tokens. (needs JAMBAVAN_ALLOW_WRITE=1)
6. Keep tool output Sankshipta: line ranges, max_results, git --stat / --name-only, jq/yq/awk/cut/head, quiet/no-color flags, and hash/mtime polling before full reads.
7. bash — run the smallest relevant check. (needs JAMBAVAN_ALLOW_BASH=1)
8. jambavan_memory_store / jambavan_memory_mine_session — persist what was decided, so the next session starts awake.
9. Hit a dead end? jambavan_failure_store it (symptom, root cause, what NOT to retry) — and jambavan_failure_search before repeating a failing approach.
10. Ending the session? jambavan_session_export — paste the handoff document into the next session, a different host, or a colleague.

Safety

Read-only by default. read_file, search, and list_files are always available. The mutating and shell tools are off unless you explicitly opt in, because an autonomous host model should not get write/exec access by accident:

Tool(s)	Enable with
write_file, patch_file, jambavan_sankshipta	JAMBAVAN_ALLOW_WRITE=1
bash	JAMBAVAN_ALLOW_BASH=1

When disabled, these tools are not registered at all — the host never sees them. (jambavan_sankshipta rewrites files in place, so it counts as a write tool.)

File, search, list, and bash working directories are confined to JAMBAVAN_ROOT (or the detected project root). Set JAMBAVAN_ALLOW_OUTSIDE_ROOT=1 only for trusted local use. Files that look like secrets (.env*, *.pem/*.key, id_rsa, .npmrc, .aws/credentials, .git-credentials, service-account*.json, and anything inside .aws/, .docker/, or .ssh/, …) are refused by all file tools unless JAMBAVAN_ALLOW_SECRETS=1. This list is deliberately non-exhaustive — it is not a substitute for keeping real secrets out of the repo.

bash runs with a minimal no-color environment (host secrets are not inherited unless JAMBAVAN_BASH_INHERIT_ENV=1) and catches a few obvious footguns (rm -rf /, rm -rf /*, home/project wipes, git reset --hard, git clean -fx, blind curl | sh, and similar). This is not a security boundary — it is trivially bypassed by encoding, aliases, scripts, shell expansion, or unlisted commands like find . -delete. Treat bash as a local shell: review tool calls before approving them, and run the server inside a sandboxed workspace (container / microVM) if you need real isolation.

Configuration

Env var	Default	Description
JAMBAVAN_ROOT	auto-detect	Project root to index and serve
JAMBAVAN_MEMORY_HOME	<indexDir>/memory	Where OKF memory docs live; point at a shared palace to reuse memory across projects
JAMBAVAN_TOKEN_BUDGET	8000	Max tokens in jambavan_context output
JAMBAVAN_DEV_MODE	full	Default Vibhishana Niti level (lite / full / ultra)
JAMBAVAN_ALLOW_WRITE	off	1 registers write_file + patch_file + jambavan_sankshipta
JAMBAVAN_ALLOW_BASH	off	1 registers bash
JAMBAVAN_ALLOW_OUTSIDE_ROOT	off	1 lets tools escape the project root (trusted local use only)
JAMBAVAN_ALLOW_SECRETS	off	1 lets file tools touch secret-looking files
JAMBAVAN_BASH_INHERIT_ENV	off	1 passes the full host env to bash (default: minimal env)
JAMBAVAN_MAX_OUTPUT_CHARS	100000	Global cap on any tool's returned output
JAMBAVAN_MAX_READ_BYTES	5242880	Max file size read_file will load

Benchmark

npm run bench dogfoods the real pipeline — no LLM calls, no external services, fully deterministic. It auto-derives queries from the repo's own most common symbols, so it's meaningful on any codebase. It measures five dimensions, not just token savings, and every number below is a fresh run against this repo (38 files, 177 symbols):

1. Index — build speed and throughput.

metric	value
cold build	~164 ms (38 files, 177 symbols)
warm re-index	~29 ms (~5.7× faster, only changed files re-parsed)
throughput	~232 files/s · ~1,079 symbols/s

2. Context — not only tokens, but how much the agent has to open. Baseline = an agent reads the full contents of every file a query matches; jambavan ships ranked, budgeted snippets instead.

metric	baseline	jambavan	win
files/snippets to read	6 whole files	14 focused chunks	targeted spans, not whole files
tokens (5 queries)	~21,500	~12,000	~44% fewer
assemble latency	(disk reads)	~2 ms	below one check's runtime

3. Graph — relationships extracted from the AST (a coverage metric, not tokens).

metric	value
nodes / edges	209 / 564
edge provenance	314 EXTRACTED (from AST) · 250 INFERRED (name mention)
build / query / path	~2.9 ms / ~7.3 ms / ~0.08 ms

4. Sankshipta — prose compression holds steady around 24%.

5. Tool latency — all 28 tools the MCP server advertises, timed over the real stdio transport (the same request/response path a host model uses): min/median/max over 10 calls for read-only tools, single-shot for mutating ones. Representative medians:

tool	median	tool	median
jambavan_context	0.3 ms	jambavan_memory_search	0.2 ms
jambavan_graph_query	0.3 ms	jambavan_awaken	1.6 ms
jambavan_graph_path	0.2 ms	jambavan_index (1 file)	13.4 ms
read_file	0.1 ms	search (ripgrep)	10.3 ms
list_files	0.3 ms	bash (subprocess)	11.9 ms
jambavan_failure_search	0.2 ms	jambavan_session_export (2 git calls)	40.6 ms

Everything driven purely in-process is sub-millisecond; the outliers (index, search, bash, session_export) are the ones that shell out or touch disk, exactly as expected. Every call succeeds — the benchmark exits non-zero if any tool errors, so it doubles as an end-to-end smoke test.

The larger the codebase, the bigger the win. The same benchmark run against a mid-size Java service (166 files, ~1,000 symbols) — every dimension scales in Jambavan's favour:

dimension	this repo (38 files, 177 symbols)	a mid-size Java service (166 files, ~1,000 symbols)
cold index	~164 ms	~577 ms
incremental re-index	~5.7× faster	~8.4× faster
context tokens saved	~44%	~87%
files→chunks (5 queries)	6 files → 14 chunks	80 files → 133 chunks
graph edges extracted	564	~10,400

Incremental re-index and per-query context stay roughly flat while a from-scratch read grows with the repo, so the token savings widen as the codebase grows. Baseline is a conservative comparison — per-query results vary, and occasionally a query whose matches sit in tiny files reads cheaper whole than as ranked snippets. Run it on yours:

JAMBAVAN_ROOT=/path/to/your/repo npm run bench

Checks

npm run lint
npm run build
npm run unit        # node:test unit suite (test/*.test.ts)
npm run self-check
npm run bench

See ARCHITECTURE.md for internals.

---

<p align="center">_{You already have the power. Jambavan only reminds you.}</p>