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
#!/usr/bin/env bun
/**
* Mirror the shared plugin assets into the Codex plugin subtree.
*
* Codex's marketplace source is `./plugins/codex` (`.agents/plugins/
* marketplace.json`), and `codex plugin add` copies only that subtree into
* `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/`. The copy
* DROPS symlinks. `plugins/codex/hooks` and `plugins/codex/skills` used to
* be symlinks into the repo root, so every installed Codex plugin had no
* hooks and no skills. Every Codex run also warned `failed to read plugin
* hooks config .../hooks/hooks.json`. Symlinks are fragile on Windows too:
* without Developer Mode or `core.symlinks`, git checks one out as a plain
* text file that holds the target path.
*
* So the Codex plugin ships real files, and this script keeps them in step
* with their source. It follows the shape of `scripts/sync-version.ts`: the
* write form and the `--check` form are the same code path, so what CI
* detects and what the write form produces cannot diverge.
*
* What is mirrored, and what is deliberately NOT:
* - `skills/**` -> `plugins/codex/skills/**`, every file, byte for byte.
* - `hooks/hooks.json` -> `plugins/codex/hooks/hooks.json`, with two
* Codex-specific changes. SessionEnd timeouts are capped at
* {@link CODEX_SESSION_END_TIMEOUT_CAP_SEC}: Codex clamps them there
* anyway, and warns on every run while the file asks for more. And every
* hook gets a `commandWindows` ({@link codexWindowsHookCommand}): on
* Windows Codex runs a hook as `%COMSPEC% /C "<command>"`, where the
* POSIX `command` cannot parse.
* - `LICENSE` and `.codexignore` -> the same names under `plugins/codex/`,
* byte for byte, so the subtree Codex installs carries its own license
* and ignore list.
* - `README.md` and `SECURITY.md` -> the same names under `plugins/codex/`,
* with relative links made absolute ({@link withAbsoluteLinks}): the
* mirror sits two levels down, where the root's relative links resolve
* to nothing.
* - NOT `hooks/*.ts`. The hook commands run `o2b-hook <name>`, which
* resolves the checkout that holds `hooks/<name>.ts` (see
* `scripts/o2b-hook`). Codex exports `CLAUDE_PLUGIN_ROOT` as the cache
* dir, so a copied script there would win that resolution and then
* fail on its `../src` imports, which the cache does not have. Without
* the scripts, resolution falls through to the real checkout.
*
* Usage:
* bun run scripts/sync-plugin-mirrors.ts # rewrite the mirrors
* bun run scripts/sync-plugin-mirrors.ts --check # exit 1 on drift, no writes
*/
import {
existsSync,
lstatSync,
mkdirSync,
readdirSync,
readFileSync,
rmSync,
writeFileSync,
} from "node:fs";
import { dirname, join, relative, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
/**
* The longest SessionEnd hook timeout Codex honours, in seconds. Codex
* 0.157.0 clamps a longer one and warns `clamping SessionEnd hook timeout
* to 3s` on every run.
*/
export const CODEX_SESSION_END_TIMEOUT_CAP_SEC = 3;
export interface MirrorSpec {
/** Source, relative to the repo root: a directory or a single file. */
readonly source: string;
/** Destination, relative to the repo root. */
readonly target: string;
/** Derives the mirrored bytes from the source bytes. Absent: a byte copy. */
readonly transform?: (source: string) => string;
}
interface HookGroup {
hooks?: Array<{ command?: string; commandWindows?: string; timeout?: number }>;
}
/**
* The POSIX hook command, which ends by running the PATH `o2b-hook` shim
* with the hook's name. The name is the one thing the Windows form needs.
*/
const POSIX_HOOK_COMMAND =
/command -v o2b-hook >\/dev\/null 2>&1 && exec o2b-hook ([a-z][a-z0-9-]*); exit 0$/;
/**
* The `commandWindows` form of a hook, which Codex runs through cmd.exe.
*
* It calls the PATH `o2b-hook` shim only, the same fallback the POSIX command
* reaches under Codex (`CLAUDE_PLUGIN_ROOT` is Codex's cache dir, which holds
* no scripts). `o2b install-cli` writes that shim as `o2b-hook.cmd`.
* - `NoDefaultCurrentDirectoryInExePath` is set first: cmd.exe otherwise
* looks for `where` and `o2b-hook` in the current directory before PATH,
* and Codex runs hooks in the project it opened, so a repository could
* ship its own `o2b-hook.cmd`.
* - `where /q $PATH:o2b-hook` keeps a missing shim silent. The `$PATH:`
* scope matters: a bare `where` searches the current directory too, and
* would pass for a planted file that cmd.exe then refuses to run.
* - `exit /b 0` keeps any outcome non-blocking, as `exit 0` does in the
* POSIX form.
* - No double quotes: cmd.exe then strips only the pair Codex wraps the
* line in.
*/
export function codexWindowsHookCommand(hook: string): string {
return `set NoDefaultCurrentDirectoryInExePath=1& where /q $PATH:o2b-hook && o2b-hook ${hook} & exit /b 0`;
}
/** `hooks/hooks.json` as Codex should read it. Formatting matches the source (oxfmt). */
export function codexHooksJson(source: string): string {
const doc = JSON.parse(source) as { hooks?: Record<string, HookGroup[]> };
for (const [event, groups] of Object.entries(doc.hooks ?? {})) {
for (const group of groups) {
group.hooks = (group.hooks ?? []).map((hook) => {
if (
event === "SessionEnd" &&
typeof hook.timeout === "number" &&
hook.timeout > CODEX_SESSION_END_TIMEOUT_CAP_SEC
) {
hook.timeout = CODEX_SESSION_END_TIMEOUT_CAP_SEC;
}
if (hook.command === undefined) return hook;
const name = POSIX_HOOK_COMMAND.exec(hook.command)?.[1];
if (name === undefined) {
// Fail the sync rather than ship a hook that cmd.exe cannot run.
throw new Error(
`${event} hook command does not end in the o2b-hook fallback; ` +
`cannot derive its Windows form: ${hook.command}`,
);
}
// Rebuilt key by key, so that commandWindows sits right after command.
const out: Record<string, unknown> = {};
for (const [key, value] of Object.entries(hook)) {
if (key === "commandWindows") continue;
out[key] = value;
if (key === "command") out["commandWindows"] = codexWindowsHookCommand(name);
}
return out;
});
}
}
return `${JSON.stringify(doc, null, 2)}\n`;
}
/** Where a root document's relative links point once it is mirrored. */
export const REPO_BLOB_URL = "https://github.com/itechmeat/open-second-brain/blob/main";
/** Where its relative images point: `raw`, so GitHub serves the file rather than a page. */
export const REPO_RAW_URL = "https://github.com/itechmeat/open-second-brain/raw/main";
/** A Markdown link or image whose target is repo-relative: not a URL, an anchor or mail. */
const RELATIVE_MARKDOWN_LINK = /(!?)\[([^\]\n]*)\]\((?![a-z][a-z0-9+.-]*:|#|\/)([^)\s]+)\)/gi;
/** A root Markdown document as the Codex subtree carries it: every relative link made absolute. */
export function withAbsoluteLinks(source: string): string {
return source.replace(
RELATIVE_MARKDOWN_LINK,
(_match, bang: string, text: string, target: string) =>
`${bang}[${text}](${bang === "!" ? REPO_RAW_URL : REPO_BLOB_URL}/${target.replace(/^\.\//, "")})`,
);
}
export const MIRRORS: ReadonlyArray<MirrorSpec> = [
{ source: "skills", target: "plugins/codex/skills" },
{
source: "hooks/hooks.json",
target: "plugins/codex/hooks/hooks.json",
transform: codexHooksJson,
},
{ source: "LICENSE", target: "plugins/codex/LICENSE" },
{ source: ".codexignore", target: "plugins/codex/.codexignore" },
{ source: "README.md", target: "plugins/codex/README.md", transform: withAbsoluteLinks },
{ source: "SECURITY.md", target: "plugins/codex/SECURITY.md", transform: withAbsoluteLinks },
];
/** Directories the mirrors own outright: a file in them that no spec produces is drift. */
export const MIRROR_DIRS: ReadonlyArray<string> = ["plugins/codex/skills", "plugins/codex/hooks"];
export interface Drift {
readonly path: string;
readonly reason: "missing" | "differs" | "extra" | "symlink";
}
interface Pair {
readonly source: string;
readonly target: string;
readonly transform?: (source: string) => string;
}
function toPosix(p: string): string {
return p.split(sep).join("/");
}
function isSymlink(path: string): boolean {
try {
return lstatSync(path).isSymbolicLink();
} catch {
return false;
}
}
/** Every regular file under `dir`, relative to it, sorted. Symlinks are collected, not followed. */
function listFiles(dir: string, symlinks: string[], base = dir): string[] {
const out: string[] = [];
for (const name of readdirSync(dir).toSorted()) {
const full = join(dir, name);
const st = lstatSync(full);
if (st.isSymbolicLink()) symlinks.push(full);
else if (st.isDirectory()) out.push(...listFiles(full, symlinks, base));
else if (st.isFile()) out.push(toPosix(relative(base, full)));
}
return out;
}
/** The (source, target) file pairs every mirror spec expands to. */
function expectedPairs(root: string): Pair[] {
const pairs: Pair[] = [];
for (const spec of MIRRORS) {
const src = join(root, spec.source);
if (!lstatSync(src).isDirectory()) {
pairs.push(spec);
continue;
}
const symlinks: string[] = [];
for (const rel of listFiles(src, symlinks)) {
pairs.push({ source: `${spec.source}/${rel}`, target: `${spec.target}/${rel}` });
}
if (symlinks.length > 0) {
const names = symlinks.map((s) => toPosix(relative(root, s))).join(", ");
throw new Error(
`mirror source ${spec.source} contains symlinks (${names}); Codex drops them`,
);
}
}
return pairs;
}
/** The bytes a mirrored file must hold. */
function expectedBytes(root: string, pair: Pair): Buffer {
const raw = readFileSync(join(root, pair.source));
return pair.transform === undefined
? raw
: Buffer.from(pair.transform(raw.toString("utf8")), "utf8");
}
/** Compare the mirrors against their sources without writing. */
export function findDrift(root: string = ROOT): Drift[] {
const drift: Drift[] = [];
const pairs = expectedPairs(root);
const expectedTargets = new Set(pairs.map((p) => p.target));
const linkedDirs: string[] = [];
for (const dir of MIRROR_DIRS) {
const full = join(root, dir);
if (isSymlink(full)) {
drift.push({ path: dir, reason: "symlink" });
linkedDirs.push(dir);
continue;
}
if (!existsSync(full)) continue;
const symlinks: string[] = [];
for (const rel of listFiles(full, symlinks)) {
const path = `${dir}/${rel}`;
if (!expectedTargets.has(path)) drift.push({ path, reason: "extra" });
}
for (const s of symlinks) drift.push({ path: toPosix(relative(root, s)), reason: "symlink" });
}
for (const pair of pairs) {
if (linkedDirs.some((d) => pair.target.startsWith(`${d}/`))) continue;
const dst = join(root, pair.target);
// A symlinked single file reads as identical here, yet Codex drops it.
if (isSymlink(dst)) drift.push({ path: pair.target, reason: "symlink" });
else if (!existsSync(dst)) drift.push({ path: pair.target, reason: "missing" });
else if (!expectedBytes(root, pair).equals(readFileSync(dst))) {
drift.push({ path: pair.target, reason: "differs" });
}
}
return drift;
}
/** Rebuild every mirror from its source. Returns the number of files written. */
export function writeMirrors(root: string = ROOT): number {
const pairs = expectedPairs(root);
const contents = pairs.map((pair) => expectedBytes(root, pair));
for (const dir of MIRROR_DIRS) rmSync(join(root, dir), { recursive: true, force: true });
pairs.forEach((pair, i) => {
const dst = join(root, pair.target);
mkdirSync(dirname(dst), { recursive: true });
// Writing through a symlink would leave the link in place.
if (isSymlink(dst)) rmSync(dst);
writeFileSync(dst, contents[i]!);
});
return pairs.length;
}
function main(argv: ReadonlyArray<string>): number {
if (!argv.includes("--check")) {
const n = writeMirrors();
process.stdout.write(`wrote ${n} mirrored file(s) into plugins/codex\n`);
return 0;
}
const drift = findDrift();
if (drift.length === 0) {
process.stdout.write("plugin mirrors: ok\n");
return 0;
}
for (const d of drift) process.stderr.write(` DRIFT (${d.reason}): ${d.path}\n`);
process.stderr.write(`\n${drift.length} drifted path(s); run: bun run sync-plugin-mirrors\n`);
return 1;
}
if (import.meta.main) {
process.exit(main(process.argv.slice(2)));
}