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.
TypeScript
/**
* Install (and remove) CLI symlinks for `o2b` and `vault-log` in `~/.local/bin`.
* On native Windows the same verbs write `.cmd` launchers instead - see
* `install-cli-windows.ts`.
*
* Mirrors `src/open_second_brain/install_cli.py`. Refuses to overwrite a
* symlink that already points to a different repo's checkout — that's the
* documented behavior across multi-runtime installs.
*/
import {
existsSync,
lstatSync,
mkdirSync,
readlinkSync,
realpathSync,
statSync,
symlinkSync,
unlinkSync,
} from "node:fs";
import { dirname, join, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
import { userBinDir } from "../core/platform-dirs.ts";
import type { InstallResult, UninstallResult } from "../core/types.ts";
import { healCliWindows, installCliWindows, uninstallCliWindows } from "./install-cli-windows.ts";
const CLI_SCRIPTS = ["o2b", "vault-log", "o2b-hook"] as const;
function repoRoot(): string {
// src/cli/install-cli.ts → repo/
return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
}
function scriptsDir(): string {
return join(repoRoot(), "scripts");
}
function findScript(name: string): string | null {
const path = join(scriptsDir(), name);
if (existsSync(path) && statSync(path).isFile()) return resolve(path);
return null;
}
function isLink(p: string): boolean {
try {
return lstatSync(p).isSymbolicLink();
} catch {
return false;
}
}
/**
* Match Python's `Path.resolve()` semantics, which follows symlinks. Plain
* `path.resolve()` does not — it just normalises path components.
*/
function realpath(p: string): string {
try {
return realpathSync(p);
} catch {
return resolve(p);
}
}
function isValidSymlink(link: string, target: string): boolean {
try {
return realpath(link) === realpath(target);
} catch {
return false;
}
}
/** Raw (possibly relative) target stored in the symlink, or null. */
function rawLinkTarget(link: string): string | null {
try {
return readlinkSync(link);
} catch {
return null;
}
}
/** True when the symlink resolves to an existing file (i.e. is not dangling). */
function linkResolves(link: string): boolean {
try {
return existsSync(realpathSync(link));
} catch {
return false;
}
}
/**
* Does an absolute path look like one of OUR CLI scripts from some Open Second
* Brain checkout, i.e. `<anything>/scripts/<name>`? Used to decide whether a
* non-current symlink is safe to reclaim (ours, just stale) vs. owned by an
* unrelated tool (leave it alone).
*/
function looksLikeOsbScript(absTarget: string, name: string): boolean {
const parts = absTarget.split(sep);
return parts[parts.length - 1] === name && parts[parts.length - 2] === "scripts";
}
/** Heuristic: the target lives inside a Claude Code plugin cache, which rotates
* version directories on update (so the symlink is expected to go stale). */
function underPluginCache(absTarget: string): boolean {
return absTarget.includes(`${sep}plugins${sep}cache${sep}`);
}
/** Absolute form of a symlink's stored target (resolved against the link dir). */
function absoluteTarget(link: string): string | null {
const raw = rawLinkTarget(link);
if (raw === null) return null;
return resolve(dirname(link), raw);
}
/**
* Explicit `install-cli` may reclaim a symlink that is dangling or that points
* at any OSB checkout's `scripts/<name>` (the user ran install-cli on purpose,
* so re-pointing to the running checkout is the intent). It must NOT clobber a
* symlink owned by an unrelated tool or a real file.
*/
function canReclaimOnInstall(link: string, name: string): boolean {
if (!linkResolves(link)) return true; // dangling
const abs = absoluteTarget(link);
return abs !== null && looksLikeOsbScript(abs, name);
}
export function installCli(bindir?: string): InstallResult {
const dir = bindir ?? userBinDir();
if (process.platform === "win32") return installCliWindows(CLI_SCRIPTS, scriptsDir(), dir);
mkdirSync(dir, { recursive: true });
const outcomes: Array<readonly [string, string]> = [];
const errors: string[] = [];
for (const name of CLI_SCRIPTS) {
const link = join(dir, name);
const source = findScript(name);
if (source === null) {
const msg = `error: script 'scripts/${name}' not found in ${scriptsDir()}`;
outcomes.push([name, msg]);
errors.push(msg);
continue;
}
if (isLink(link)) {
if (isValidSymlink(link, source)) {
outcomes.push([name, `exists: ${link} → ${source}`]);
} else if (canReclaimOnInstall(link, name)) {
// Stale OSB symlink (e.g. pointing at a removed/old plugin version) or
// a dangling link: re-point it to the current checkout instead of
// forcing the user to delete it by hand. Idempotent across updates.
try {
unlinkSync(link);
symlinkSync(source, link);
outcomes.push([name, `repointed: ${link} → ${source}`]);
} catch (exc) {
const msg = `error: could not repoint symlink ${link}: ${(exc as Error).message ?? exc}`;
outcomes.push([name, msg]);
errors.push(msg);
}
} else {
let existing = "unknown";
try {
existing = readlinkSync(link);
} catch {
// ignore
}
// Conflict with a symlink owned by an unrelated tool: refuse, and
// report as an error so cmdInstallCli exits non-zero.
const msg = `error: ${link} already points to ${existing} (not an Open Second Brain script), not overwriting`;
outcomes.push([name, msg]);
errors.push(msg);
}
} else if (existsSync(link)) {
const msg = `error: ${link} exists and is not a symlink, not overwriting`;
outcomes.push([name, msg]);
errors.push(msg);
} else {
try {
symlinkSync(source, link);
outcomes.push([name, `created: ${link} → ${source}`]);
} catch (exc) {
const msg = `error: could not create symlink ${link}: ${(exc as Error).message ?? exc}`;
outcomes.push([name, msg]);
errors.push(msg);
}
}
}
return { bindir: dir, outcomes, errors };
}
/**
* Best-effort, non-interactive repair of the `~/.local/bin` CLI symlinks,
* meant to run from a SessionStart hook. Unlike `installCli`, this is automatic
* and therefore conservative: it only touches a symlink that is
* - dangling (its target was removed by a plugin update), or
* - an OSB `scripts/<name>` link that lives inside a Claude Code plugin cache
* (which rotates version dirs on update) and is not already current.
* It NEVER repoints a stable-directory install (e.g. `/srv/projects/...` used by
* Hermes/Codex on a server), never touches a foreign symlink, and never touches
* a real file. Resolves the current checkout from this module's own location,
* so it heals even when the on-PATH `o2b` is the stale one.
*/
export function healCliSymlinks(bindir?: string): InstallResult {
const dir = bindir ?? userBinDir();
if (process.platform === "win32") return healCliWindows(CLI_SCRIPTS, scriptsDir(), dir);
const outcomes: Array<readonly [string, string]> = [];
const errors: string[] = [];
for (const name of CLI_SCRIPTS) {
const link = join(dir, name);
const source = findScript(name);
if (source === null) continue; // cannot heal what we cannot source
if (!isLink(link)) continue; // absent, or a real file we must not touch
if (isValidSymlink(link, source)) continue; // already current
// Only auto-heal a link whose stored target is clearly OURS and lives in a
// version-rotating plugin cache (works for dangling links too, since the
// stored target is read via readlink). A dangling link that points at a
// stable-dir or foreign install is left alone - automatic repair must not
// hijack installs it does not own.
const abs = absoluteTarget(link);
const reclaimable = abs !== null && looksLikeOsbScript(abs, name) && underPluginCache(abs);
if (!reclaimable) continue;
try {
unlinkSync(link);
symlinkSync(source, link);
outcomes.push([name, `healed: ${link} → ${source}`]);
} catch (exc) {
errors.push(`could not heal ${link}: ${(exc as Error).message ?? exc}`);
}
}
return { bindir: dir, outcomes, errors };
}
export function uninstallCli(bindir?: string): UninstallResult {
const dir = bindir ?? userBinDir();
if (process.platform === "win32") return uninstallCliWindows(CLI_SCRIPTS, scriptsDir(), dir);
const repoScripts = scriptsDir();
const outcomes: Array<readonly [string, string]> = [];
const errors: string[] = [];
for (const name of CLI_SCRIPTS) {
const link = join(dir, name);
if (!isLink(link)) {
if (existsSync(link)) {
outcomes.push([name, `skipped: ${link} is not a symlink — refusing to remove`]);
} else {
outcomes.push([name, `skipped: ${link} does not exist`]);
}
continue;
}
let target: string;
try {
target = realpath(link);
} catch (exc) {
const msg = `error: cannot resolve ${link}: ${(exc as Error).message ?? exc}`;
outcomes.push([name, msg]);
errors.push(msg);
continue;
}
const repoScriptsReal = realpath(repoScripts);
if (!target.startsWith(repoScriptsReal + sep) && target !== repoScriptsReal) {
outcomes.push([
name,
`skipped: ${link} → ${target} is outside this repo's scripts/ — refusing to remove`,
]);
continue;
}
try {
unlinkSync(link);
outcomes.push([name, `removed: ${link}`]);
} catch (exc) {
const msg = `error: cannot unlink ${link}: ${(exc as Error).message ?? exc}`;
outcomes.push([name, msg]);
errors.push(msg);
}
}
return { bindir: dir, outcomes, errors };
}
export function renderInstallResult(result: InstallResult): string {
const lines: string[] = [];
lines.push(`o2b install-cli — ${result.bindir}`);
lines.push("-".repeat(40));
for (const [name, msg] of result.outcomes) {
lines.push(` ${name}: ${msg}`);
}
if (result.errors.length > 0) {
lines.push("");
lines.push(`${result.errors.length} error(s).`);
}
return lines.join("\n").replace(/\s+$/g, "") + "\n";
}
export function renderUninstallResult(result: UninstallResult): string {
const lines: string[] = [];
lines.push(`o2b uninstall --remove-cli — ${result.bindir}`);
lines.push("-".repeat(40));
for (const [name, msg] of result.outcomes) {
lines.push(` ${name}: ${msg}`);
}
if (result.errors.length > 0) {
lines.push("");
lines.push(`${result.errors.length} error(s).`);
}
return lines.join("\n").replace(/\s+$/g, "") + "\n";
}