@kinqs/brainrouter-cli 0.3.4 → 0.3.5

package/README.md

@@ -1,185 +1,145 @@
-# 🧠 BrainRouter Terminal Agent CLI
+# `@kinqs/brainrouter-cli`
 
-A premium, autonomous terminal-based AI coding assistant and REPL that acts as your local agent. It leverages **BrainRouter's memory engine** for cognitive persistence (System 1/2 loops) and provides standard filesystem/terminal tools to solve complex coding tasks autonomously.
+A memory-native terminal agent. Edits files, runs shell commands,
+spawns child agents, and talks to a BrainRouter MCP server for long-term
+recall, skills, and capture.
+
+Ships the `brainrouter` binary.
 
 ---
 
-## Features
-- **Dual-Tier Connection**: Connects to local MCP servers via standard I/O (stdio) or hosted multi-tenant servers over Streamable HTTP/SSE.
-- **Double-Tier Memory Architecture**:
-  - **System 1 (Heuristic Recall)**: Automatically retrieves active focus scenes, codebase facts, and skills *before* each LLM reasoning cycle.
-  - **System 2 (Memory Consolidation)**: Autonomously extracts learning points, updates facts, and saves evidence via turn-by-turn memory capture.
-- **Local Execution Harness**: Autonomous execution of files editing, directory listing, regex/string grep, and terminal command invocation (safely prompted for user verification).
-- **Obsidian Dark / Midnight Ledger Aesthetics**: High-end command line styling, loader animations, and formatted terminal markdown output.
+## Install
 
----
+```bash
+npm install -g @kinqs/brainrouter-cli
+```
 
-## Installation & Setup
-
-1. **Build the Monorepo**:
-   From the repository root:
-   ```bash
-   npm install
-   npm run build
-   ```
-
-2. **Configure Provider and Server Profiles**:
-   Run the interactive configurator to set up your LLM settings (OpenAI, local endpoints like Ollama/LM Studio) and active server profile.
-   From the repository root:
-   ```bash
-   npm run cli config
-   ```
-   Or from the `brainrouter` package subdirectory:
-   ```bash
-   node dist/index.js config
-   ```
-   This generates and modifies settings stored in `~/.config/brainrouter/config.json`.
+**The `-g` flag is critical.** Without it, npm installs into the current
+directory's `node_modules/` and the `brainrouter` binary ends up at
+`./node_modules/.bin/brainrouter` — not on `$PATH`. Symptom: `brainrouter:
+command not found`.
 
----
+**Sudo caveat.** Whether you need `sudo` depends on your Node install:
+
+| How Node is installed | Use `sudo`? |
+|---|---|
+| Homebrew (`brew install node`) | ❌ No — global prefix is user-writable |
+| nvm / asdf / fnm | ❌ No — same reason |
+| System Node on macOS / Linux | ✅ Yes — global prefix is `/usr/local/...` |
+
+Check yours:
 
-## CLI Usage
-
-### Start Interactive Agent Session (REPL)
-Starts the agent loop. It will automatically load the active server connection and prime the agent with active codebase memories.
-From the repository root:
-   ```bash
-   npm run cli
-   ```
-   Or to run a specific command:
-   ```bash
-   npm run cli chat
-   ```
-   Or from the `brainrouter` package subdirectory:
-   ```bash
-   node dist/index.js chat
-   ```
-*Tip: You can override the active LLM model via `--model <name>` or profile via `--profile <name>`.*
-
-Workspace detection:
-- By default, BrainRouter uses the nearest project root with `AGENT.md`, `AGENTS.md`, or `.git`.
-- If you run from this package directory during BrainRouter development, the CLI promotes the workspace to the monorepo root so tools see the whole project, not only `brainrouter/`.
-- Override manually with `--workspace /absolute/path/to/project` or `BRAINROUTER_WORKSPACE=/absolute/path/to/project`.
-- In the REPL, run `/workspace` to confirm the active root and session key.
-
-### Host Login / Setup Connection
-Interactively log in to a hosted HTTP/SSE BrainRouter deployment and test latency/connectivity:
-From the repository root:
 ```bash
-npm run cli login
+npm config get prefix
+```
+
+If the path is under `/Users/...`, `/opt/homebrew/...`, or your home dir
+→ no sudo. If it's `/usr/local/...` → use sudo.
+
+Verify the install:
+
+```bash
+which brainrouter           # prints the path to the binary
+brainrouter --version       # prints 0.3.5
 ```
 
 ---
 
-## Interactive REPL Slash Commands
+## Configure
+
+Two configuration surfaces, both one-time:
 
-Within the chat session, type `/` to access commands:
-- `/help` — List all available directive commands.
-- `/status` — Display active server profile details, LLM model, server latency check, and database size stats.
-- `/workspace` — Show active workspace root, launch directory, and BrainRouter session key.
-- `/tools` — Show local workspace tools and MCP tools exposed to the LLM.
-- `/doctor` — Check active profile, MCP connectivity, plan + session store health, and orchestration tool availability.
-- `/skills` — Visualize all loaded BrainRouter skills and categories.
-- `/plan` — Show the durable CLI task plan persisted under `.brainrouter/cli/tasks.json`.
-- `/transcript [main|sessionKey]` — Show recent persisted transcript entries.
-- `/roles` — List built-in agent roles (`explorer`, `architect`, `reviewer`, `worker`, `verifier`) with default access modes.
-- `/agents` — List child agent sessions with status, role, label, and elapsed time.
-- `/agent <id>` — Show child detail, prompt, final output, and recent transcript.
-- `/spawn <role> <prompt>` — Spawn a child agent (parent narrates via the LLM tool call).
-- `/wait <id> [timeoutMs]` — Wait for a child agent to finish.
-- `/spec <title>` — Runs the **spec-driven-skill** and writes a full `spec.md` to `<workspace>/.brainrouter/cli/workflows/<slug>/spec.md`. Stops for approval before generating tasks.
-- `/approve [slug]` — Approves the current (or named) workflow and kicks off the worker + verifier implementation phase, one task at a time, appending to `walkthrough.md`.
-- `/workflows` — List durable workflow folders with per-artifact status (`spec.md`, `tasks.md`, `walkthrough.md`).
-- `/feature-dev <feature>` — Runs the catalogued **agentic-engineering-workflow** skill with explorer + architect orchestration. Writes `spec.md` and `tasks.md` to the workflow folder, then stops for user approval before worker implementation.
-- `/review [scope]` — Runs the catalogued **code-review-and-quality** skill with 3 parallel reviewer agents (correctness, maintainability, conventions).
-- `/implement-plan` — Runs the catalogued **incremental-skill** with a worker + verifier loop on the next pending plan item.
-- `/skill <name> [input]` — Generic invoker for any skill in your `skills/` catalogue. The CLI fetches the skill body via the MCP `get_skill` tool, falls back to filesystem (`skills/**/SKILL.md`), and hands the agent a structured prompt that embeds the skill instructions plus orchestration affordances (`spawn_agent`, `update_plan`).
+### 1. The chat LLM and MCP server profile
 
-### Skill-driven workflows
+```bash
+brainrouter config          # interactive — set LLM provider, model, key, endpoint
+brainrouter login           # interactive — set MCP server URL + API key
+```
 
-The CLI ships with a thin slash → skill mapping (see `brainrouter-cli/src/prompt/skillRunner.ts`). Slash commands do **not** carry monolithic hard-coded prompts; they delegate to the SKILL.md authored under `skills/`. This means improving a workflow is a documentation edit, not a code change. Add a new mapping in `SLASH_TO_SKILL` to expose a new slash command, or use `/skill <name>` to invoke any skill ad-hoc.
+Both write to `~/.config/brainrouter/config.json`.
 
-#### How the skill catalogue is discovered
+For local-model setups (LM Studio / Ollama), point the LLM endpoint at
+`http://localhost:1234/v1/chat/completions` or `http://localhost:11434/v1/chat/completions`.
 
-The CLI resolves a skill body in this order:
+### 2. (Optional) Runtime knobs — `~/.config/brainrouter/cli.env` or `./brainrouter-cli.env`
 
-1. **MCP `get_skill` tool** — the connected MCP server merges *global* skills (the canonical BrainRouter catalogue) with *local* skills the user authored under `<workspace>/skills/` or `<workspace>/projects/*/skills/`. Local skills shadow global ones on name conflict. This is the path used in normal operation.
-2. **Filesystem fallback** (used only when MCP is unreachable) searches, in order:
-   - `<workspace>/skills/**/SKILL.md`
-   - `<workspace>/.brainrouter/skills/**/SKILL.md`
-   - The installed `@kinqs/brainrouter-mcp-server` package directory (resolved via `require.resolve`). This works because the MCP package bundles the canonical catalogue at publish time (see below).
-3. Otherwise the CLI hands the agent a benign placeholder and asks it to use general judgement.
+Only needed if you want to tune sandbox, tool-loop limits, trace logging,
+or web-search backend. See the [`.env.example`](.env.example) bundled with
+this package for the full list. LLM credentials do **not** go here — they
+live in `config.json`.
 
-#### Catalogue bundling at publish time
+---
 
-The `@kinqs/brainrouter-mcp-server` package ships with the full BrainRouter skill catalogue baked in, so a user who only runs `npm install @kinqs/brainrouter-mcp-server @kinqs/brainrouter-cli` in their own workspace gets all 70+ canonical skills out of the box — no monorepo checkout required.
+## Run
 
-This is done via two lifecycle scripts in `brainrouter/scripts/`:
+```bash
+brainrouter                 # starts the interactive REPL
+brainrouter chat            # same — `chat` is the default subcommand
+brainrouter run "summarize the changes in src/"   # one-shot non-interactive
+brainrouter agents          # list child agent sessions in this workspace
+```
 
-- `prepack.mjs` — runs before `npm pack`/`npm publish`. Copies `skills/`, `agents/`, `references/`, and `docs/` from the monorepo root into the package directory and records what it copied in `.bundled-content.json`.
-- `postpack.mjs` — runs after pack. Reads the marker and removes exactly what `prepack` added, leaving the working tree clean.
+Inside the REPL, type `/help` for the full slash-command list (60+
+commands across session / memory / workflow / orchestration / observability
+surfaces).
 
-The MCP server's resolver ([brainrouter/src/resolver.ts](../brainrouter/src/resolver.ts)) prefers the package's own `skills/` when present (installed-package mode) and otherwise walks up to the monorepo root (development mode). Both layouts work identically from the CLI's point of view.
+### Offline mode
 
-### Durable workflow artifacts (one folder per workflow)
+If the MCP server isn't reachable, the CLI still boots — but only local
+tools (file edits, shell, web fetch, `spawn_agent`) work. Memory recall,
+capture, and skills are disabled until the server is back. The startup
+banner shows `⚠️  OFFLINE MODE` when this happens. Pass `--strict-mcp` to
+make the CLI exit instead of degrading.
 
-All multi-step commands (`/spec`, `/feature-dev`, `/review`, `/implement-plan`) anchor to a workflow slug and write their outputs to:
+### Stdio mode
 
-```
-<workspace>/.brainrouter/cli/workflows/<slug>/
-  meta.json        # { slug, title, kind, createdAt, updatedAt, status }
-  spec.md          # produced by /spec or /feature-dev phase 3
-  tasks.md         # produced by /feature-dev phase 3
-  walkthrough.md   # appended by /implement-plan as items ship
-  review.md        # produced by /review
-```
+If you'd rather have the CLI spawn the MCP server as a child process
+instead of running it separately, use `brainrouter config` → "Set Active
+Server Profile" → `default` (the bundled stdio profile). You don't need
+to run anything else — the CLI manages the server's lifecycle.
 
-The orchestration prompts for these commands **require** the agent to call `write_file` with the exact workspace-relative path — no chat-only plans. Use `/workflows` to inspect what's on disk. `getCurrentWorkflow` tracks the most recent one so `/implement-plan` appends to it automatically.
+---
 
-The system prompt also directs the agent to redirect free-form spec/plan requests to `/spec` or `/feature-dev` instead of producing inline monoliths, so the "one place" rule survives even when you don't type a slash command.
+## Workspace detection
 
-### Memory-native flow
+By default, the CLI uses the nearest project root with `AGENT.md`,
+`AGENTS.md`, or `.git`. Override with:
 
-Each parent turn runs three memory queries in parallel before the LLM sees the user prompt:
+```bash
+brainrouter --workspace /absolute/path/to/project
+# or
+BRAINROUTER_WORKSPACE=/absolute/path/to/project brainrouter
+```
 
-1. **`memory_recall`** — cognitive memory most relevant to the prompt.
-2. **`memory_working_context`** — current working canvas, so resumed sessions don't reset.
-3. **`memory_task_state`** — open tasks / handover notes for this workspace.
+Inside the REPL, run `/workspace` to confirm the active root and session key.
 
-The merged briefing (secrets redacted via `redactText`) is injected as a system message and the recalled record IDs are tracked through the whole turn. At end-of-turn, `selectCitedRecordIds` heuristically picks the records that actually informed the answer (by ID mention or distinctive content match) and reports them via `memory_mark_cited` — replacing the previous always-empty citation list, so System-1 recall actually learns.
+---
 
-Child agents (`spawn_agent`) skip the full briefing for speed but accept a `seedRecordIds: string[]` parameter so the parent can hand over what it already recalled. Long child outputs (≥ 6,000 chars) are automatically offloaded to `memory_working_offload` and only a preview + ref handle is returned to the parent — the main context-saving win when synthesizing multiple child reports.
+## What you also probably want
 
-After every turn, the CLI also asks `memory_contradictions` and surfaces a one-line warning in the REPL when newly-captured beliefs disagree with prior ones, so drift gets caught instead of silently accumulating.
+A BrainRouter MCP server for the cognitive memory. The CLI works without
+it (offline mode) but you lose recall, capture, and skills:
 
-Inspection commands:
+```bash
+npm install -g @kinqs/brainrouter-mcp-server
+brainrouter-mcp init                              # one-time: scaffold ~/.config/brainrouter/server.env
+$EDITOR ~/.config/brainrouter/server.env          # set BRAINROUTER_LLM_API_KEY, embeddings, etc.
+brainrouter-mcp --http --port 3747                # in a separate terminal
+```
 
-- `/memory <query>` — search long-term cognitive memory (`memory_search`).
-- `/recall <query>` — explicit `memory_recall`, no LLM turn.
-- `/briefing` — what was recalled before the most recent turn.
-- `/scenes` — list active focus scenes.
-- `/working` — current working-memory canvas.
-- `/forget <recordId>` — archive an obsolete memory.
+Then `brainrouter login` and point at `http://localhost:3747/mcp`.
 
-The workflow commands `/feature-dev`, `/review`, and `/implement-plan` are now required to open with `memory_search` (plus `memory_graph_query` / `memory_file_history` / `memory_task_state` depending on the workflow) and pass `seedRecordIds` to children, so no exploration is ever duplicated across sessions.
+---
 
-### Child agent permissions
+## Docs
 
-Child agents default to the safest mode for their role: `explorer`, `architect`, `reviewer` are `read`; `worker` is `write`; `verifier` is `shell`. Override with `access: "read" | "write" | "shell"` when calling `spawn_agent`. Shell execution from children runs unattended — only grant `shell` to trusted roles like `verifier`.
-- `/config` — Output active configuration details (with security sanitization for API keys).
-- `/compact` — Clear the active chat context while keeping the session identity.
-- `/clear` — Wipe the chat history of the active session.
-- `/exit` — Close connections and exit.
+- **Repo**: <https://github.com/kinqsradiollc/BrainRouter>
+- **Memory engine deep-dive**: [BRAINROUTER.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/BRAINROUTER.md)
+- **Maintainer runbook**: [SETUP.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/SETUP.md)
+- **Bugs / requests**: <https://github.com/kinqsradiollc/BrainRouter/issues>
 
 ---
 
-## Autonomous Tool Execution
-
-The agent coordinates two scopes of tools:
-1. **BrainRouter Memory Tools** (loaded dynamically via the MCP connection): `memory_recall`, `memory_capture_turn`, `list_skills`, etc.
-2. **Local Workspace Tools**:
-   - `read_file` — Reads content of a workspace file.
-   - `write_file` — Overwrites or writes a new file.
-   - `edit_file` — Performs safe single-match string search-and-replace.
-   - `list_dir` — Lists directory paths.
-   - `grep_search` — Platform-independent recursive search of code patterns.
-   - `run_command` — Runs a shell command on your host (always requests manual confirmation first for safety).
+## License
+
+MIT

package/dist/agent/agent.js

@@ -984,7 +984,7 @@ export class Agent {
                 try {
                     const res = await fetch(url, {
                         headers: {
-                            'User-Agent': 'Mozilla/5.0 (compatible; BrainRouterCLI/0.3.4)'
+                            'User-Agent': 'Mozilla/5.0 (compatible; BrainRouterCLI/0.3.5)'
                         }
                     });
                     if (!res.ok) {
@@ -1424,7 +1424,7 @@ async function runWebSearch(query, maxResults) {
     }
     try {
         const url = `https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_html=1&skip_disambig=1`;
-        const res = await fetch(url, { headers: { 'User-Agent': 'BrainRouterCLI/0.3.4' } });
+        const res = await fetch(url, { headers: { 'User-Agent': 'BrainRouterCLI/0.3.5' } });
         if (!res.ok) {
             return `web_search failed: DuckDuckGo returned ${res.status} ${res.statusText}.`;
         }

package/dist/cli/repl.js

@@ -50,7 +50,7 @@ const SLASH_COMMANDS = [
     '/experimental', '/memories', '/debug-config', '/mention', '/keymap', '/ide',
 ];
 export function startREPL(agent, mcpClient, config, workspace) {
-    console.log(chalk.bold.hex('#CC9166')('\n🧠 BRAINROUTER TERMINAL AGENT CLIENT v0.3.4'));
+    console.log(chalk.bold.hex('#CC9166')('\n🧠 BRAINROUTER TERMINAL AGENT CLIENT v0.3.5'));
     console.log(chalk.gray('Midnight Ledger / Obsidian Surface theme active.'));
     console.log(chalk.gray(`Workspace root: ${workspace?.workspaceRoot || process.cwd()}`));
     // Surface offline mode prominently — easy to miss the warning that scrolled

package/dist/index.js

@@ -165,7 +165,7 @@ const program = new Command();
 program
     .name('brainrouter')
     .description('BrainRouter CLI — Premium interactive terminal-based agent client.')
-    .version('0.3.4');
+    .version('0.3.5');
 // Chat Command (default)
 program
     .command('chat', { isDefault: true })

package/dist/runtime/mcpClient.js

@@ -14,7 +14,7 @@ export class McpClientWrapper {
      */
     connected = false;
     constructor() {
-        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.4' }, { capabilities: {} });
+        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.5' }, { capabilities: {} });
     }
     /** Whether this wrapper has an active MCP transport. */
     isConnected() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinqs/brainrouter-cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Memory-native terminal coding agent. Talks to the BrainRouter MCP cognitive engine for recall, skills, capture, persona, focus scenes, and contradiction tracking.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,8 +21,8 @@
     "prepack": "npm run build && find dist -name '*.test.*' -delete"
   },
   "dependencies": {
-    "@kinqs/brainrouter-sdk": "^0.3.4",
-    "@kinqs/brainrouter-types": "^0.3.4",
+    "@kinqs/brainrouter-sdk": "^0.3.5",
+    "@kinqs/brainrouter-types": "^0.3.5",
     "@modelcontextprotocol/sdk": "^1.11.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",