setup git:20260922.fcbe590A

Immutable. This exact content never changes and is served at /api/v1/blob/f464b27529ae3e87.

---
name: setup
description: First-run Eklavya setup — check prerequisites, create the database, choose a mode, and say what memory does.
disable-model-invocation: true
---

# /eklavya:setup

Get Eklavya working on this machine. Be brief; this should take one exchange.

**1. Check prerequisites.** Run `node --version`. That is the whole list — the server, the CLI and all seven hooks are Node, so nothing else has to be on `PATH`. Node must be 22+; below that the SQLite driver has no prebuilt binary and would need a C++ toolchain to install. If it is older, say so and how to upgrade on this platform, and stop: the rest of setup will not work.

Optionally run `eklavya doctor`, which reports the same thing plus the runtime, the SQLite driver, the plugin's registration, the chat skill, the database and the effective config. It exits non-zero and names the repair — `eklavya install` — if any of those has broken. That is also the command to reach for later, whenever Eklavya has gone quiet: the hooks never fail loudly, so a broken install looks exactly like a quiet one.

**2. Confirm the database.** Call `get_config` and report `global_path`. If that same call reports `surface: "cowork"`, stop there — `global_path` came back, so the server is running and the database is behind it; that is the confirmation. **Do not run the shell check below in Cowork.** It runs in a sandbox VM with its own filesystem, finds no `~/.eklavya/knowledge.db`, and would have you report a broken install on a healthy one.

Everywhere else, check the DB:

```bash
sqlite3 ~/.eklavya/knowledge.db 'select domain, count(*) from concepts group by domain'
```

The server creates and seeds it on first start, and `npx eklavya install` creates it up front, so this should already show `web-auth`, `react`, `node-backend` and `git`. If the file is missing, the MCP server is not running — check `/plugin` for errors, and check that the runtime is installed (`npx eklavya install` finishes it in one step).

**3. Choose a mode.** Ask which fits, and explain in one line each:

- **ambient** (default) — questions after tasks, always skippable
- **enforced** — the session quiz must pass before a commit goes through; for interns and onboarding
- **off** — installed but dormant

Then `set_config` with their choice. Use `scope: "repo"` if they want it to apply to this project only — that writes `.eklavya.json` at the repo root, which is how a lead pins enforced mode for one codebase. Otherwise global.

**3b. Choose a focus.** One more question, because it changes every quiz. Mode is how hard Eklavya pushes; focus is what it teaches.

- **concept** (default) — asks the transferable version of the same ideas. Best when learning a stack.
- **project** — asks about the code just written. Best when learning a codebase.
- **learn** — you name a topic and it teaches that, using your real code as the example where the work touches it.

`set_config` with `focus`, plus `focus_topic` if they chose `learn` — that combination is useless without one. If they have no preference, say concept is the default and move on; this should not become an interview. `/eklavya:mode` changes it later.

**4. If they chose enforced, install the git hook.** Skip this entire step when `get_config` reports `surface: "cowork"` — Cowork does not commit, so there is nothing to gate and no repo to install into. Say once that enforced mode will ask its questions but block nothing here, and move on; everything else in this setup applies unchanged. Trust that field rather than checking the environment yourself: a shell command in Cowork runs inside a sandbox VM and cannot see the variable this is read from.

The `PreToolUse` hook only covers commits made inside Claude Code — which includes the Code tab in Claude Desktop, the same engine on the same config. The git `pre-commit` hook covers every other path — a bare terminal, VS Code, Cursor:

```bash
"${CLAUDE_PLUGIN_ROOT}"/scripts/install-git-hook.sh
```

It chains to any existing `pre-commit` hook rather than replacing it, and only acts on repos whose `.eklavya.json` sets `"mode": "enforced"` — so installing it is safe even if they later switch to ambient. Mention `--uninstall` restores the previous hook.

Skip this step for ambient or off.

**4b. Say what memory does, in two sentences, and do not ask a question about it.**

Eklavya also records what each session did — the prompts, the edits, the tool
failures — and hands the relevant part back at the start of the next one, so
next week's session starts knowing what last week's did. It is on by default,
it is local (the summariser and the search index both run on this machine, no
key and no account), and it is a separate switch from the mode they just
chose: `mode: off` stops the questions and keeps the history.

Say that and move on. It needs no decision now, and turning it into a fifth
question makes setup an interview. If they ask where it goes or what is
excluded, point at `/eklavya:memory` and the [memory page](https://eklavya.dev/docs/memory/)
rather than reciting the exclusion list.

**5. Say what happens next.** In ambient mode: build something, and questions will follow. Point at `/eklavya:progress` and `/eklavya:quiz`. In enforced mode, add that commits are held until the session quiz passes, and `/eklavya:gate` shows what is outstanding.