brainclaw 0.22.1 → 0.23.1

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import path from 'node:path';
 import { Command } from 'commander';
 import { runInit } from './commands/init.js';
 import { runSetup } from './commands/setup.js';
@@ -78,6 +79,8 @@ import { runExplore } from './commands/explore.js';
 import { getInstalledBrainclawVersion } from './core/brainclaw-version.js';
 import { cleanOrphanFiles, memoryDir } from './core/io.js';
 import { initLogLevel, logger } from './core/logger.js';
+import { resolveEffectiveCwd } from './core/store-resolution.js';
+import { runSwitch } from './commands/switch.js';
 const program = new Command();
 function collect(value, previous) {
     return [...previous, value];
@@ -88,12 +91,30 @@ program
     .version(getInstalledBrainclawVersion())
     .option('--verbose', 'Show info-level log messages on stderr')
     .option('--debug', 'Show debug-level log messages on stderr')
+    .option('--cwd <path>', 'Override working directory for this invocation')
     .hook('preAction', (_thisCommand, actionCommand) => {
     const root = actionCommand.optsWithGlobals();
     initLogLevel({ verbose: root.verbose, debug: root.debug });
-    const removed = cleanOrphanFiles(memoryDir());
-    if (removed > 0) {
-        logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
+    // Skip effective cwd resolution for commands that create the store
+    const cmdName = actionCommand.name();
+    const skipResolution = cmdName === 'init' || cmdName === 'setup';
+    if (!skipResolution) {
+        // Resolve effective cwd (--cwd > BRAINCLAW_PROJECT > active-project > process.cwd)
+        const effectiveCwd = resolveEffectiveCwd({ explicitCwd: root.cwd });
+        if (effectiveCwd !== process.cwd()) {
+            // Change process.cwd() so all commands resolve the correct store
+            // without needing individual --cwd plumbing
+            process.chdir(effectiveCwd);
+            logger.info(`Resolved effective cwd: ${effectiveCwd}`);
+        }
+        const removed = cleanOrphanFiles(memoryDir());
+        if (removed > 0) {
+            logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
+        }
+    }
+    else if (root.cwd) {
+        // For init/setup, still respect explicit --cwd but nothing else
+        process.chdir(path.resolve(root.cwd));
     }
 });
 // --- init ---
@@ -1090,6 +1111,21 @@ program
     .action((options) => {
     runExplore({ query: options.query });
 });
+program
+    .command('switch [project]')
+    .description('Set the active project for subsequent commands')
+    .option('--list', 'List available projects in the workspace')
+    .option('--clear', 'Clear the active project (revert to cwd)')
+    .option('--json', 'Output as JSON')
+    .action((project, options) => {
+    const globalOpts = options.parent?.parent ? program.opts() : {};
+    runSwitch(project, {
+        list: options.list,
+        clear: options.clear,
+        json: options.json,
+        cwd: globalOpts.cwd,
+    });
+});
 program.parseAsync(process.argv).catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/commands/mcp.js

@@ -29,7 +29,7 @@ import { validateMcpInput, validateMcpField } from '../core/input-validation.js'
 import { buildEstimationReport } from './estimation-report.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
-import { resolveTargetStore, resolveStoreChain } from '../core/store-resolution.js';
+import { resolveEffectiveCwd, resolveTargetStore, resolveStoreChain } from '../core/store-resolution.js';
 import { probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview } from '../core/setup-flow.js';
 import { ensureUserStore } from '../core/setup-state.js';
 import { readUnseenEvents, buildNotificationSummary } from '../core/event-log.js';
@@ -888,7 +888,7 @@ export class McpServerConnection {
     }
 }
 export function runMcp() {
-    const cwd = process.cwd();
+    const cwd = resolveEffectiveCwd();
     if (!memoryExists(cwd)) {
         console.error('Project memory not initialized. Run `brainclaw init` first.');
         process.exit(1);
@@ -991,7 +991,7 @@ function getReviewAssignee(tags) {
     return undefined;
 }
 export function handleMcpReadToolCall(name, args = {}, context = {}) {
-    const cwd = context.cwd ?? process.cwd();
+    const cwd = context.cwd ?? resolveEffectiveCwd();
     if (name === 'bclaw_get_context') {
         const result = buildContext({
             target: args.path,

package/dist/commands/switch.js

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
+import { memoryExists } from '../core/io.js';
+import { resolveProjectRef, resolveWorkspaceRoot } from '../core/store-resolution.js';
+import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
+import { loadConfig } from '../core/config.js';
+export function runSwitch(projectRef, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const wsRoot = resolveWorkspaceRoot(cwd);
+    if (!wsRoot) {
+        console.error('Error: no brainclaw workspace found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    // --list: show available projects
+    if (options.list) {
+        listProjects(wsRoot, options.json ?? false);
+        return;
+    }
+    // --clear: remove active project
+    if (options.clear) {
+        clearActiveProject(wsRoot);
+        if (options.json) {
+            console.log(JSON.stringify({ cleared: true }));
+        }
+        else {
+            console.log('✔ Active project cleared. Commands will use current directory.');
+        }
+        return;
+    }
+    // No argument: show current active project
+    if (!projectRef) {
+        showCurrent(wsRoot, options.json ?? false);
+        return;
+    }
+    // Switch to project
+    const resolved = resolveProjectRef(projectRef, cwd);
+    if (!resolved) {
+        console.error(`Error: cannot resolve project "${projectRef}".`);
+        console.error('Use `brainclaw switch --list` to see available projects.');
+        process.exit(1);
+    }
+    let projectName;
+    try {
+        const config = loadConfig(resolved);
+        projectName = config.project_name;
+    }
+    catch {
+        // name is optional
+    }
+    saveActiveProject(wsRoot, {
+        path: resolved,
+        name: projectName,
+        switched_at: new Date().toISOString(),
+        switched_by: process.env.BRAINCLAW_AGENT_NAME ?? process.env.USER ?? 'unknown',
+    });
+    if (options.json) {
+        console.log(JSON.stringify({ switched: true, path: resolved, name: projectName }));
+    }
+    else {
+        const rel = path.relative(wsRoot, resolved) || '.';
+        console.log(`✔ Switched to ${projectName ? `"${projectName}" (${rel})` : rel}`);
+    }
+}
+function showCurrent(wsRoot, json) {
+    const active = loadActiveProject(wsRoot);
+    if (!active) {
+        if (json) {
+            console.log(JSON.stringify({ active: false }));
+        }
+        else {
+            console.log('No active project. Commands use current directory.');
+            console.log('Use `brainclaw switch <project>` to set one.');
+        }
+        return;
+    }
+    const rel = path.relative(wsRoot, active.path) || '.';
+    if (json) {
+        console.log(JSON.stringify({ active: true, ...active, relative_path: rel }));
+    }
+    else {
+        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}`);
+        console.log(`  switched at: ${active.switched_at}`);
+        if (active.switched_by)
+            console.log(`  switched by: ${active.switched_by}`);
+    }
+}
+function listProjects(wsRoot, json) {
+    const active = loadActiveProject(wsRoot);
+    const projects = [];
+    // Add workspace root itself
+    if (memoryExists(wsRoot)) {
+        try {
+            const config = loadConfig(wsRoot);
+            projects.push({
+                name: config.project_name,
+                path: wsRoot,
+                relative_path: '.',
+                active: active?.path === wsRoot,
+            });
+        }
+        catch {
+            projects.push({
+                path: wsRoot,
+                relative_path: '.',
+                active: active?.path === wsRoot,
+            });
+        }
+    }
+    // Discover child projects (depth 7 covers deep workspace layouts like /srv/dev/repos/global/applications/*/...)
+    const children = scanNestedBrainclawProjects(wsRoot, 7);
+    for (const child of children) {
+        const childPath = path.resolve(child.path);
+        if (childPath === wsRoot)
+            continue;
+        const rel = path.relative(wsRoot, childPath) || '.';
+        projects.push({
+            name: child.project_name,
+            path: childPath,
+            relative_path: rel,
+            active: active?.path === childPath,
+        });
+    }
+    if (json) {
+        console.log(JSON.stringify({ workspace: wsRoot, projects }, null, 2));
+        return;
+    }
+    if (projects.length === 0) {
+        console.log('No brainclaw projects found in this workspace.');
+        return;
+    }
+    console.log(`Projects in ${wsRoot}:\n`);
+    for (const p of projects) {
+        const marker = p.active ? '→ ' : '  ';
+        const name = p.name ? `${p.name} (${p.relative_path})` : p.relative_path;
+        console.log(`${marker}${name}`);
+    }
+    if (!active) {
+        console.log('\nNo active project. Use `brainclaw switch <project>` to set one.');
+    }
+}
+//# sourceMappingURL=switch.js.map

package/dist/core/active-project.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MEMORY_DIR } from './io.js';
+const ACTIVE_PROJECT_FILE = 'active-project.json';
+/**
+ * Load the active project for a workspace.
+ * Returns undefined when no active project is set or the file is unreadable.
+ */
+export function loadActiveProject(workspaceRoot) {
+    const filePath = path.join(workspaceRoot, MEMORY_DIR, ACTIVE_PROJECT_FILE);
+    if (!fs.existsSync(filePath)) {
+        return undefined;
+    }
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (typeof raw.path !== 'string' || !raw.path) {
+            return undefined;
+        }
+        return {
+            path: raw.path,
+            name: typeof raw.name === 'string' ? raw.name : undefined,
+            switched_at: typeof raw.switched_at === 'string' ? raw.switched_at : new Date().toISOString(),
+            switched_by: typeof raw.switched_by === 'string' ? raw.switched_by : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist the active project for a workspace.
+ */
+export function saveActiveProject(workspaceRoot, project) {
+    const dir = path.join(workspaceRoot, MEMORY_DIR);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const filePath = path.join(dir, ACTIVE_PROJECT_FILE);
+    fs.writeFileSync(filePath, JSON.stringify(project, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Clear the active project (revert to process.cwd() default).
+ */
+export function clearActiveProject(workspaceRoot) {
+    const filePath = path.join(workspaceRoot, MEMORY_DIR, ACTIVE_PROJECT_FILE);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+}
+//# sourceMappingURL=active-project.js.map

package/dist/core/store-resolution.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { loadActiveProject } from './active-project.js';
 import { loadConfig } from './config.js';
 import { MEMORY_DIR } from './io.js';
 import { summarizeWorkspaceProjects } from './workspace-projects.js';
@@ -84,6 +85,98 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
     const match = chain.find((s) => s.role === 'user');
     return match?.cwd ?? os.homedir();
 }
+/**
+ * Single source of truth for the effective working directory.
+ *
+ * Priority:
+ * 1. explicitCwd (--cwd flag)
+ * 2. BRAINCLAW_PROJECT env var → resolved by name/path from workspace
+ * 3. active-project.json in workspace root
+ * 4. process.cwd()
+ */
+export function resolveEffectiveCwd(options = {}) {
+    // 1. Explicit --cwd flag
+    if (options.explicitCwd) {
+        return path.resolve(options.explicitCwd);
+    }
+    // 2. BRAINCLAW_PROJECT env var
+    const envProject = process.env.BRAINCLAW_PROJECT;
+    if (envProject) {
+        const resolved = resolveProjectRef(envProject, process.cwd(), options.storeChainOptions);
+        if (resolved)
+            return resolved;
+    }
+    // 3. active-project.json from workspace root
+    const wsRoot = resolveWorkspaceRoot(process.cwd(), options.storeChainOptions);
+    if (wsRoot) {
+        const active = loadActiveProject(wsRoot);
+        if (active && fs.existsSync(path.join(active.path, MEMORY_DIR, 'config.yaml'))) {
+            return active.path;
+        }
+    }
+    // 4. Default
+    return process.cwd();
+}
+/**
+ * Find the workspace root (farthest store in the chain, or the one with
+ * role=workspace). Returns undefined when no store exists.
+ */
+export function resolveWorkspaceRoot(cwd = process.cwd(), options = {}) {
+    const chain = resolveStoreChain(cwd, options);
+    if (chain.length === 0)
+        return undefined;
+    const ws = chain.find((s) => s.role === 'workspace');
+    return ws?.cwd ?? chain[chain.length - 1].cwd;
+}
+/**
+ * Resolve a project reference (name or relative path) to an absolute path.
+ * Returns undefined when the reference cannot be resolved to a valid brainclaw project.
+ */
+export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
+    const wsRoot = resolveWorkspaceRoot(cwd, storeChainOptions);
+    if (!wsRoot)
+        return undefined;
+    // Try as absolute path
+    if (path.isAbsolute(ref)) {
+        return fs.existsSync(path.join(ref, MEMORY_DIR, 'config.yaml')) ? ref : undefined;
+    }
+    // Try as relative path from workspace root
+    const asPath = path.resolve(wsRoot, ref);
+    if (fs.existsSync(path.join(asPath, MEMORY_DIR, 'config.yaml'))) {
+        return asPath;
+    }
+    // Try by project name: scan child stores for matching project_name
+    const chain = resolveStoreChain(wsRoot, storeChainOptions);
+    for (const store of chain) {
+        if (store.cwd === wsRoot)
+            continue; // skip workspace itself
+        try {
+            const config = loadConfig(store.cwd);
+            if (config.project_name === ref)
+                return store.cwd;
+        }
+        catch {
+            // skip unreadable configs
+        }
+    }
+    // Try discovering child projects by scanning filesystem
+    try {
+        const wsConfig = loadConfig(wsRoot);
+        const summary = summarizeWorkspaceProjects(wsRoot, wsConfig);
+        for (const project of summary.discovered_projects) {
+            const projectPath = path.resolve(wsRoot, project.path);
+            if (project.project_name === ref) {
+                if (fs.existsSync(path.join(projectPath, MEMORY_DIR, 'config.yaml'))) {
+                    return projectPath;
+                }
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
 /**
  * Resolve the most specific child store that should answer a context request.
  *

package/docs/architecture/project-refs.md

@@ -257,10 +257,29 @@ Likely persisted fields:
 
 This should stay clearly separate from canonical memory items such as decisions and constraints.
 
+## Current Implementation (v0.23.0)
+
+`brainclaw switch` provides the first layer of project navigation:
+
+- `brainclaw switch <name-or-path>` — set active project by name or relative path
+- `brainclaw switch --list` — discover available projects in workspace
+- `resolveProjectRef()` — shared resolver for CLI and MCP (name, path, registry lookup)
+- `resolveEffectiveCwd()` — single source of truth: `--cwd` > `BRAINCLAW_PROJECT` env > active-project > cwd
+- MCP tools automatically resolve the active project
+
+This covers the most common agent friction (cwd-dependent resolution) without requiring the full `project_ref` model yet.
+
 ## Migration Strategy
 
 The migration should be low-risk and incremental.
 
+Phase 0 (done):
+
+- `brainclaw switch` with name/path resolution
+- global `--cwd` option
+- `BRAINCLAW_PROJECT` environment variable
+- `resolveEffectiveCwd()` used by CLI and MCP
+
 Phase 1:
 
 - introduce `project_ref` in workspace discovery/registry

package/docs/cli.md

@@ -11,6 +11,53 @@ For capable coding agents, prefer MCP for dynamic runtime state:
 
 Use the CLI when a human operator is driving the workflow, when you are scripting setup or release operations, or when MCP is not the integration path.
 
+## Global Options
+
+All commands support these global options:
+
+| Option | Description |
+|---|---|
+| `--cwd <path>` | Override working directory for this invocation. Bypasses active project and env var resolution. |
+| `--verbose` | Show info-level log messages on stderr |
+| `--debug` | Show debug-level log messages on stderr |
+
+**Effective cwd resolution priority** (highest wins):
+
+1. `--cwd` flag
+2. `BRAINCLAW_PROJECT` environment variable (project name or path)
+3. Active project set via `brainclaw switch`
+4. `process.cwd()` (shell working directory)
+
+---
+
+## Multi-Project Navigation
+
+### `brainclaw switch [project]`
+
+Set the active project for subsequent CLI and MCP commands. This eliminates the need to `cd` into a subproject directory in multi-project workspaces. The active project is persisted per-workspace in `.brainclaw/active-project.json`.
+
+| Option | Description |
+|---|---|
+| `--list` | List all available projects in the workspace |
+| `--clear` | Clear the active project (revert to cwd default) |
+| `--json` | Output as JSON |
+
+The `<project>` argument accepts:
+- **Project name** — matched against the global registry and workspace config
+- **Relative path** — resolved from the workspace root (e.g. `apps/lodestar`)
+- **Absolute path** — used directly
+
+```bash
+brainclaw switch --list              # discover available projects
+brainclaw switch lodestar            # switch by project name
+brainclaw switch apps/lodestar       # switch by relative path
+brainclaw switch                     # show current active project
+brainclaw switch --clear             # clear, revert to cwd
+brainclaw --cwd /other/path status   # one-off override without switching
+```
+
+**MCP usage:** The active project also affects MCP tools. When `bclaw_get_context()` is called without an explicit path, it resolves context from the active project's store. Agents can also use `BRAINCLAW_PROJECT=<name>` environment variable for the same effect.
+
 ---
 
 ## Initialize and Inspect

package/docs/concepts/workspace-bootstrapping.md

@@ -38,3 +38,44 @@ If shared memory is absent, that should not always be interpreted as "there is n
 It may simply mean the workspace has not been onboarded yet.
 
 This lets a single machine support multiple very different workspaces without forcing one static instruction layer to fit all of them equally well.
+
+## Multi-project workspaces
+
+A workspace may contain multiple brainclaw-initialized child projects (each with its own `.brainclaw/` store). In this topology:
+
+- The workspace root holds shared instructions, constraints, and coordination state
+- Each child project holds project-specific memory (decisions, traps, plans)
+- The store chain walks upward: child → repo → workspace → user
+
+### Working with child projects
+
+Agents and operators can address child projects without `cd`:
+
+```bash
+brainclaw switch apps/lodestar    # set active project
+brainclaw plan list               # now targets lodestar's store
+brainclaw switch --clear          # back to workspace root
+```
+
+Or use environment variables:
+
+```bash
+export BRAINCLAW_PROJECT=lodestar
+brainclaw context                 # resolves lodestar's store
+```
+
+Or one-off overrides:
+
+```bash
+brainclaw --cwd apps/lodestar plan list
+```
+
+### Project discovery
+
+`brainclaw switch --list` discovers child projects via:
+
+1. Global project registry
+2. Workspace config `projects.known`
+3. Filesystem scan for subdirectories containing `.brainclaw/`
+
+The bootstrap analysis (`analyzeRepository`) also detects brainclaw-native workspace complexity (child stores, folder strategy, known projects) alongside classic monorepo markers.

package/docs/integrations/agents.md

@@ -101,6 +101,41 @@ brainclaw adds all generated files to `.gitignore` automatically during init.
 
 Exception: use `--shared` if you intentionally want the main instruction file (e.g., CLAUDE.md) versioned for the whole team.
 
+## Multi-project workspaces
+
+When a workspace contains multiple brainclaw-initialized child projects, agents need to target the correct project store. There are three mechanisms (from most to least ergonomic):
+
+### 1. `brainclaw switch` (persistent)
+
+An operator or agent sets the active project once, and all subsequent commands resolve against it:
+
+```bash
+brainclaw switch apps/lodestar    # set active project
+brainclaw plan list               # targets lodestar
+bclaw_get_context()               # MCP also targets lodestar
+brainclaw switch --clear          # back to workspace root
+```
+
+### 2. `BRAINCLAW_PROJECT` environment variable
+
+Set in the shell or agent configuration. Useful for CI/CD or when the agent can control its environment:
+
+```bash
+export BRAINCLAW_PROJECT=lodestar
+```
+
+### 3. `--cwd` flag (one-off override)
+
+For a single command without changing the active project:
+
+```bash
+brainclaw --cwd apps/lodestar plan list
+```
+
+**Priority**: `--cwd` > `BRAINCLAW_PROJECT` > active project > shell cwd.
+
+**Discovery**: use `brainclaw switch --list` to see all available projects in the workspace.
+
 ## Session lifecycle
 
 ### Starting work

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.22.1",
+  "version": "0.23.1",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {