total-recall-brain 3.13.0 → 3.13.2

package/src/server/routes/webauthn.mjs

@@ -0,0 +1,184 @@
+/**
+ * WebAuthn / passkey routes for dashboard step-up (secret reveal).
+ *
+ * - GET  /api/webauthn/status
+ * - POST /api/webauthn/register/options
+ * - POST /api/webauthn/register/verify
+ * - POST /api/webauthn/assert/options
+ * - POST /api/webauthn/assert/verify   → { step_up_token }
+ * - POST /api/webauthn/step-up/password → { step_up_token } (fallback if no passkeys)
+ * - DELETE /api/webauthn/credentials/:id
+ */
+
+import express from 'express';
+import { requireAuth, requireScope, mintStepUpToken, verifyDashboardPassword } from '../auth.mjs';
+import { badRequest, serverError, BRAIN_DIR } from './_shared.mjs';
+import {
+  listPasskeys,
+  hasPasskeys,
+  beginRegistration,
+  finishRegistration,
+  beginAuthentication,
+  finishAuthentication,
+  deletePasskey,
+  resolveWebAuthnPath,
+} from '../../core/webauthn-store.mjs';
+import { logger } from '../../core/logger.mjs';
+
+const router = express.Router();
+
+function brainDir() {
+  return process.env.TR_SECRETS_BRAIN || BRAIN_DIR;
+}
+
+router.get('/api/webauthn/status', requireAuth, requireScope('keys:read', 'config:read'), (req, res) => {
+  try {
+    const dir = brainDir();
+    const passkeys = listPasskeys(dir);
+    res.json({
+      enabled: true,
+      has_passkeys: passkeys.length > 0,
+      count: passkeys.length,
+      passkeys,
+      store: resolveWebAuthnPath(dir),
+      // When false, UI may offer password re-entry as step-up fallback
+      password_step_up_allowed: true,
+    });
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.post(
+  '/api/webauthn/register/options',
+  requireAuth,
+  requireScope('keys:write', 'config:write'),
+  async (req, res) => {
+    try {
+      const options = await beginRegistration(brainDir(), req);
+      res.json(options);
+    } catch (err) {
+      logger.warn('webauthn', `register options failed: ${err.message}`);
+      return badRequest(res, err.message);
+    }
+  },
+);
+
+router.post(
+  '/api/webauthn/register/verify',
+  requireAuth,
+  requireScope('keys:write', 'config:write'),
+  async (req, res) => {
+    try {
+      const body = req.body || {};
+      const response = body.response || body;
+      if (!response?.id) return badRequest(res, 'WebAuthn registration response required');
+      const result = await finishRegistration(brainDir(), req, response, {
+        label: body.label,
+      });
+      res.status(201).json({
+        ...result,
+        passkeys: listPasskeys(brainDir()),
+      });
+    } catch (err) {
+      logger.warn('webauthn', `register verify failed: ${err.message}`);
+      return badRequest(res, err.message);
+    }
+  },
+);
+
+router.post(
+  '/api/webauthn/assert/options',
+  requireAuth,
+  requireScope('keys:read', 'config:read'),
+  async (req, res) => {
+    try {
+      const options = await beginAuthentication(brainDir(), req);
+      res.json(options);
+    } catch (err) {
+      return badRequest(res, err.message);
+    }
+  },
+);
+
+router.post(
+  '/api/webauthn/assert/verify',
+  requireAuth,
+  requireScope('keys:read', 'config:read'),
+  async (req, res) => {
+    try {
+      const body = req.body || {};
+      const response = body.response || body;
+      if (!response?.id) return badRequest(res, 'WebAuthn authentication response required');
+      const result = await finishAuthentication(brainDir(), req, response);
+      const step_up_token = mintStepUpToken({
+        purpose: body.purpose || 'secrets:reveal',
+        ttlSeconds: body.ttl_seconds || 60,
+        actor: 'passkey',
+      });
+      logger.info('webauthn', 'Passkey step-up granted', {
+        credentialId: result.credentialId,
+        purpose: body.purpose || 'secrets:reveal',
+      });
+      res.json({
+        verified: true,
+        step_up_token,
+        expires_in: body.ttl_seconds || 60,
+      });
+    } catch (err) {
+      logger.warn('webauthn', `assert verify failed: ${err.message}`);
+      return badRequest(res, err.message);
+    }
+  },
+);
+
+/** Password re-entry step-up (works always; preferred when no passkeys). */
+router.post(
+  '/api/webauthn/step-up/password',
+  requireAuth,
+  requireScope('keys:read', 'config:read'),
+  async (req, res) => {
+    try {
+      const password = req.body?.password;
+      if (!password) return badRequest(res, 'password is required');
+      const ok = await verifyDashboardPassword(password);
+      if (!ok) {
+        return res.status(401).json({ error: 'Invalid password' });
+      }
+      // If passkeys exist, still allow password as fallback but log it
+      if (hasPasskeys(brainDir())) {
+        logger.info('webauthn', 'Password step-up used while passkeys registered');
+      }
+      const step_up_token = mintStepUpToken({
+        purpose: req.body?.purpose || 'secrets:reveal',
+        ttlSeconds: req.body?.ttl_seconds || 60,
+        actor: 'password',
+      });
+      res.json({
+        verified: true,
+        method: 'password',
+        step_up_token,
+        expires_in: req.body?.ttl_seconds || 60,
+      });
+    } catch (err) {
+      serverError(res, err);
+    }
+  },
+);
+
+router.delete(
+  '/api/webauthn/credentials/:id',
+  requireAuth,
+  requireScope('keys:write', 'config:write'),
+  (req, res) => {
+    try {
+      const r = deletePasskey(brainDir(), req.params.id);
+      if (!r.found) return res.status(404).json({ error: 'Passkey not found' });
+      res.json({ deleted: true, passkeys: listPasskeys(brainDir()) });
+    } catch (err) {
+      serverError(res, err);
+    }
+  },
+);
+
+export { router as webauthnRouter };

package/src/server/update-route-manifest.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { restRouter } from './rest.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MANIFEST_PATH = path.join(__dirname, 'route-manifest.json');
+
+function extractRoutes(router) {
+  const routes = [];
+  function traverse(stack) {
+    if (!stack || !Array.isArray(stack)) return;
+    for (const layer of stack) {
+      if (layer.route) {
+        const pathStr = layer.route.path;
+        const methods = Object.keys(layer.route.methods)
+          .filter(m => layer.route.methods[m])
+          .map(m => m.toUpperCase());
+        for (const method of methods) {
+          routes.push({ method, path: pathStr });
+        }
+      } else if (layer.name === 'router' && layer.handle && layer.handle.stack) {
+        traverse(layer.handle.stack);
+      }
+    }
+  }
+  traverse(router.stack);
+  return routes;
+}
+
+const liveRoutes = extractRoutes(restRouter);
+const sortFn = (a, b) => {
+  const cmp = a.path.localeCompare(b.path);
+  if (cmp !== 0) return cmp;
+  return a.method.localeCompare(b.method);
+};
+liveRoutes.sort(sortFn);
+fs.writeFileSync(MANIFEST_PATH, JSON.stringify(liveRoutes, null, 2) + '\n');
+console.log('Updated route-manifest.json with ' + liveRoutes.length + ' routes');

package/templates/onboarding-interview.md

@@ -2,7 +2,7 @@
 type: task
 slug: onboarding-interview
 category: onboarding
-title: "Conduct user onboarding interview"
+title: "Conduct portable-memory onboarding interview"
 status: pending
 priority: 1
 created: {{CREATED_AT}}
@@ -11,49 +11,59 @@ updated: {{CREATED_AT}}
 
 ## Objective
 
-Conduct a warm, conversational onboarding interview with the user to deeply understand who they are, what they care about, and how you can best serve them. This is the most important task in the queue.
+Conduct a warm, practical onboarding interview so Total Recall can store durable preferences and facts as Markdown memory nodes. This is personal portable memory — not an operating system takeover. Keep the tone helpful and concrete.
 
 ## Instructions for the Agent
 
-When the user starts their next chat session, you MUST conduct this interview BEFORE doing any other work. Do NOT dump all the questions at once. Ask them one at a time, naturally, like a thoughtful conversation. Acknowledge and reflect on each answer before asking the next question.
+When the user starts their next chat session (and they have no `user-profile` yet), conduct this interview BEFORE unrelated work. Do NOT dump all questions at once. Ask one at a time. Acknowledge each answer before the next.
 
-Once the user has answered all questions (or says they want to skip any), write their answers into the vault immediately using your file tools.
+Once the user has answered (or skipped any), write their answers into the vault using tools / CLI (`remember` or direct vault writes). Prefer CLI when available:
 
-## Interview Questions (ask one at a time, conversationally)
+```bash
+npx total-recall remember preference "..." --tags "user,profile,onboarding" --importance 5
+```
+
+## Interview Questions (ask one at a time)
+
+1. **Who are you?** — "Quick intro: what do you do, and what are you most focused on right now?"
 
-1. **Who are you?** — "To get started, can you tell me a bit about yourself? What do you do for work or what are you most focused on in life right now?"
+2. **What should I remember?** — "What kinds of things matter most for me to keep: decisions, preferences, project facts, people, or something else?"
 
-2. **What are you working on?** — "What are the main projects or goals you're working toward? These could be professional, personal, creative — anything you want me to help you with."
+3. **Which tools do you use?** — "Which IDEs or agents should share this memory? (Claude Code, Cursor, Codex, Gemini, Aider, Obsidian, HTTP, etc.) I can guide you with `npx total-recall connect …`."
 
-3. **What do you want to remember?** — "What kinds of things are most important for me to keep track of for you? (Ideas, research, decisions, people, tasks, reading, etc.)"
+4. **How should I talk?** — "Prefer short answers or detailed ones? Should I push back or mostly support?"
 
-4. **What topics excite you?** — "What subjects, fields, or areas of knowledge do you find yourself coming back to? What should I research and follow for you automatically?"
+5. **Hard rules** — "Any absolute do's or don'ts I must always follow (style, tools, safety)?"
 
-5. **How do you like to communicate?** — "Do you prefer direct, brief answers or detailed explanations? Do you want me to push back on ideas or mostly support your thinking?"
+6. **Background work** — "Want dream consolidation and optional daemon tasks running in the background, or on-demand only?"
 
-6. **What frustrates you?** — "Is there anything that drives you crazy — things you keep forgetting, information that's hard to find, tasks that slip through the cracks?"
+7. **Secrets** — "API keys never go in the vault. Use `npx total-recall secret set`. Any keys you want to set up next?"
 
-7. **What would success look like?** — "Six months from now, if I've done my job perfectly, what would be different for you?"
+8. **Notifications (optional)** — "Want Telegram pings when background tasks finish? If yes, BotFather token + chat ID."
 
-8. **Telegram Notifications** — "Would you like me to message you on Telegram when I finish background tasks or find something interesting during my idle time? If yes, you'll need to create a bot on Telegram via BotFather and give me the Bot Token and your Chat ID."
+## Product context to reinforce (lightly, not as a lecture)
+
+- **Write** → `remember` / session ingest  
+- **Sleep** → `dream` (consolidate, conflict-check, recompile)  
+- **Read** → `recall` + compiled surfaces in any connected IDE  
+- **Async** → open task queue / daemon under policy  
+- Hosts are equal — track any repo; no product-specific hardcoding
 
 ## After the Interview
 
-Write the following files using your terminal tools:
+Write (or update) these files:
 
-**`.agent/config/notifications.yml`** — If they provided Telegram details, write them exactly like this:
+**`.agent/config/notifications.yml`** — only if they provided Telegram details:
 ```yaml
 telegram_bot_token: "their-token-here"
 telegram_chat_id: "their-chat-id-here"
 ```
 
-**`.agent/memory-vault/preferences/user-profile.md`** — Full SSSS memory node with the user's identity, role, and communication style.
-
-**`.agent/memory-vault/preferences/user-priorities.md`** — SSSS memory node listing the user's top goals, active projects, and what they want from Total Recall.
-
-**`.agent/memory-vault/preferences/user-interests.md`** — SSSS memory node listing topics to research autonomously.
+**`.agent/memory-vault/preferences/user-profile.md`** — identity + communication style  
+**`.agent/memory-vault/preferences/user-priorities.md`** — goals and what they want from memory  
+**`.agent/memory-vault/preferences/user-interests.md`** — topics worth tracking
 
-Use this frontmatter template for each file:
+Frontmatter template:
 ```yaml
 ---
 type: memory
@@ -69,4 +79,4 @@ tags: [user, profile, onboarding]
 ---
 ```
 
-After writing the files, mark this task `status: done` and confirm to the user that their profile has been saved.
+Then mark this task `status: done` and confirm the profile was saved. Point them at the dashboard **Onboarding** page or `init → connect → remember → dream` if they prefer CLI-only.

package/templates/openwiki/README.md

@@ -0,0 +1,10 @@
+# OpenWiki
+
+Portable knowledge documentation for this Total Recall brain.
+
+| Layer | Purpose |
+|-------|---------|
+| **Memory vault** | SSSS nodes (rules, prefs, facts) — machine-enforceable |
+| **OpenWiki** | Human/agent docs (architecture, how-tos, stack notes) |
+
+OpenWiki ships with Total Recall. Edit freely; do not put secrets here.

package/templates/openwiki/architecture.md

@@ -0,0 +1,5 @@
+# Architecture (this brain)
+
+Describe the systems this brain cares about: repos, stacks, deploy targets.
+
+Project brains should document the local codebase; the global brain documents cross-repo identity and preferences.

package/templates/openwiki/ide.md

@@ -0,0 +1,10 @@
+# IDE personalization
+
+```bash
+npx total-recall connect claude-code   # CLAUDE.md
+npx total-recall connect codex         # AGENTS.md
+npx total-recall connect cursor        # .cursor/rules/
+npx total-recall connect gemini        # GEMINI.md
+```
+
+Total Recall only writes inside managed inject markers. Your local rules stay intact.

package/templates/openwiki/memory.md

@@ -0,0 +1,11 @@
+# Memory
+
+Use the Total Recall CLI for durable memory:
+
+```bash
+npx total-recall remember invariant "Never commit secrets." --importance 5
+npx total-recall recall "secrets"
+npx total-recall compile
+```
+
+Categories: invariants, preferences, facts, decisions, patterns, anti-patterns, concepts, lore.

package/templates/openwiki/secrets.md

@@ -0,0 +1,7 @@
+# Secrets & API keys
+
+Store credentials in Total Recall's secrets store (`config/secrets.enc` / future CLI).
+
+**Never** put API keys in openwiki pages or compiled IDE instruction files.
+
+Planned CLI surface (TR_CORE_FOCUS Phase 4): `secret set|list|rotate|audit` and usage/cost meters.

package/templates/openwiki/skills.md

@@ -0,0 +1,7 @@
+# Skills
+
+- **Total Recall skill** (only nested agent skill): `.agent/skills/total-recall/SKILL.md`
+- **User skills**: `.agent/skills/<name>/SKILL.md` — project or global
+- **TR modules** (not skills): `.agent/skills/total-recall/modules/` — internal docs/scripts
+
+TR will track skill installs across repos and support adaptive deploy (see TR_CORE_FOCUS).

package/scaffold/.agent/skills/total-recall/skills/tr-cli-agents/SKILL.md

@@ -1,121 +0,0 @@
----
-name: tr-cli-agents
-provenance: total-recall
-description: "Orchestrate headlessly spawned CLI agents from the central registry."
----
-
-# CLI Agents — Headless Multi-Agent Orchestration & Dispatch Engine
-
-This system skill governs the discovery, configuration, and execution of headless **CLI Agents** within the Total Recall Sovereign OS. It replaces local models (via Ollama/Gemma) with a high-speed, parallelized dispatch engine that orchestrates elite external developer agents (`antigravity`, `gemini`, `claude`, `codex`) via synchronous subprocess execution (`spawnSync`).
-
----
-
-## 🎯 SYSTEM OVERVIEW
-
-The CLI Agent Dispatch Engine parses agent profiles from the central registry file:
-`.agent/skills/total-recall/skills/tr-cli-agents/agents.yml`
-
-```mermaid
-flowchart TD
-    User[Chat Request / Dispatch Event] --> Engine[Dispatch Engine]
-    Engine --> Registry[Load cli-agents/agents.yml]
-    Registry --> Router{Select Enabled Agent}
-    
-    Router -->|Antigravity| AG[spawnSync: 'antigravity']
-    Router -->|Gemini| GM[spawnSync: 'gemini']
-    Router -->|Claude Code| CC[spawnSync: 'claude']
-    Router -->|Codex CLI| CX[spawnSync: 'codex']
-    
-    AG & GM & CC & CX --> Out[Parse JSON Output]
-    Out --> Response[Consolidated Response & Memory Ingestion]
-```
-
-### Core Execution Modality
-To maintain deterministic control, security compliance, and bypass complex permission prompts, agents are headlessly spawned with custom default models, auto-accept parameters, and yolo bypass flags configured per-binary.
-
----
-
-## 📂 REGISTRY CONFIGURATION (`agents.yml`)
-
-The primary configuration format defines active binaries, default flags, priorities, and execution modes:
-
-```yaml
-agents:
-  - name: antigravity
-    binary: antigravity
-    flags: --sandbox=false --yolo -o json
-    priority: 1
-    enabled: true
-    exec: flag
-  - name: gemini
-    binary: gemini
-    flags: --sandbox=false --yolo -o json
-    priority: 2
-    enabled: true
-    exec: flag
-  - name: claude
-    binary: claude
-    flags: --output-format json --permission-mode bypassPermissions
-    priority: 3
-    enabled: true
-    exec: flag
-  - name: codex
-    binary: codex
-    flags: --full-auto --json
-    priority: 4
-    enabled: true
-    exec: subcommand
-timeout: 300
-max_retries: 2
-```
-
-### Key Execution Modes (`exec`)
-*   **`flag`**: Appends input strings or JSON schemas as standard execution flags directly to the command invocation.
-*   **`subcommand`**: Passes execution commands as a nested subcommand (e.g., `codex run --payload=...`).
-
----
-
-## 🛡️ SECURITY & COMPLIANCE
-
-1.  **Strict Sandbox Isolation**: When running third-party code generated during multi-agent dispatches, dispatches MUST enforce `--sandbox=true` unless explicitly overridden by `security.yml` locality rules.
-2.  **State Verification**: The dispatch engine captures and parses `stderr` streams separately. Any unhandled exit code > 0 automatically raises a fallback sequence to the next enabled agent in the priority queue.
-3.  **Authentication Handshake**: All spawned dispatches carry the active brain PAT token securely mapped via the `TR_PAT` environment variable to ensure seamless VFS memory access during execution.
-
----
-
-## ⚠️ HARD-EARNED LESSONS & RECOVERY MANUAL (CRITICAL RUNTIME KNOWLEDGE)
-
-The following architectural realities represent hard-earned technical breakthroughs required to ensure 100% stable execution of the `antigravity` agent and associated background dispatch loops. **DO NOT DEVIATE from these patterns during future updates or refactoring sessions.**
-
-### 1. macOS LaunchAgent & Background Process PATH Isolation Pathology
-*   **The Problem**: Background execution managers (like macOS LaunchAgents, cron jobs, and daemon processes) boot with a highly restricted, shell-isolated environment. This results in an empty or deeply stripped `$PATH` variable.
-*   **The Pathology**: Spawning standard child processes (such as `spawnSync('which antigravity')`) under these contexts fails silently or throws empty strings, making active agents completely undiscoverable even if they are globally linked or installed.
-*   **The Immutable Resolution**:
-    1.  **Boot PATH Expansion**: Maintain proactive PATH expansion at the absolute top of the configuration system ([src/core/config.mjs](file:///Users/greg/Github/total-recall/src/core/config.mjs)) to expand `$PATH` using verified node versions and standard locations before any other logic compiles.
-    2.  **Pure JS Resolver (`findBinaryInPath`)**: Never spawn external process calls (like `which`) for discovery. Instead, use the native Node.js filesystem resolver (`findBinaryInPath` in [src/core/runtime.mjs](file:///Users/greg/Github/total-recall/src/core/runtime.mjs)) which checks stat entries (`fs.statSync`) and file execution modes directly against path segments.
-
-### 2. Gemini API Active Model Realities (2026)
-*   **The Problem**: Many standard or legacy model mappings are deprecated, causing silent failures or standard `404` errors directly from the Google API endpoints.
-*   **The Pathology**:
-    -   `gemini-2.0-flash` is deprecated on modern API profiles and returns a `404` error for standard generation calls.
-    -   `gemini-3.1-flash-live-preview` exists in the model registry but is restricted to audio/bidi streaming (`bidiGenerateContent`) and throws error codes for standard text generation.
-*   **The Immutable Resolution**:
-    1.  **Frontier Default**: Always default standard text dispatches directly to **`gemini-3.5-flash`** (verified active).
-    2.  **Alias Mapping**: Maintain the robust alias mapping inside the CLI agent wrapper to dynamically map generic aliases to verified, functional frontier models:
-        -   `gemini`, `default`, `flash`, `gemini-flash`, `3.5-flash` $\to$ **`gemini-3.5-flash`**
-        -   `pro`, `gemini-pro`, `3.1-pro` $\to$ **`gemini-3.1-pro-preview`**
-
-### 3. Standalone CLI Ingestion & Budget Safety compliance
-*   **The Problem**: Standalone executions of custom CLI wrappers (like `antigravity`) run outside the main Express route controllers, making their token spend completely invisible to local tracking tools.
-*   **The Pathology**: The `total-recall` budget safety system ([src/core/usage-tracker.mjs](file:///Users/greg/Github/total-recall/src/core/usage-tracker.mjs)) scans `~/.gemini/tmp/<folder>/chats/*.jsonl` to calculate daily/weekly spending. If an agent does not log its token metadata upon execution, the budget watchdog remains blind to its consumption, leaving the user vulnerable to rate limit bans or massive billing spikes.
-*   **The Immutable Resolution**:
-    -   The `antigravity` wrapper *must* capture `usageMetadata` (`promptTokenCount` and `candidatesTokenCount`) from successful API responses and append it directly as a standard JSONL line to:
-        `~/.gemini/tmp/antigravity/chats/usage.jsonl`
-    -   This guarantees perfect compliance and zero-leak tracking under both manual shell executions and high-throughput background daemon runs.
-
-### 4. System-Wide CLI Agent Ingestion & Inherent Tracking Mechanics
-To maintain accurate monitoring and ensure budget safeties remain 100% synchronized across all reasoning tasks, the central `usage-tracker` scans and parses execution metrics dynamically per agent:
-*   **`claude` (Claude Code)**: Automatically writes local logs to `~/.claude/stats-cache.json`. Total Recall parses this file on demand to sum token usages and calculate current expenditure.
-*   **`codex` (OpenAI Codex CLI)**: Appends JSONL logs recursively under `~/.codex/sessions/`. Total Recall traverses this folder structure and aggregates `prompt_tokens` and `completion_tokens` directly.
-*   **`gemini` (Standard Gemini CLI)**: Saves chat history files ending with `.jsonl` directly to `~/.gemini/tmp/<hash>/chats/`. Total Recall reads the `tokens.input` and `tokens.output` fields for each log turn.
-*   **`antigravity` (Native Agent Wrapper)**: Replicates standard Gemini CLI structure by appending token entries directly to `~/.gemini/tmp/antigravity/chats/usage.jsonl` on every single query turn, ensuring full compliance with the central tracking core.

package/scaffold/.agent/skills/total-recall/skills/tr-cli-agents/references/antigravity.txt

@@ -1,20 +0,0 @@
-Antigravity CLI Agent Wrapper — Headless Zero-Dependency Cognitive Agent
-
-Usage:
-  antigravity [options] [prompt]
-  antigravity -p "prompt"
-
-Options:
-  -p, --prompt    The text prompt to generate content for
-  -m, --model     Gemini API model identifier or alias (default: gemini-3.5-flash)
-                  Supported aliases:
-                    - flash / gemini-flash / 3.5-flash -> gemini-3.5-flash (Frontier default)
-                    - pro / gemini-pro / 3.1-pro       -> gemini-3.1-pro-preview (Frontier Pro)
-  -o, --json      Output dynamic JSON response payload (choices: stream/json/default)
-  --json          Output dynamic JSON response payload
-  -h, --help      Show this help information
-
-Examples:
-  antigravity "Say hello"
-  antigravity -p "Write an essay about AI" -m pro
-  antigravity -p "Get system stats" --json

package/scaffold/.agent/skills/total-recall/skills/tr-cli-agents/references/claude.txt

@@ -1,58 +0,0 @@
-Usage: claude [options] [command] [prompt]
-
-Claude Code - starts an interactive session by default, use -p/--print for
-non-interactive output
-
-Arguments:
-  prompt                                            Your prompt
-
-Options:
-  --add-dir <directories...>                        Additional directories to allow tool access to
-  --agent <agent>                                   Agent for the current session. Overrides the 'agent' setting.
-  --agents <json>                                   JSON object defining custom agents (e.g. '{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}')
-  --allow-dangerously-skip-permissions              Enable bypassing all permission checks as an option, without it being enabled by default. Recommended only for sandboxes with no internet access.
-  --allowedTools, --allowed-tools <tools...>        Comma or space-separated list of tool names to allow (e.g. "Bash(git:*) Edit")
-  --append-system-prompt <prompt>                   Append a system prompt to the default system prompt
-  --betas <betas...>                                Beta headers to include in API requests (API key users only)
-  --chrome                                          Enable Claude in Chrome integration
-  -c, --continue                                    Continue the most recent conversation in the current directory
-  --dangerously-skip-permissions                    Bypass all permission checks. Recommended only for sandboxes with no internet access.
-  -d, --debug [filter]                              Enable debug mode with optional category filtering (e.g., "api,hooks" or "!statsig,!file")
-  --disable-slash-commands                          Disable all skills
-  --disallowedTools, --disallowed-tools <tools...>  Comma or space-separated list of tool names to deny (e.g. "Bash(git:*) Edit")
-  --fallback-model <model>                          Enable automatic fallback to specified model when default model is overloaded (only works with --print)
-  --file <specs...>                                 File resources to download at startup. Format: file_id:relative_path (e.g., --file file_abc:doc.txt file_def:img.png)
-  --fork-session                                    When resuming, create a new session ID instead of reusing the original (use with --resume or --continue)
-  -h, --help                                        Display help for command
-  --ide                                             Automatically connect to IDE on startup if exactly one valid IDE is available
-  --include-partial-messages                        Include partial message chunks as they arrive (only works with --print and --output-format=stream-json)
-  --input-format <format>                           Input format (only works with --print): "text" (default), or "stream-json" (realtime streaming input) (choices: "text", "stream-json")
-  --json-schema <schema>                            JSON Schema for structured output validation. Example: {"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}
-  --max-budget-usd <amount>                         Maximum dollar amount to spend on API calls (only works with --print)
-  --mcp-config <configs...>                         Load MCP servers from JSON files or strings (space-separated)
-  --mcp-debug                                       [DEPRECATED. Use --debug instead] Enable MCP debug mode (shows MCP server errors)
-  --model <model>                                   Model for the current session. Provide an alias for the latest model (e.g. 'sonnet' or 'opus') or a model's full name (e.g. 'claude-sonnet-4-5-20250929').
-  --no-chrome                                       Disable Claude in Chrome integration
-  --no-session-persistence                          Disable session persistence - sessions will not be saved to disk and cannot be resumed (only works with --print)
-  --output-format <format>                          Output format (only works with --print): "text" (default), "json" (single result), or "stream-json" (realtime streaming) (choices: "text", "json", "stream-json")
-  --permission-mode <mode>                          Permission mode to use for the session (choices: "acceptEdits", "bypassPermissions", "default", "delegate", "dontAsk", "plan")
-  --plugin-dir <paths...>                           Load plugins from directories for this session only (repeatable)
-  -p, --print                                       Print response and exit (useful for pipes). Note: The workspace trust dialog is skipped when Claude is run with the -p mode. Only use this flag in directories you trust.
-  --replay-user-messages                            Re-emit user messages from stdin back on stdout for acknowledgment (only works with --input-format=stream-json and --output-format=stream-json)
-  -r, --resume [value]                              Resume a conversation by session ID, or open interactive picker with optional search term
-  --session-id <uuid>                               Use a specific session ID for the conversation (must be a valid UUID)
-  --setting-sources <sources>                       Comma-separated list of setting sources to load (user, project, local).
-  --settings <file-or-json>                         Path to a settings JSON file or a JSON string to load additional settings from
-  --strict-mcp-config                               Only use MCP servers from --mcp-config, ignoring all other MCP configurations
-  --system-prompt <prompt>                          System prompt to use for the session
-  --tools <tools...>                                Specify the list of available tools from the built-in set. Use "" to disable all tools, "default" to use all tools, or specify tool names (e.g. "Bash,Edit,Read").
-  --verbose                                         Override verbose mode setting from config
-  -v, --version                                     Output the version number
-
-Commands:
-  doctor                                            Check the health of your Claude Code auto-updater
-  install [options] [target]                        Install Claude Code native build. Use [target] to specify version (stable, latest, or specific version)
-  mcp                                               Configure and manage MCP servers
-  plugin                                            Manage Claude Code plugins
-  setup-token                                       Set up a long-lived authentication token (requires Claude subscription)
-  update                                            Check for updates and install if available