Getting Started with jarvis-brain

Practical, copy-paste-friendly guide. Goal: go from zero to productive in under 15 minutes.

TL;DR

Get a dev token (ask an admin or create one on VPS — 30 sec).
Open https://brain.sdet.it/login → paste token → you're in.
Pick your path: browser (architect/review), CLI (terminal lookups), or Claude Code MCP (biggest win — CC stops wasting tokens on Grep).

What is jarvis-brain, in one sentence

A federated knowledge graph over all Acme repos (Acme core + Inventory + Checkout + Analytics + Customer) that you query via browser, CLI, or Claude Code — so you stop grepping through 5 repos to find out what's in core.

Who benefits from what

🎨 Frontend developer (Inventory / Checkout / Analytics / Customer / Customer KPO)

Problem: "I need a cart hook. Acme-core probably has one, but where?"

Without brain: rg useCart in 5 repos, read 20 files, guess what's core vs local.

With brain (in Claude Code):

Ask CC: "show me useCart from acme-core and who uses it"

CC calls brain_query + brain_explain + brain_path automatically. You get: file path, neighbors, who uses it, which repos override it.

Saving: 5 min → 10 sec. And Claude Code stops burning tokens on Grep/Read exploration.

🏗️ Architect / Tech lead

Problem: "Do Checkout and Inventory duplicate logic that should live in Acme?"

With brain:
- https://brain.sdet.it/admin/insights/acme → 1395 communities, 10 god-nodes, DRY violations
- brain_ffcss(mode=violations) → "Checkout and Inventory both define color-primary locally — promote to Acme"
- Graph viz → click any node → see inbound/outbound across all 5 repos

Saving: system-level decisions in 15 min instead of 1 day of analysis.

👥 Team lead / onboarding

Problem: New dev starts on Customer, no idea what's in Acme-core.

With brain:
- Send them https://brain.sdet.it/vault/forgefront/_master/ → 5560 pages, all cross-linked
- Or https://brain.sdet.it/graph/forgefront/Acme/ → visual map, click to explore
- Or install CLI → brain query "anything"

Saving: Onboarding without you personally walking through the codebase.

Prerequisites

Network access to https://brain.sdet.it (public HTTPS)
A dev token (ask an admin — see step 1 below)
For MCP in Claude Code: .mcp.json edit permission (trivial)
For CLI: curl, jq, bash (standard on macOS/Linux)

Step 1: Get a dev token

If you're an admin (SSH to VPS)

ssh -p 63538 [email protected]
cd /opt/docker/apps/jarvis-brain
docker compose exec brain-api python -m brain.scripts.manage_tokens \
  create --name firstname-lastname --scopes query,graph

Copy the brain_xxxxxxxxxxxxxxxx token — shown once, never again.

If you're not an admin

Ask @darekowalski for one. Include your name (e.g. "laptop-marta") so we can audit usage.

Step 2: First browse (60 seconds)

Open https://brain.sdet.it/login
Paste your brain_... token, click SIGN IN
You'll see the CRT terminal success page with 6 links
Click any graph link — e.g. https://brain.sdet.it/graph/forgefront/InventoryApp/
Click any node → wiki page opens with details + neighbors

You're in. Explore via top nav: GRAPHS / WIKI / DASHBOARD.

Step 3: Install the CLI (2 minutes)

curl -sSL https://brain.sdet.it/install-cli | bash
export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc

brain login                             # prompts for URL + token
brain query "useBaseUser"               # smoke test
brain graph InventoryApp              # inspect full graph
brain explain "acme/Acme:acme/Acme:ActivePromos"

Config lives in ~/.config/brain/config (XDG-compliant).

Step 4: Plug into Claude Code (the big win — 3 minutes)

This is where brain really pays off. CC stops Grep'ing and uses pre-computed brain answers.

4a. Add MCP server config

Option A — project-level (recommended, per-project):

In the root of any repo where you want brain available, create .mcp.json:

{
  "mcpServers": {
    "brain": {
      "type": "http",
      "url": "https://brain.sdet.it/mcp",
      "headers": {
        "Authorization": "Bearer ${BRAIN_DEV_TOKEN}"
      }
    }
  }
}

Or just copy the template:

curl -O https://raw.githubusercontent.com/dar-kow/jarvis-brain/main/.mcp.json.example
mv .mcp.json.example .mcp.json

Option B — global (available in every CC session):

Add the same block to ~/.claude/claude_desktop_config.json (or whatever your CC config file is).

4b. Set the token as env var

# ~/.zshrc or ~/.bashrc
export BRAIN_DEV_TOKEN=brain_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Reload: source ~/.zshrc

4c. Verify in Claude Code

Start a new CC session in any repo that has .mcp.json. Run:

/mcp

You should see:

brain: connected
  - brain_query
  - brain_graph
  - brain_path
  - brain_explain
  - brain_ffcss

4d. First real prompt

In CC (inside a Inventory or Checkout repo):

"Show me how Inventory implements the AddToCart flow. Use brain to find what Acme-core provides and where Inventory overrides it."

CC will chain-call:
- brain_query("AddToCart", scope="acme/InventoryApp")
- brain_explain(<node_id>) for each hit
- brain_path(from=<Inventory node>, to=<Acme core hook>)

…and give you an answer without reading a single file with Grep.

Step 5: Your first week — real use cases

Use case 1: "I'm writing a feature and want to reuse, not duplicate"

In CC: "I need a toast error handler in the checkout flow. Does acme-core already have one?"

CC → brain_query("toast error", scope="acme/Acme") → finds useToast → you reuse, don't reinvent.

Use case 2: "Debugging — why does this act differently in Inventory vs Checkout?"

In CC: "Trace the path from Inventory's ProductCard render to whichever base hook handles pricing."

CC → brain_path(from="acme/InventoryApp:ProductCard", to="acme/Acme:useBasePrice") → returns hops → you see exactly where Inventory diverges from core.

Use case 3: "Code review — is this new util a duplicate?"

Browser: https://brain.sdet.it/graph/forgefront/Acme/ → type formatPrice in the search (vis-network built-in) → see if it already exists.

Or CLI: brain query "formatPrice" → instant answer.

Use case 4: Architect quarterly review

https://brain.sdet.it/admin/dashboard — cost trend over 90d (do you spend too much on Gemini?)
https://brain.sdet.it/admin/insights/acme — see the 10 god-nodes (highest-coupled code — refactor candidates)
brain_ffcss(mode="violations") — DRY violations across repos (tokens that should be in Acme)
Export wiki → https://brain.sdet.it/vault/forgefront/_master/ — share with stakeholders

Use case 5: Onboarding a new dev (15 min instead of 2h)

Send them 3 links:
1. https://brain.sdet.it/login (get them a token first)
2. https://brain.sdet.it/vault/forgefront/_master/ (the wiki — 5560 pages)
3. This guide you're reading

Done. They can self-serve.

MCP tools reference

Tool	Args	What it returns
`brain_query`	`q, scope?, limit?`	FTS5 search — top N hits with label/file/repo + 2-hop neighbors
`brain_graph`	`group, repo?`	Raw `graph.json` for repo, or group master if repo omitted
`brain_path`	`from_node, to_node, max_hops?`	Shortest path between two node IDs on the federated master graph
`brain_explain`	`node_id`	Node metadata (kind, file, community) + inbound/outbound neighbors + git-blame provenance
`brain_ffcss`	`group, repo?, mode: tokens\\|usage\\|violations`	FFCSS token federation — canonical/local, overrides, DRY violations

Scopes for brain_query:
- None → fan-out across all groups (master index)
- "acme" → group-wide
- "acme/InventoryApp" → scoped to one repo
- "super" → cross-group merged (same as None but from dedicated super index)

What if brain is missing info?

If you're working in a repo and brain gives stale/empty results:

Option A — wait for auto-regen

We poll jarvis-brain-job-graphs every 5 minutes. If the graph was re-extracted and pushed, wait 3 min and retry.

Option B — force a re-extract (requires `/brain-extract` skill)

In CC, inside the repo:

/brain-extract

This uses Claude Code's native AST analysis to emit graph.json → commits to jarvis-brain-job-graphs → VPS federates within 3 min.

Option C — trigger LLM extraction via admin

Ping an admin, they run:

curl -X POST "https://brain.sdet.it/admin/rebuild?scope=repo&id=acme/InventoryApp&mode=incremental" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Troubleshooting

"401 Invalid bearer token"

Your token is invalid or expired. Get a new one from admin. Brain tokens don't expire but can be revoked.

"No hits for useBaseUser"

FTS5 tokenizes useBaseUser as one token. Search the camelCase split instead:
- brain query "Base" → finds useBaseUser, ProductCardBase, etc.
- Or use wildcard: brain query "useBase*"

"Graph too large for interactive view"

The master graph (5559 nodes) exceeds vis-network's 4500 limit. Use per-repo graphs from the home page, or the wiki (no size limit there).

"MCP: brain connection refused"

Check:
- BRAIN_DEV_TOKEN env var is set (echo it — should start with brain_)
- .mcp.json is in the current repo root
- Restart Claude Code

CLI: "brain: command not found"

$HOME/.local/bin not on PATH. Add to your shell rc:

export PATH="$HOME/.local/bin:$PATH"

FAQ

Q: Does brain slow down my CC?
A: No. MCP calls to brain are <100ms (fast HTTP). Without brain, CC Greps 5 repos which takes 2-5 seconds.

Q: Who can see my queries?
A: Every query is logged in QueryLog with your dev-token name. Admins can see aggregate stats (top queries, latency) but individual queries are only visible to admins with DB access.

Q: Can I use brain from VS Code / Cursor / etc.?
A: Anything that speaks MCP over HTTP. Currently we've verified only Claude Code. The raw HTTP API works from any language (curl https://brain.sdet.it/query?...).

Q: What happens when Acme-core changes?
A: Polling picks it up within 5 min (if the graph was re-extracted). Qwen local re-extracts on git push via webhook → graph.json → graphs repo → brain federation → live.

Q: Does brain work for backend code?
A: Right now the 5 acme repos are frontend/Vue. Brain is framework-agnostic — the extractor emits graph.json of any language (Python, Go, TS). To add your backend repo, update groups.yml and trigger extraction.

Quick reference card

Print this or pin somewhere:

https://brain.sdet.it/              — home (6-card overview)
https://brain.sdet.it/login         — paste your dev token here
https://brain.sdet.it/graph/<g>/<r>/ — interactive graph viz per repo
https://brain.sdet.it/vault/<g>/_master/ — federated wiki (5560 pages)
https://brain.sdet.it/admin/dashboard — cost/latency/jobs (admin only)

CLI:
  brain login
  brain query "cart"
  brain graph InventoryApp
  brain explain <node_id>
  brain path <from> <to>

MCP tools in CC:
  brain_query, brain_graph, brain_path, brain_explain, brain_ffcss

Next steps

Frontend devs: configure MCP (Step 4) — this is where you'll feel the biggest win day-to-day.
Architects: schedule 30 min to explore /admin/insights/acme and /admin/dashboard. You'll find 2-3 refactor opportunities immediately.
Team leads: forward this doc + a dev token to every dev. Self-onboarding works.
Everyone: if brain saves you time, tell us. If it's missing something, file an issue: https://github.com/dar-kow/jarvis-brain/issues

Questions? DM @darekowalski or file an issue.
Full architecture details: see README.md + CHANGELOG.md [0.4.0] + docs/OPERATIONS.md.