Getting started

CLI & daemon

The editor-independent path: install the daemon, launch the TUI, index a repo, ask a grounded question, then register the MCP server with your CLI host.

1 · Install the daemon

Release installer (recommended). The one-line installer verifies prerequisites, clones + builds the daemon into ~/.insrc/daemon, and starts it. Update later by re-running it or with ~/.insrc/daemon/scripts/daemon-ctl.sh update.

$ curl -fsSL https://github.com/insors-ai/insrc/releases/latest/download/insrc-daemon-install.sh | bash
# pass installer options after `bash -s --`, e.g.:
$ curl -fsSL https://github.com/insors-ai/insrc/releases/latest/download/insrc-daemon-install.sh | bash -s -- --no-start --embedder ollama
# options: --target <path>  --branch main  --no-start  --repo <fork-url>  --embedder auto|ollama|onnx

From source (development) — for working on the daemon itself:

$ git clone https://github.com/insors-ai/insrc.git
$ cd insrc
$ npm install            # runtime + dev deps (builds native modules)
$ npm run build          # tsc + copy-assets.mjs → out/

The two entry points produced by the build:

• out/daemon/index.js — the daemon binary the IDE spawns.
• out/bin/insrc-mcp.js — the MCP binary you register with claude / codex.

$ npx tsx --test 'src/workflow/**/*.test.ts' 'src/mcp/**/*.test.ts'   # ~5s
$ npx tsx --test 'src/**/__tests__/*.test.ts'                       # full sweep

2 · Launch the TUI

The insrc command is a full-screen ink (React) TUI. It starts (or attaches to) the daemon and gives you Daemon / Repos / Workflows / Setup / Tiers / Debug panes.

$ "$HOME/.insrc/daemon/scripts/insrc"

┌─ Repos ───────────────────────────────────────────┐
│ ● insrc            ready    · 3,412 entities      │
│ ○ my-service       indexing · 61%               │
└───────────────────────────────────────────────────┘
 a add repo   r re-index   d remove   ↑↓ select

3 · Add & index a repo

Registry membership is established exclusively through the repo.add IPC — from the TUI, open the Repos pane and press a. The daemon parses the tree with tree-sitter, builds the graph, and generates embeddings.

During a, insrc asks — per file — whether to install the steering block into the repo's CLAUDE.md (Claude Code) and/or AGENTS.md (Codex). Say yes and the daemon writes a safe, idempotent insrc:steering marked section (created if absent, replaced in place on re-add, never clobbering your surrounding content) so a controller reaches for insrc_analyze_step on code questions, insrc_triage first on build requests, and insrc_review_step before approving. No manual copy-paste needed.

From the command bar (non-interactive, so it can't prompt) pass the flag explicitly: repo add <path> --steering installs both, or --steering=claude / --steering=agents for one. Bare repo add <path> installs nothing (no silent write) and prints a reminder.

Wait for the status to reach ready (embeddings pending shows as a count). Graph searches span the transitive DEPENDS_ON closure of the active repo, so add dependency repos too if you want cross-repo answers.

On add, insrc writes a per-repo .insrc/config.json with an ignore section — seeded from the repo's .gitignore when present, otherwise from its type (node / python / java / go). Edit it to control which directories the indexer and file-watcher skip (e.g. node_modules, dist, target, __pycache__). It's created idempotently and never overwritten once you've customised it.

4 · Ask your first question

For any question about a codebase's structure, conventions or capabilities, use the analyze tools — every claim is grounded in a real graph exploration, with file paths drawn from the index (no hallucinated paths).

# In your MCP-connected assistant, ask:
"List the storage layers and where each is initialised."

Prefer insrc_analyze_step (multi-turn, stays in your session) over the one-shot insrc_analyze when driving from an MCP client — it's more accurate and doesn't spawn a separate billing path. See the analyze guide.

5 · Register the MCP servers (manual / explicit)

Approving a steering block during repo add already registers the matching client (above). This is the manual path — for a client you skipped, a from-source install, or to re-register by hand. It wires the MCP binary insrc-mcp.js into each client, exposing the full tool suite — insrc_analyze_step, insrc_triage, insrc_workflow_step, insrc_review_step and insrc_build_step. The installer puts the binary at ~/.insrc/daemon/out/bin/insrc-mcp.js; a from-source build has it at out/bin/insrc-mcp.js in the repo.

Claude Code

Register at user scope so insrc is available in every repo:

$ claude mcp add insrc --scope user -- node ~/.insrc/daemon/out/bin/insrc-mcp.js
$ claude mcp list        # insrc: … ✔ Connected

To scope it to a single repo instead, drop a .mcp.json at that repo's root — insrc is then visible only inside it. Use an absolute path (~ is not expanded in JSON):

{
  "mcpServers": {
    "insrc": {
      "command": "node",
      "args": ["/Users/you/.insrc/daemon/out/bin/insrc-mcp.js"]
    }
  }
}

Codex

Codex servers in ~/.codex/config.toml are global by nature — add the insrc server there (absolute path; no ~):

[mcp_servers.insrc]
command = "node"
args = ["/Users/you/.insrc/daemon/out/bin/insrc-mcp.js"]

Restart the client (or reconnect its MCP) after editing a config file — both read it at startup.

How the repo is resolved

Resolution is session-aware for both clients, in order: an explicit repo argument wins; otherwise the server matches its working directory against the registered repos (the session workspace — both clients spawn the server with the workspace as its CWD); otherwise it falls back to an optional INSRC_REPO env for headless / cron use. That's why one global registration with no INSRC_REPO works everywhere. Either way the repo must be registered with the daemon and finished indexing.

VS Code extension

The extension installs and manages the daemon for you, so there's no manual daemon step — just install, accept the onboarding prompts, and use your assistant. Full detail on the VS Code page.

1 · Install the extension

Open the Extensions view (⇧⌘X / Ctrl+Shift+X), search insrc, and click Install — or install insors.insrc-vscode from the Marketplace. (Pre-release: ⋯ → Install from VSIX… with a built insrc-vscode-<version>.vsix.)

2 · Accept the first-run onboarding

On first activation the extension runs one coalesced flow, prompting for each step independently and only when needed — nothing happens without your explicit consent:

1. Install the insrc daemon into ~/.insrc/ (or keep an existing one current).
2. Register this workspace with the daemon (repo.add) so it gets indexed.
3. Wire your AI host (Claude Code, Cursor, …) so insrc's MCP tools are available to your assistant.

3 · Use it

Your assistant now explores the code through insrc's grounded tools. Edit the daemon's config from native VS Code Settings (search insrc), pick a tier's model with insrc: Set model tier, and open the status-bar insrc item for Detailed Status / Repo Configuration panels. See the VS Code page and the settings guide.

JetBrains plugin

One plugin for IntelliJ IDEA, PyCharm, GoLand & WebStorm (2024.2+). It manages the daemon and wires a JetBrains AI host; setup happens on project open. Full detail on the JetBrains page.

1 · Install the plugin

Settings → Plugins → Marketplace, search insrc, and click Install. (Pre-release: Settings → Plugins → ⚙ → Install Plugin from Disk… with a built insrc-jetbrains-<version>.zip.) You also need a JetBrains AI host — AI Assistant or Junie; without one the plugin stays dormant and re-checks on later project opens.

2 · First-run setup (on project open)

Installing the plugin doesn't touch the daemon by itself — on the first project open with the plugin active it:

1. Probes for the daemon and, if absent, offers a one-click setup you accept explicitly (it clones + builds the daemon into ~/.insrc/daemon; an existing daemon is silently kept current).
2. Offers "Enable insrc for this project" — a one-click repo.add that registers the open project.
3. Wires your AI host — writes the insrc MCP registration + the tracked-workflow steering into the detected host's config and rules files.

3 · Use it

Your assistant is now grounded per-project. Drive and inspect insrc from Settings → Tools → insrc (a live config editor with Daemon / Workflows / Debug pages), the project-view context menu (repo status + register), and the artifact-review tool window (read, comment on and approve pending workflow artifacts). See the JetBrains page and the settings guide.