Local-first π§ memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly π΄ dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
v0.10.11 β multi-runtime install + Most-applied in digest: Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use
superpowers:subagent-driven-development(recommended) orsuperpowers:executing-plansto implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.Git policy for this project (operator-imposed): the executing agent MUST NOT run
git commit,git push, branch creation, or any other state-changing git command without an explicit per-action confirmation from the operator. Every "Commit" step below ends withPause: ask operator for permission to run the git command, paste the exact command, wait for an explicit yes. Do not auto-stage and do not piggyback unrelated changes.
Goal: Ship o2b install --target X [--apply|--check] for seven
new runtimes (Cursor, Aider, opencode, kiro, Copilot CLI, Gemini CLI,
Pi) plus a generic printout fallback; ship o2b init --interactive
wizard on top of that; surface Most-applied (Nd) in brain_digest
with _brain.yaml-driven window and limit; add per-runtime session-
transcript awareness to o2b discipline report for Claude Code,
Codex, and Cursor; restructure docs/install.md into a router plus
per-runtime files.
Architecture: One InstallAdapter interface lives at
src/core/install/types.ts. Each runtime is a single file under
src/core/install/adapters/. Shared helpers (json-merge.ts,
managed-block.ts, manifest.ts, payload.ts) live next to the
registry. The CLI layer (src/cli/install/*) is thin and composes
adapters. Theme 2 reuses the existing computeMostApplied β
signature gains optional windowDays and limit, and both
consumers (active.md and digest.ts) read the new
active.most_applied block from Brain/_brain.yaml.
Tech Stack: TypeScript (Bun-native), bun test, bun:sqlite
(only for Cursor session-transcript reader; already in the stack),
no new runtime dependencies. Tests live under tests/ mirroring
src/. Full suite: bun test. Typecheck: bun run typecheck.
Spec: docs/plans/2026-05-20-multi-runtime-install-design.md.
Read it before starting β every section number below (Β§3.1,
Β§7.2, ...) refers to that document.
Pre-flight
These run once before Task 1.
- Verify the working tree is clean.
cd /srv/projects/open-second-brain
git status
Expected: branch is master or a feature branch, no unstaged
changes, no untracked files in src/ or tests/. If dirty: stop
and ask the operator how to proceed.
- Verify baseline tests pass.
cd /srv/projects/open-second-brain
bun test
Expected: full suite green.
- Verify typecheck passes.
cd /srv/projects/open-second-brain
bun run typecheck
Expected: zero errors.
- Read the spec.
Read docs/plans/2026-05-20-multi-runtime-install-design.md end-to-end.
- Resolve open questions from Β§13 of the spec via WebFetch.
The spec leaves four questions to verify at impl time. Resolve before
Task 7 (Cursor) and before Task 12 (Aider). For each, record findings
in a scratch file under /tmp/install-impl-notes.md (gitignored) so
later tasks reference the same evidence.
1. Aider β does upstream support a native MCP client at impl time?
WebFetch: https://github.com/Aider-AI/aider/blob/main/CHANGELOG.md
WebFetch: https://aider.chat/docs/config/dotenv.html
2. opencode β exact MCP config file path.
WebFetch: https://github.com/sst/opencode#mcp
3. kiro β exact MCP config file path.
WebFetch: https://kiro.dev/docs/mcp (or the project's README)
4. Copilot CLI β exact `copilot mcp add` syntax + fallback file path.
WebFetch: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
5. Gemini CLI β settings.json layout.
WebFetch: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
6. Pi β skills directory convention.
WebFetch: https://pi.dev/docs (if available) or
https://mariozechner.at/posts/2025-11-30-pi-coding-agent/
If any WebFetch returns conflicting or stale information, stop and ask the operator. Do not guess.
Task 1: Shared install types
Objective: Land the InstallAdapter interface and supporting
types so subsequent tasks have a stable seam.
Files:
- Create:
src/core/install/types.ts - Create:
tests/core/install/types.test.ts
Step 1: Write failing test.
// tests/core/install/types.test.ts
import { describe, expect, test } from "bun:test";
import {
ADAPTER_STATUSES,
INSTALL_STEP_KINDS,
VERIFY_STATUSES,
} from "../../../src/core/install/types.ts";
describe("install types", () => {
test("ADAPTER_STATUSES covers the four documented states", () => {
expect(ADAPTER_STATUSES).toEqual(
new Set([
"not-installed",
"installed",
"drift",
"unsupported-on-this-platform",
]),
);
});
test("INSTALL_STEP_KINDS covers the five operation kinds", () => {
expect(INSTALL_STEP_KINDS).toEqual(
new Set([
"json-merge",
"managed-block",
"subprocess",
"file-copy",
"symlink",
"print",
]),
);
});
test("VERIFY_STATUSES covers the four documented states", () => {
expect(VERIFY_STATUSES).toEqual(
new Set(["ok", "drift", "not-installed", "mcp-unreachable"]),
);
});
});
Step 2: Run test to verify failure.
bun test tests/core/install/types.test.ts
Expected: FAIL β module not found.
Step 3: Write minimal implementation.
Create src/core/install/types.ts with the interfaces listed in
Β§2.2 of the spec, plus the runtime-checkable sets above. Pure
type-only file (no I/O, no side effects, no runtime deps).
Key exports:
export const ADAPTER_STATUSES = new Set([
"not-installed", "installed", "drift", "unsupported-on-this-platform",
] as const);
export const INSTALL_STEP_KINDS = new Set([
"json-merge", "managed-block", "subprocess", "file-copy", "symlink", "print",
] as const);
export const VERIFY_STATUSES = new Set([
"ok", "drift", "not-installed", "mcp-unreachable",
] as const);
export type AdapterStatus = ...; // union over ADAPTER_STATUSES
export type InstallStepKind = ...;
export type VerifyStatus = ...;
export interface InstallEnv { ... }
export interface DetectResult { ... }
export interface InstallStep { ... }
export interface InstallPlan { ... }
export interface ApplyOpts { ... }
export interface ManifestEntry { ... }
export interface ApplyResult { ... }
export interface UninstallResult { ... }
export interface VerifyResult { ... }
export interface SessionPathsResult { ... }
export interface InstallAdapter { ... }
export interface McpPayload { ... } // shape of the canonical MCP server entry
Full field list per the spec Β§2.2.
Step 4: Run test to verify pass.
bun test tests/core/install/types.test.ts
bun run typecheck
Expected: PASS, zero typecheck errors.
Step 5: Commit.
Stage and prepare:
git status
git diff --stat src/core/install/types.ts tests/core/install/types.test.ts
git add src/core/install/types.ts tests/core/install/types.test.ts
Pause: ask operator for permission to run the git command, paste the exact command, wait for an explicit yes:
git commit -m "feat(install): InstallAdapter interface and supporting types"
Task 2: manifest.ts sidecar I/O helper
Objective: Land the read/write helper for
<vault>/.open-second-brain/install.lock.json per Β§2.4 of the spec.
Files:
- Create:
src/core/install/manifest.ts - Create:
tests/core/install/manifest.test.ts
Step 1: Write failing tests.
// tests/core/install/manifest.test.ts
import { describe, expect, test, beforeEach } from "bun:test";
import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
readManifest,
recordEntry,
removeEntry,
manifestPath,
type ManifestEntry,
} from "../../../src/core/install/manifest.ts";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "osb-manifest-"));
});
describe("install manifest", () => {
test("readManifest returns empty shell when file is missing", () => {
const m = readManifest(vault);
expect(m.schema_version).toBe(1);
expect(m.installs).toEqual({});
});
test("recordEntry creates sidecar dir + file atomically", () => {
const entry: ManifestEntry = {
target: "cursor",
applied_at: "2026-05-20T12:00:00.000Z",
operation: "json-merge",
config_path: "/home/u/.cursor/mcp.json",
owned_keys: ["mcpServers.open-second-brain"],
};
recordEntry(vault, entry);
const m = readManifest(vault);
expect(m.installs.cursor).toEqual(entry);
const raw = readFileSync(manifestPath(vault), "utf8");
expect(raw.endsWith("\n")).toBe(true);
});
test("recordEntry overwrites existing entry for the same target", () => {
recordEntry(vault, {
target: "cursor", applied_at: "2026-05-20T12:00:00.000Z",
operation: "json-merge", config_path: "/a",
owned_keys: ["mcpServers.open-second-brain"],
});
recordEntry(vault, {
target: "cursor", applied_at: "2026-05-20T12:05:00.000Z",
operation: "json-merge", config_path: "/b",
owned_keys: ["mcpServers.open-second-brain"],
});
const m = readManifest(vault);
expect(m.installs.cursor!.applied_at).toBe("2026-05-20T12:05:00.000Z");
expect(m.installs.cursor!.config_path).toBe("/b");
});
test("removeEntry deletes the named target only", () => {
recordEntry(vault, {
target: "cursor", applied_at: "...Z",
operation: "json-merge", config_path: "/a",
owned_keys: ["mcpServers.open-second-brain"],
});
recordEntry(vault, {
target: "pi", applied_at: "...Z",
operation: "symlink", config_path: null,
owned_paths: ["/p"],
});
removeEntry(vault, "cursor");
const m = readManifest(vault);
expect(m.installs.cursor).toBeUndefined();
expect(m.installs.pi).toBeDefined();
});
test("removeEntry on missing target is a no-op", () => {
removeEntry(vault, "cursor");
expect(readManifest(vault).installs).toEqual({});
});
test("readManifest tolerates forward-compat unknown top-level keys", () => {
mkdirSync(join(vault, ".open-second-brain"), { recursive: true });
writeFileSync(
manifestPath(vault),
JSON.stringify({ schema_version: 1, installs: {}, future_thing: 42 }),
);
const m = readManifest(vault);
expect(m.schema_version).toBe(1);
});
test("readManifest rejects unknown schema_version", () => {
mkdirSync(join(vault, ".open-second-brain"), { recursive: true });
writeFileSync(
manifestPath(vault),
JSON.stringify({ schema_version: 999, installs: {} }),
);
expect(() => readManifest(vault)).toThrow(/schema_version/);
});
afterEach(() => {
try { rmSync(vault, { recursive: true, force: true }); } catch {}
});
});
Step 2: Run test to verify failure.
bun test tests/core/install/manifest.test.ts
Expected: FAIL β module not found.
Step 3: Write minimal implementation.
src/core/install/manifest.ts exports manifestPath(vault),
readManifest(vault), recordEntry(vault, entry),
removeEntry(vault, target). Use the existing
atomicWriteFileSync from src/core/fs-atomic.ts for writes.
JSON output: 2-space indent, trailing newline.
Reject unknown schema_version. Tolerate unknown top-level keys
(forward-compat per spec Β§2.4). Missing file = empty shell.
Step 4: Run test to verify pass.
bun test tests/core/install/manifest.test.ts
bun run typecheck
Expected: all 7 tests PASS, zero typecheck errors.
Step 5: Commit.
git add src/core/install/manifest.ts tests/core/install/manifest.test.ts
Pause for operator yes, then:
git commit -m "feat(install): sidecar manifest read/write"
Task 3: json-merge.ts helper
Objective: Safe merge of OSB's two mcpServers keys into an
existing JSON file, preserving user-authored content and
indentation.
Files:
- Create:
src/core/install/json-merge.ts - Create:
tests/core/install/json-merge.test.ts - Create fixtures:
tests/fixtures/install/json-merge/{empty,user-keys-present,osb-already,bom}.{before,after}.json
Step 1: Write failing tests.
Cover six cases:
- Empty file (or missing) β write a new file with both OSB keys
under
mcpServers, 2-space indent, trailing newline. - User has unrelated
mcpServerskeys (e.g.mcpServers.other) β keep them, add two OSB keys, preserve key order (user keys before OSB keys, OSB keys in insertion order). - User has older OSB keys with different command/args β overwrite both with canonical payload, byte-equal to expected output.
- File has 4-space indent β preserve 4-space indent on write.
- File has BOM at start β preserve BOM.
- File is invalid JSON β throw
JsonMergeErrorwith file path and parse error.
// tests/core/install/json-merge.test.ts
// see full code under tests/ folder; here is the test of case 2:
test("preserves unrelated mcpServers keys", () => {
const before = `{
"mcpServers": {
"other": { "command": "x", "args": [] }
}
}\n`;
const after = mergeMcpServers(before, OSB_PAYLOAD);
const parsed = JSON.parse(after);
expect(Object.keys(parsed.mcpServers)).toEqual([
"other",
"open-second-brain",
"open-second-brain-writer",
]);
expect(parsed.mcpServers.other).toEqual({ command: "x", args: [] });
});
(Detail similar for the other 5 cases; refer to fixtures.)
Step 2: Run test to verify failure.
bun test tests/core/install/json-merge.test.ts
Expected: FAIL β module not found.
Step 3: Write minimal implementation.
src/core/install/json-merge.ts exports:
mergeMcpServers(currentJson: string, payload: { full: McpServerEntry; writer: McpServerEntry }): stringremoveMcpServers(currentJson: string): stringβ removes both OSB keys; emptymcpServersobject kept (we don't dictate user's parent shape).JsonMergeError extends Errorβ carries path.
Implementation hints:
- Detect indentation by scanning the first indented line; default to 2 spaces if file has no nesting.
- Detect BOM by inspecting first three bytes (
ο»Ώ); preserve verbatim. - Use
JSON.parsefor read; manual stringify withJSON.stringify(..., null, indent)for write. - Don't sort keys; preserve insertion order. JS objects retain insertion order for non-integer keys, so build the merged
mcpServersby iterating original keys (skipping OSB names if present) then appending OSB names.
Step 4: Run test to verify pass.
bun test tests/core/install/json-merge.test.ts
bun run typecheck
Expected: all 6 tests PASS.
Step 5: Commit.
git add src/core/install/json-merge.ts tests/core/install/json-merge.test.ts tests/fixtures/install/json-merge/
Pause for operator, then:
git commit -m "feat(install): JSON-merge helper for mcpServers"
Task 4: managed-block.ts helper
Objective: Insert / replace / remove a marker-fenced block in a text file (used by Aider adapter and the future text-fallback adapter).
Files:
- Create:
src/core/install/managed-block.ts - Create:
tests/core/install/managed-block.test.ts - Create fixtures:
tests/fixtures/install/managed-block/{insert,replace,remove}.{before,after}.txt
Step 1: Write failing tests.
Cover:
- Insert into file that has no marker block β append at end with a leading blank line; preserve all preceding content byte-for-byte.
- Replace existing block β content between markers fully replaced; surrounding lines unchanged.
- Remove block β both markers and everything between them removed; preceding and trailing blank lines normalised to one.
- Nested markers β reject with
ManagedBlockError. - Single marker without closing β reject with
ManagedBlockError. - CRLF input β preserve CRLF on write (don't normalise to LF).
- Custom marker text β markers are parametrised; default uses the
# >>> open-second-brain managed >>>/<<<pair fromprotect.ts.
Step 2-4: Standard TDD cycle.
Implementation hints:
- Markers are parametrised so the adapter chooses (Aider uses YAML comment markers; generic-text-fallback uses the same).
- Use a precompiled RegExp with
^...$andmflag to find the pair; reject if more than one of either marker appears. - Detect line ending (CRLF vs LF) by scanning first 1KB; preserve.
Step 5: Commit.
git add src/core/install/managed-block.ts tests/core/install/managed-block.test.ts tests/fixtures/install/managed-block/
Pause, then:
git commit -m "feat(install): managed-block editor for text/YAML configs"
Task 5: payload.ts builder
Objective: Build the canonical MCP server entries from the plugin config β same input, deterministic output, used by every adapter that emits MCP config.
Files:
- Create:
src/core/install/payload.ts - Create:
tests/core/install/payload.test.ts
Step 1: Write failing tests.
test("buildPayload returns full + writer entries with vault + env vars", () => {
const cfg = {
vault: "/home/u/vault",
agent_name: "claude-vps-agent",
timezone: "Europe/Belgrade",
};
const { full, writer } = buildPayload(cfg);
expect(full.command).toBe("o2b");
expect(full.args).toEqual(["mcp", "--vault", "/home/u/vault"]);
expect(full.env).toEqual({
VAULT_AGENT_NAME: "claude-vps-agent",
VAULT_TIMEZONE: "Europe/Belgrade",
});
expect(writer.args).toEqual(["mcp", "--writer-only", "--vault", "/home/u/vault"]);
});
test("buildPayload omits env when agent_name / timezone missing", () => {
const cfg = { vault: "/v", agent_name: null, timezone: null };
const { full } = buildPayload(cfg);
expect(full.env).toBeUndefined();
});
test("buildPayload throws on missing vault", () => {
expect(() => buildPayload({ vault: null } as any)).toThrow(/vault/);
});
Step 2-4: TDD cycle.
Pure function; reads no I/O; takes the loaded plugin config as
argument. Adapters that need it call discoverConfig themselves
upstream.
Step 5: Commit.
git add src/core/install/payload.ts tests/core/install/payload.test.ts
Pause:
git commit -m "feat(install): canonical MCP payload builder"
Task 6: Adapter registry
Objective: A Map<target, InstallAdapter> + detectAll(env)
helper. Empty in this commit (adapters land in later tasks).
Files:
- Create:
src/core/install/registry.ts - Create:
tests/core/install/registry.test.ts
Step 1: Write failing tests.
test("registry is empty initially", () => {
const reg = createRegistry();
expect(reg.list()).toEqual([]);
expect(reg.get("cursor")).toBeUndefined();
});
test("register + get round-trip", () => {
const reg = createRegistry();
const fake: InstallAdapter = makeFakeAdapter("test");
reg.register(fake);
expect(reg.get("test")).toBe(fake);
expect(reg.list().map((a) => a.target)).toEqual(["test"]);
});
test("register rejects duplicate target", () => {
const reg = createRegistry();
reg.register(makeFakeAdapter("cursor"));
expect(() => reg.register(makeFakeAdapter("cursor"))).toThrow(/duplicate/);
});
test("detectAll returns one entry per registered adapter", () => {
const reg = createRegistry();
reg.register(makeFakeAdapter("a"));
reg.register(makeFakeAdapter("b"));
const env = makeEnv({});
expect(reg.detectAll(env).map((d) => d.target)).toEqual(["a", "b"]);
});
Step 2-4: TDD cycle.
Provide a createRegistry() factory plus a module-level default
registry (defaultRegistry) that adapter files mutate via
defaultRegistry.register(...) at import time. Test-friendly:
createRegistry() returns a fresh isolated instance.
Step 5: Commit.
git add src/core/install/registry.ts tests/core/install/registry.test.ts
Pause:
git commit -m "feat(install): adapter registry"
Task 7: cursor adapter
Objective: First real adapter β canonical JSON-merge case.
Files:
- Create:
src/core/install/adapters/cursor.ts - Create:
tests/core/install/adapters/cursor.test.ts - Create fixtures:
tests/fixtures/install/cursor/{clean,user-keys,osb-old,drift}.before.jsonand matching.after.json
Step 1: Write failing tests.
Cover the six scenarios listed in spec Β§10.2:
- Clean install on empty config β
applywrites file;verifyreturnsok. - Re-apply β second
applyis a byte-no-op; manifestapplied_atis updated only if content changed. - Drift detection β manually mutate the file post-install;
verifyreturnsdriftwith the missing/extra keys. - Uninstall β
uninstallremoves both keys; manifest entry gone; surrounding keys preserved. - Uninstall without manifest entry β fails with code path message;
--force-from-snippetsucceeds when payload matches. - User-modified block β file mtime newer than
applied_at, content differs from canonical;applywithout--forcethrows exit-4 (the adapter signals via thrown error; the CLI layer converts).
test("apply on empty config installs both keys", () => {
const env = makeEnv({ home: TMP_HOME, configPath: join(TMP_HOME, ".cursor/mcp.json") });
const adapter = cursorAdapter;
const payload = buildPayload(loadFakeConfig());
const plan = adapter.plan(payload, env);
const result = adapter.apply(plan, env, { dryRun: false, stdout: ..., stderr: ... });
const raw = JSON.parse(readFileSync(env.configPath, "utf8"));
expect(Object.keys(raw.mcpServers)).toEqual([
"open-second-brain",
"open-second-brain-writer",
]);
expect(result.manifest.owned_keys).toEqual([
"mcpServers.open-second-brain",
"mcpServers.open-second-brain-writer",
]);
});
Step 2: Run test to verify failure.
bun test tests/core/install/adapters/cursor.test.ts
Expected: FAIL β module not found.
Step 3: Write minimal implementation.
src/core/install/adapters/cursor.ts:
detect(env): check${XDG_CONFIG_HOME:-$HOME}/.cursor/mcp.json; reportinstalledif both OSB keys present and match,driftif file exists with partial or mismatched OSB keys,not-installedotherwise.plan(payload, env): emit onejson-mergestep with preview (deterministic diff text).apply(plan, env, opts): build current canonical payload frompayload.ts, callmergeMcpServersfromjson-merge.ts, write atomically. Record manifest. HonordryRun.uninstall(env, opts): read manifest, callremoveMcpServers, remove manifest entry. If manifest absent and not--force-from-snippet, throwManifestMissingError.verify(env): parse file, compare current key values to canonical payload. If file mtime is newer thanapplied_atand content differs from canonical βdrift.
Auto-register: defaultRegistry.register(cursorAdapter) at the
bottom of the file. The default registry is imported by every CLI
verb.
Step 4: Run test to verify pass.
bun test tests/core/install/adapters/cursor.test.ts
bun run typecheck
Expected: all six scenarios PASS.
Step 5: Commit.
git add src/core/install/adapters/cursor.ts tests/core/install/adapters/cursor.test.ts tests/fixtures/install/cursor/
Pause:
git commit -m "feat(install): cursor adapter"
Task 8: opencode adapter
Objective: Same JSON-merge pattern as Cursor; different config path.
Files:
- Create:
src/core/install/adapters/opencode.ts - Create:
tests/core/install/adapters/opencode.test.ts - Fixtures:
tests/fixtures/install/opencode/
Pattern: Replicate Task 7 structure. The body of the adapter
shares 90% of the code with Cursor β extract the common JSON-merge
adapter body to adapters/_json-mcp.ts if and only if the third
JSON-merge adapter (Task 9 or Task 10) doesn't introduce a third
shape difference. Otherwise keep them as three independent files
to avoid premature abstraction.
Detect path: ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/mcp.json
(confirm via WebFetch resolved in Pre-flight).
TDD cycle + fixtures + commit. Brief commit message:
feat(install): opencode adapter.
Task 9: kiro adapter
Same shape as Cursor / opencode. Config path ~/.kiro/settings.json
(confirm via WebFetch). If kiro stores MCP entries under a
different top-level key than mcpServers, override the key in
json-merge call.
After this task, decide whether to extract the shared JSON-merge
adapter body into adapters/_json-mcp.ts. If yes, do it as a
no-op refactor (existing tests must still pass) and commit
separately:
git commit -m "refactor(install): extract shared JSON-merge adapter body"
Task 10: gemini-cli adapter
Same shape as Cursor. Config path ~/.gemini/settings.json under
key mcpServers (per
github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).
Verify hint: gemini --version exit 0 is the cheap liveness
check; o2b mcp --probe is the MCP-side check.
TDD cycle + fixtures + commit. Message:
feat(install): gemini-cli adapter.
Task 11: copilot-cli adapter (subprocess + fallback)
Objective: First adapter that calls a subprocess. Adds the
subprocess operation kind in practice.
Files:
- Create:
src/core/install/adapters/copilot-cli.ts - Create:
tests/core/install/adapters/copilot-cli.test.ts - Mocked subprocess fixtures.
Step 1: Write failing tests.
Test cases:
- Happy path β
copilotCLI on PATH;applycallscopilot mcp remove open-second-brainthencopilot mcp add ...(twice, once per name). - CLI missing β
applyfalls back to JSON-merge at the documented fallback file path; stderr emits "copilot CLI not found; using file fallback". - CLI returns non-zero on
addβapplyfalls back to file mode, stderr describes the CLI error. - Uninstall via subprocess β calls
copilot mcp removeonce per name. - Uninstall via file fallback β same path as Cursor uninstall.
- Verify via
copilot mcp listparsing β both names present βok.
Subprocess mocking: use Bun.spawn injection point. The adapter
takes an injectable spawn function in its options (defaults to
Bun.spawn); tests pass a fake.
Step 2-4: TDD cycle.
Adapter records operation: "subprocess" plus optional
fallback_file field in manifest when fallback path was used.
Step 5: Commit.
git commit -m "feat(install): copilot-cli adapter with subprocess + file fallback"
Task 12: aider adapter
Objective: Managed-block in ~/.aider.conf.yml + sidecar
context file.
Files:
- Create:
src/core/install/adapters/aider.ts - Create:
templates/install/aider-context.md.tmpl - Create:
tests/core/install/adapters/aider.test.ts - Fixtures.
Pre-task check. Re-read Pre-flight finding #1. If upstream Aider
shipped native MCP at impl time, switch to JSON-merge against
Aider's MCP config and document the change in a one-line comment
at top of aider.ts. The rest of this task assumes no native MCP.
Step 1: Write failing tests.
Cases:
- Clean install β creates
~/.aider.conf.ymlif missing; adds managed block underread:; generates<vault>/.open-second-brain/aider-context.mdfrom template. - Pre-existing
~/.aider.conf.ymlwith user's ownread:list β preserves user's list; appends managed block as additional list entries between markers. - Re-apply β byte no-op when canonical payload hasn't changed.
- Uninstall β removes managed block AND sidecar context file (path from manifest).
- Template render β the sidecar context file contains a brief
summary of
skills/brain-memory/SKILL.mdplus the currentBrain/active.mdbody. Regeneration on each apply. - Verify β managed block present + sidecar file exists + non-empty.
Step 2-4: TDD cycle.
Template uses simple {{var}} substitution (no jinja). Template
content drafted as part of this task.
Step 5: Commit.
git commit -m "feat(install): aider adapter (managed-block + sidecar context)"
Task 13: pi adapter
Objective: Symlink-only adapter; no JSON, no managed block.
Files:
- Create:
src/core/install/adapters/pi.ts - Create:
tests/core/install/adapters/pi.test.ts
Cases:
- Clean install β creates
~/.pi/skills/brain-memorysymlink pointing at<repo>/skills/brain-memory. --pi-skill-dir <path>override β symlink at custom location.- Re-apply on existing valid symlink β no-op.
- Re-apply on existing broken symlink (target gone) β replaces.
- Re-apply on existing non-symlink at target path β refuses
without
--force(don't clobber a user-authored directory). - Uninstall β removes symlink only, never the source.
- Verify β symlink valid + target readable.
Step 5: Commit.
git commit -m "feat(install): pi adapter (symlink-based)"
Task 14: generic adapter
Objective: Print-only fallback; never edits any runtime config.
Files:
- Create:
src/core/install/adapters/generic.ts - Create:
tests/core/install/adapters/generic.test.ts
Cases:
- Default β prints canonical JSON payload to stdout.
--format yamlβ YAML rendering.--out <path>β writes to file; manifest records path.--out -β explicit stdout.detectβ always returnsnot-installed.uninstallβ prints the path that the operator must remove manually; no file deletion.
Step 5: Commit.
git commit -m "feat(install): generic adapter (print-only fallback)"
Task 15: o2b mcp --writer-only flag
Objective: The Payload builder emits args
["mcp", "--writer-only", ...]. Land the matching flag in
o2b mcp.
Files:
- Modify:
src/mcp/main.ts(or wherevero2b mcpargv parsing lives β search formcpMainorcmdMcp). - Modify:
src/mcp/tools.ts:buildToolTableto accept awriterOnly: booleanoption. - Test:
tests/mcp/writer-only.test.ts.
Step 1: Test.
test("writer-only tool table contains only the three writer tools + brain_context", () => {
const table = buildToolTable({ writerOnly: true, ... });
const names = table.tools.map((t) => t.name);
expect(names.sort()).toEqual([
"brain_apply_evidence",
"brain_context",
"brain_feedback",
"brain_note",
]);
});
test("full tool table contains everything", () => {
const table = buildToolTable({ writerOnly: false, ... });
expect(table.tools.length).toBeGreaterThan(15);
});
Step 2-4: TDD cycle.
Add --writer-only to argv parsing. When set, pass to
buildToolTable. The writer-server in .mcp.json already
filters this way via a different mechanism (per v0.10.7); reuse
the filter logic if it lives in a helper, else extract.
Step 5: Commit.
git commit -m "feat(mcp): --writer-only flag for o2b mcp"
Task 16: o2b mcp --probe flag
Objective: Used by o2b install --check to validate that the
MCP server starts and responds to initialize.
Files:
- Modify:
src/mcp/main.ts - Create:
src/mcp/probe.ts - Test:
tests/mcp/probe.test.ts
Behavior: o2b mcp --probe:
- Sets up an in-process pipe instead of stdio.
- Sends an MCP
initializerequest. - Reads the response; checks
toolsarray is non-empty. - Writes one line to stdout:
mcp probe ok (N tools)ormcp probe FAIL: <reason>. - Exits 0 on success, non-zero on failure.
Cases:
- Happy path β returns 0, prints tool count.
- Probe with vault flag missing in plugin config β exits non-zero with "vault not configured".
- Probe with vault path invalid (does not exist) β exits non-zero with reason.
Step 5: Commit.
git commit -m "feat(mcp): --probe flag for in-process MCP handshake"
Task 17: o2b install CLI verb
Objective: Main entry-point. Glues registry + adapters.
Files:
- Create:
src/cli/install/install.ts - Create:
src/cli/install/render.ts - Modify:
src/cli/main.tsto routeo2b install. - Test:
tests/cli/install/install.test.ts.
Step 1: Tests (organised by subcommand path).
describe("o2b install", () => {
test("no args β detect-only table (text)", async () => {
const out = await runCli(["install"], env);
expect(out.stdout).toContain("detected runtimes");
expect(out.exitCode).toBe(0);
// No file writes
expect(existsSync(env.cursorConfig)).toBe(false);
});
test("--json β machine output", async () => {
const out = await runCli(["install", "--json"], env);
const parsed = JSON.parse(out.stdout);
expect(parsed.targets).toBeInstanceOf(Array);
});
test("--target cursor (no --apply) β plan-only", async () => {
const out = await runCli(["install", "--target", "cursor"], env);
expect(out.stdout).toContain("json-merge");
expect(existsSync(env.cursorConfig)).toBe(false);
});
test("--target cursor --apply β writes file", async () => {
const out = await runCli(["install", "--target", "cursor", "--apply"], env);
expect(out.exitCode).toBe(0);
expect(existsSync(env.cursorConfig)).toBe(true);
});
test("--target unknown β exit 2", async () => {
const out = await runCli(["install", "--target", "nope"], env);
expect(out.exitCode).toBe(2);
});
test("--target generic --out - β stdout", async () => {
const out = await runCli(
["install", "--target", "generic", "--out", "-"], env,
);
expect(JSON.parse(out.stdout).command).toBe("o2b");
});
test("apply on user-modified block exits 4", async () => {
// setup: install once, then hand-edit, advance mtime
await runCli(["install", "--target", "cursor", "--apply"], env);
writeFileSync(env.cursorConfig, '{ "mcpServers": { "open-second-brain": { "command": "TAMPERED" } } }');
advanceFileMtime(env.cursorConfig, 60); // make mtime newer than manifest applied_at
const out = await runCli(["install", "--target", "cursor", "--apply"], env);
expect(out.exitCode).toBe(4);
expect(out.stderr).toContain("hand-edited");
});
});
Step 2-4: TDD cycle.
The verb resolves defaultRegistry, parses argv, dispatches:
- no
--targetβregistry.detectAll(env)βrenderDetectTable(...)or JSON. --target Xwithout--applyβadapter.plan(...)βrenderPlan(...).--target X --applyβadapter.detect(...)+adapter.plan(...)+adapter.apply(...).--target genericwith--out/--formatβ passthrough.
Use existing parseArgs helper from src/cli/argparse.ts.
Step 5: Commit.
git commit -m "feat(cli): o2b install verb (detect + plan + apply)"
Task 18: o2b uninstall --target X CLI verb
Objective: Sibling of install β reads manifest, calls
adapter.uninstall.
Files:
- Modify:
src/cli/uninstall.ts(existing β extend with--targetmode; current--apply-localmode stays). - Test:
tests/cli/uninstall-target.test.ts.
Cases:
- Dry-run (
--target X, no--apply) β prints what would be removed; no file changes. --applyβ removes per manifest; manifest entry deleted.- Manifest missing β exits non-zero with hint;
--force-from-snippetpath documented in the error message. --target Xwith no manifest entry β exit 0 with "nothing recorded".
Step 5: Commit.
git commit -m "feat(cli): o2b uninstall --target X"
Task 19: o2b install --check CLI verb
Objective: Runtime install health check.
Files:
- Modify:
src/cli/install/install.ts - Test:
tests/cli/install/check.test.ts.
Cases:
- All-ok β exit 0; table shows each target with status.
- One drift β exit 3; drift row carries
fixhint pointing at the exact apply command. - Not-installed everywhere β exit 0 (
not-installedis not an error). - MCP probe failure on Cursor (probe spawn returns non-zero) β
row status
mcp-unreachablewith restart hint. --jsonβ mirror of text output, exit code identical.
Step 5: Commit.
git commit -m "feat(cli): o2b install --check"
Task 20: o2b init --interactive wizard
Objective: First-time setup wizard that composes
o2b init + optional o2b brain init + per-target install.
Files:
- Create:
src/cli/install/init-interactive.ts - Modify:
src/cli/main.tsto routeo2b init --interactive. - Test:
tests/cli/init-interactive.test.ts.
Step 1: Test.
The wizard takes an injectable prompt(question, options)
function. Tests pass a fake that returns scripted answers; the
wizard's output is asserted exactly.
test("wizard happy path: clean vault, two targets selected", async () => {
const answers = [
"1", // vault: first candidate
"claude-vps", // agent name
"Europe/Belgrade",
"ru",
"1,3", // pick targets 1 and 3 from list
"y", // brain init?
"n", // starter?
"yes", // confirm summary
];
const result = await runWizard(makeFakePrompt(answers), env);
expect(result.exitCode).toBe(0);
expect(result.actions).toContain("o2b init --vault ...");
expect(result.actions).toContain("o2b install --target cursor --apply");
});
test("wizard aborts at summary on 'no'", async () => {
const answers = [..., "no"];
const result = await runWizard(makeFakePrompt(answers), env);
expect(result.exitCode).toBe(0);
expect(result.actions).toEqual([]); // nothing executed
});
Step 2-4: TDD cycle.
Implement nine steps per spec Β§5. Each step is a small private function; the top-level wizard glues them together with the injected prompt.
Step 5: Commit.
git commit -m "feat(cli): o2b init --interactive wizard"
Task 21: Theme 2 β active.most_applied config block
Objective: Land the new block in _brain.yaml schema + loader
- validator.
Files:
- Modify:
src/core/brain/types.ts(addBrainActiveConfig,BrainMostAppliedConfiginterfaces; addactive?:field toBrainConfig). - Modify:
src/core/brain/policy.ts(loader pulls the block; validator rejects out-of-range values). - Test:
tests/core/brain/policy-active.test.ts.
Cases:
_brain.yamlwithoutactiveblock β loader returnscfg.active === undefined; consumers use defaults._brain.yamlwithactive.most_applied: { window_days: 7, limit: 3 }β loaded values.window_days: 0βBrainConfigError("active.most_applied.window_days must be between 1 and 365, got 0").window_days: "thirty"βBrainConfigError.limit: -1βBrainConfigError.limit: 100βBrainConfigError("between 1 and 50").
Step 5: Commit.
git commit -m "feat(brain): _brain.yaml active.most_applied config block"
Task 22: Theme 2 β extend computeMostApplied
Objective: Make windowDays and limit parameters; keep
defaults for back-compat.
Files:
- Modify:
src/core/brain/most-applied.ts - Modify:
tests/core/brain/most-applied.test.ts(add cases for custom values; existing cases must still pass).
Cases (new ones to add to the existing test file):
windowDays: 7β events older than 7 days excluded.windowDays: 7, limit: 2β top 2 within 7-day window.windowDays: 365β events from up to one year ago count.- Day-level fence preserved regardless of
windowDays.
Step 5: Commit.
git commit -m "feat(brain): computeMostApplied windowDays + limit params"
Task 23: Theme 2 β active.md uses configured window
Objective: regenerateActive reads
cfg.active?.most_applied?.{window_days, limit} and passes them
through.
Files:
- Modify:
src/core/brain/active.ts - Modify:
tests/core/brain/active.test.ts(one new case).
Case:
_brain.yaml has active.most_applied.window_days: 7 β
active.md header reads ## Most-applied (7d) and only counts
events within the last 7 days.
Golden test note: existing golden fixtures used default 30/10; verify they still pass byte-for-byte.
Step 5: Commit.
git commit -m "feat(brain): active.md honours active.most_applied config"
Task 24: Theme 2 β digest most_applied JSON field
Objective: Add most_applied to DigestJson and the data
collector.
Files:
- Modify:
src/core/brain/digest.ts - Modify:
tests/core/brain/digest.test.ts.
Cases:
- Default config β
digest.most_applied.window_days === 30,limit === 10,entries: [...]. - Custom config β values reflected in JSON.
- Empty window β
entries: [], block present.
Step 5: Commit.
git commit -m "feat(brain): digest JSON most_applied block"
Task 25: Theme 2 β digest most_applied Markdown section
Objective: Render ## Most-applied (Nd) between existing
sections.
Files:
- Modify:
src/core/brain/digest.ts:renderMarkdown - Modify golden Markdown fixtures: add new section for windows with entries; absent for empty-window cases.
Cases:
- Default config + non-empty window β section rendered.
- Empty window β section omitted entirely.
- Custom window (
14d) β header text reflects it.
Step 5: Commit.
git commit -m "feat(brain): digest Markdown Most-applied section"
Task 26: Companion 2 β sessionPaths for claudecode/codex/cursor
Objective: Land the three transcript-path resolvers.
Files:
- Modify: existing claudecode adapter (created in earlier task or
located via
find src/core/install/adapters/ -name '*claude*') β addsessionPaths. If no Claude Code adapter exists yet, the resolver lives standalone atsrc/core/install/session-paths-claudecode.ts. - Create:
src/core/install/session-paths-codex.ts - Create:
src/core/install/session-paths-cursor.ts - Tests:
tests/core/install/session-paths-{claudecode,codex,cursor}.test.ts
Cases per resolver:
- Standard path resolves on Linux fixtures.
- macOS layout resolves (Cursor).
- Missing files β returns
{ paths: [] }, not an error.
Step 5: Commit.
git commit -m "feat(install): sessionPaths for claudecode/codex/cursor"
Task 27: Companion 2 β o2b discipline report transcript adapter
Objective: Plug session-path resolvers into the report; surface
transcript-confirmed sub-reason in alert rows.
Files:
- Modify:
scripts/discipline-report.ts(the actual implementation behindbin/o2b-discipline-report). - Test:
tests/scripts/discipline-report-transcripts.test.ts.
Cases:
- Claude Code transcript shows activity + zero brain events for
the same agent that day β alert with
transcript-confirmed. - Transcript empty + git/mtime activity β existing proxy result
(no
transcript-confirmedflag). - Multiple runtimes simultaneously β each evaluated independently.
Step 5: Commit.
git commit -m "feat(discipline): per-runtime transcript-confirmed signal"
Task 28: Docs β install/ folder restructure
Objective: Split install.md into router + per-runtime files.
Files:
- Modify:
install.md(root) β reduce to router; preserve a pointer at the top to the per-runtime files. - Create:
install/prerequisites.md - Create:
install/cursor.md,install/aider.md,install/opencode.md,install/kiro.md,install/copilot-cli.md,install/gemini-cli.md,install/pi.md,install/generic.md - Create (migrate content from existing branches):
install/claudecode.md,install/codex.md,install/hermes.md,install/openclaw.md.
Pattern per file:
- One-paragraph intro.
- Command block:
o2b install --target X --apply(or other per-runtime command). - Verify section:
o2b install --check --target X. - Caveats (one or two paragraphs at most).
- Uninstall command.
Step 5: Commit.
git commit -m "docs(install): split install.md into router + per-runtime files"
Task 29: Docs β README quick install
Objective: Surface the one-liner up front.
Files:
- Modify:
README.mdβ add a "Quick install" section above existing content.
Step 5: Commit.
git commit -m "docs: README quick-install section"
Task 30: CHANGELOG + version bump
Objective: Land the v0.10.11 entry and bump
package.json / pyproject.toml.
Files:
- Modify:
CHANGELOG.md - Modify:
package.json(versionfield) - Modify:
pyproject.toml(if it carries a version field) - Modify: any other version-bearing file (search:
grep -rn "0\\.10\\.10" --include='*.{json,toml,md,ts}' .)
Per project convention: one PR β one CHANGELOG version. No
[Unreleased] placeholder.
Sample entry (operator confirms the date on ship day):
## [0.10.11] - <YYYY-MM-DD set on the day the release ships>
### Added
- `o2b install --target X [--apply|--check]` for Cursor, Aider,
opencode, kiro, GitHub Copilot CLI, Google Gemini CLI, Pi, and
generic printout.
- `o2b uninstall --target X` driven by the new sidecar manifest at
`<vault>/.open-second-brain/install.lock.json`.
- `o2b init --interactive` first-time-setup wizard.
- `o2b mcp --writer-only` and `o2b mcp --probe` subflags.
- `Brain/_brain.yaml` `active.most_applied.{window_days, limit}`
block. `brain_digest` and `Brain/active.md` honour the values;
default 30/10 unchanged.
- `Most-applied (Nd)` section in `brain_digest` Markdown and a
mirrored `most_applied` field in the JSON form.
- Per-runtime session-transcript awareness in `o2b discipline
report` for Claude Code, Codex, and Cursor.
- Documentation restructured into `install.md` router plus
`install/<target>.md` per-runtime files.
Step 5: Commit.
git commit -m "chore: release v0.10.11"
Task 31: Vault summary update (operator-coordinated)
Objective: Keep Projects/OpenSecondBrain/Features/_summary.md
in sync with what shipped.
This task does not run autonomously. The vault lives outside the repo and the operator decides what to write there. The executing agent prepares a draft snippet and presents it to the operator for manual application.
Draft to present:
- Β§4 β strike "second half deferred" and mark the line that closes it. Note PR + release tag.
- Β§15 β same for the wizard half.
- Deferred section Β§D non-bash-runtime activity sources β replace with "partial uptake shipped in v0.10.11; remaining runtimes (opencode / kiro / Copilot CLI / Gemini CLI / Aider / Pi) stay deferred. Trigger: stable upstream transcript paths and operator use."
- Add new deferred items per spec Β§12 (project-scope, Pi path auto-detect, interactive apply, restart hooks).
Pause: print the snippet to the operator, ask them to drop it into
the vault file. The executing agent does not edit
/root/vault/Projects/... directly.
Final pass
- Full test suite green.
bun test
- Typecheck clean.
bun run typecheck
- Lint clean (if the repo wires one β verify
package.json scripts).
bun run lint
Spec compliance walk-through. Re-read
docs/plans/2026-05-20-multi-runtime-install-design.mdand tick each Β§1.1 deliverable against shipped code. If any deliverable is missing, list it in the operator handoff message.CHANGELOG matches reality. Run
git log v0.10.10..HEAD --onelineand verify every commit subject maps to a CHANGELOG bullet.Hermes preview restart (operator-coordinated, if Hermes is the active runtime on this server). After the operator confirms the work is shippable:
hermes gateway restartWait for the new
Plugin discovery completeline in~/.hermes/logs/agent.logbefore testing live.Operator handoff. Summary message to operator:
v0.10.11 ready. Seven new install targets land; Most-applied now configurable. Reviewed against design doc, all tasks checked off. Suggest reviewing the seven new adapter files and the new CLI verbs before tag and release. The vault summary draft is in Task 31 β apply when ready.
Implementation order recap
| # | Task | Depends on |
|---|---|---|
| 1 | types.ts interfaces |
β |
| 2 | manifest.ts |
1 |
| 3 | json-merge.ts |
β (independent helper) |
| 4 | managed-block.ts |
β |
| 5 | payload.ts |
β |
| 6 | Registry | 1 |
| 7 | cursor adapter |
2, 3, 5, 6 |
| 8 | opencode adapter |
7 |
| 9 | kiro adapter |
7 |
| 10 | gemini-cli adapter |
7 |
| 11 | copilot-cli adapter |
6, 3 |
| 12 | aider adapter |
4, 6 |
| 13 | pi adapter |
6 |
| 14 | generic adapter |
6 |
| 15 | o2b mcp --writer-only |
β |
| 16 | o2b mcp --probe |
β |
| 17 | o2b install CLI |
7-14, 15 |
| 18 | o2b uninstall --target X |
17 |
| 19 | o2b install --check |
16, 17 |
| 20 | o2b init --interactive |
17 |
| 21 | active.most_applied config |
β |
| 22 | computeMostApplied params |
21 |
| 23 | active.md honours config |
22 |
| 24 | digest JSON most_applied | 22 |
| 25 | digest Markdown section | 24 |
| 26 | sessionPaths resolvers | β |
| 27 | discipline-report transcripts | 26 |
| 28 | docs restructure | 17-20 |
| 29 | README quick install | 28 |
| 30 | CHANGELOG + version | every preceding task |
| 31 | vault summary | 30 |
Tasks 1-6 are setup; they can land as one feature branch. Tasks 7-14 (adapters) are independent of each other once 1-6 are done β they can land in any order. Tasks 15-16 land in parallel with adapters. Tasks 17-20 (CLI verbs) gate on adapters being done. Tasks 21-25 (Theme 2) are entirely independent of Theme 1 and can land in parallel. Tasks 26-27 (Companion 2) are independent of both. Tasks 28-31 are the wrap.