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
/**
* Codex CLI adapter — subprocess-driven, with a TOML section merge into
* `$CODEX_HOME/config.toml` when the `codex` binary is absent.
*
* Primary path:
* - `codex mcp remove <name>` (best-effort; non-zero is fine when the
* server was not registered)
* - `codex mcp add <name> [--env K=V ...] -- <command> <args...>`
*
* Fallback path:
* - upsert the two `[mcp_servers.<name>]` tables into
* `$CODEX_HOME/config.toml`, which is where `codex mcp add` persists
* them anyway. Every unrelated table - `[plugins."..."]`,
* `[marketplaces....]`, a foreign `[mcp_servers.*]` - survives
* byte-for-byte.
*
* ## Why `verify` asks two different questions of one file
*
* Unlike `copilot-cli`, whose subprocess mode leaves NO artifact, both
* Codex paths end in the same `config.toml`. What differs is who wrote
* the bytes:
*
* - **fallback mode**: this build serialised the tables, so `verify`
* compares them against the payload it would write today. Any edit
* is drift.
* - **subprocess mode**: the Codex CLI serialised them in its own
* layout, which this build has no published grammar for and must not
* guess at. `verify` therefore checks that the two tables are still
* DECLARED and lets `codex mcp list` answer whether the host is
* actually serving them. That is a presence check, not a byte check,
* and the detail line says so rather than implying more.
*
* ## The Codex home is injected, never ambient
*
* `CODEX_HOME` relocates the whole Codex configuration directory, and the
* Codex CLI REFUSES to start when it points at a path that does not
* exist. The runner seam therefore takes the resolved home as its first
* argument and the default runner creates it before spawning: an adapter
* that resolved `InstallEnv.home` for its own file writes while its
* subprocess wrote the ambient `~/.codex` would install into two places
* at once - and would mutate the operator's real machine from a test.
*
* Two seams, for the reason `copilot-cli.ts` states: `CodexRunner` owns
* the commands that CHANGE this host, while `../host-probe.ts` owns the
* read-only question "what does this host say it has registered",
* declared once in `RUNTIME_FACTS[codex].hostProbe`. BOTH seams take the
* injected home - the probe through `hostProbeEnvironment(env)` - so the
* file half and the handshake half of a `verify` describe one machine.
* They described two for a release: the file half read the relocated
* `CODEX_HOME` while `codex mcp list` answered about the operator's real
* `~/.codex`.
*/
import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { codexHome as resolveCodexHome, INSTALL_TARGET_ID } from "../../runtime/host-facts.ts";
import { hasMcpServers, removeMcpServers, upsertMcpServers } from "../grok-config.ts";
import type { GrokMcpEntry } from "../grok-config.ts";
import {
handshakeNote,
probeHost,
probeRefutedVerdict,
probeRefutes,
HOST_PROBE_RESULT,
} from "../host-probe.ts";
import { payloadWithRuntimeIdentity } from "../identity.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../json-merge.ts";
import { readManifest, recordEntry, removeEntry } from "../manifest.ts";
import { expectedPayloadFromEnv } from "../payload-equals.ts";
import { payloadForHost } from "../payload-host.ts";
import { defaultRegistry } from "../registry.ts";
import {
InstallError,
type ApplyOpts,
type ApplyResult,
type DetectResult,
type InstallAdapter,
type InstallEnv,
type InstallPlan,
type ManifestEntry,
type McpPayload,
type McpServerEntry,
type UninstallResult,
type VerifyResult,
type SessionPathsResult,
} from "../types.ts";
import { sessionPathsFor } from "../session-paths.ts";
const TARGET = INSTALL_TARGET_ID.codex;
const LABEL = "Codex CLI";
const FIX_HINT = `o2b install --target ${TARGET} --apply`;
const SERVER_NAMES: ReadonlyArray<string> = Object.freeze([OSB_KEY_FULL, OSB_KEY_WRITER]);
/**
* ChatGPT desktop has no MCP registration of its own: it reads the same
* `$CODEX_HOME/config.toml` this adapter writes, so the codex
* registration serves it. It is named in the merge-lane detect note - a
* note, never a status or a target - because an operator on a machine
* with only the desktop app reads exactly this line in `o2b install`'s
* detect output and otherwise has no surface telling them this target is
* theirs. There is deliberately no ChatGPT install target id: a second
* target for one config file would claim bytes the codex target owns and
* report them as drift.
*/
const MERGE_LANE_NOTE =
"codex CLI not on PATH; registration goes through the config.toml merge, " +
"the same file ChatGPT desktop reads";
/**
* Codex's vendor token, combined with the operator's host segment into a
* host-qualified identity by `../identity.ts` - so a Brain write made
* through Codex says `codex-<host>-agent` instead of masquerading as the
* operator's own name, exactly as grok and opencode already do.
*/
export const CODEX_RUNTIME_ID = TARGET;
// ---------- Injectable subprocess runner ----------
export interface CodexRunResult {
readonly exitCode: number;
readonly stdout: string;
readonly stderr: string;
}
export interface CodexRunner {
available(): boolean;
/** `codex <args>` with `CODEX_HOME` set to `home`, which must exist. */
run(home: string, args: ReadonlyArray<string>): CodexRunResult;
}
const defaultRunner: CodexRunner = {
available(): boolean {
try {
return Bun.which("codex") !== null;
} catch {
return false;
}
},
run(home, args) {
// Codex refuses to load a configuration whose `CODEX_HOME` does not
// exist, so the directory is created before the spawn rather than
// letting the operator read that refusal as an OSB failure.
if (!existsSync(home)) mkdirSync(home, { recursive: true });
const r = Bun.spawnSync({
cmd: ["codex", ...args],
env: { ...process.env, CODEX_HOME: home },
stdout: "pipe",
stderr: "pipe",
});
return {
exitCode: r.exitCode ?? 1,
stdout: r.stdout?.toString() ?? "",
stderr: r.stderr?.toString() ?? "",
};
},
};
let activeRunner: CodexRunner = defaultRunner;
export function setCodexRunner(runner: CodexRunner): void {
activeRunner = runner;
}
export function resetCodexRunner(): void {
activeRunner = defaultRunner;
}
// ---------- Paths and payload ----------
/**
* The Codex configuration directory this install is about.
*
* Delegated to `../../runtime/host-facts.ts` rather than re-derived: that
* module already resolves the same `$CODEX_HOME`-or-`~/.codex` rule for
* the session roots, and two copies of a relocation rule is two answers
* waiting to disagree.
*/
function codexHome(env: InstallEnv): string {
return resolveCodexHome({ home: env.home, env: env.env });
}
function configPath(env: InstallEnv): string {
return join(codexHome(env), "config.toml");
}
function readFileOrEmpty(path: string): string {
try {
return readFileSync(path, "utf8");
} catch {
return "";
}
}
/** The payload as this host must receive it: host dimensions, then identity. */
function codexPayload(raw: McpPayload, env: InstallEnv): McpPayload {
return payloadWithRuntimeIdentity(payloadForHost(TARGET, raw, env), CODEX_RUNTIME_ID);
}
/** The same payload rebuilt from the env alone, for the verify path. */
function expectedPayload(env: InstallEnv): McpPayload {
return payloadWithRuntimeIdentity(expectedPayloadFromEnv(env, TARGET), CODEX_RUNTIME_ID);
}
/**
* The two tables to write, in the shape `../grok-config.ts` serialises.
*
* That module is reused rather than re-implemented: Codex and grok name
* the same `[mcp_servers.<name>]` table with the same `command` /
* `args` / `env` value shapes, and a second line-section TOML editor in
* this tree would be one more place for the byte-for-byte preservation
* guarantee to be got wrong.
*/
function tomlEntry(entry: McpServerEntry): GrokMcpEntry {
return {
command: entry.command,
args: [...entry.args],
...(entry.env ? { env: { ...entry.env } } : {}),
};
}
function codexMcpServers(payload: McpPayload): Record<string, GrokMcpEntry> {
return {
[OSB_KEY_FULL]: tomlEntry(payload.full),
[OSB_KEY_WRITER]: tomlEntry(payload.writer),
};
}
/**
* Whether `toml` DECLARES the `[mcp_servers.<name>]` table.
*
* Anchored to a whole line, and that is the point. A substring search
* matches `# [mcp_servers.open-second-brain]` as readily as the table
* itself, so an operator who commented both tables out - the ordinary way
* to turn a server off - got `detect: installed` and `verify: ok` for a
* registration Codex would not load. A commented header is the operator
* saying no, and a reader that cannot tell it from a yes is reporting on a
* file it did not understand.
*
* Leading whitespace is tolerated because TOML permits an indented table
* header; anything else on the line - a `#`, a second table, trailing
* prose - means this is not that header.
*/
function declaresTable(toml: string, name: string): boolean {
const header = `[mcp_servers.${name}]`;
return toml.split("\n").some((line) => line.trim() === header);
}
/** Whether both of our tables are declared at all, whoever wrote them. */
function declaresBothServers(toml: string): boolean {
return SERVER_NAMES.every((name) => declaresTable(toml, name));
}
function declaredServers(toml: string): ReadonlyArray<string> {
return SERVER_NAMES.filter((name) => declaresTable(toml, name));
}
/** The clause naming which of the two tables the file is missing. */
function undeclared(toml: string): string {
const missing = SERVER_NAMES.filter((name) => !declaresTable(toml, name));
return `does not declare ${missing.join(", ")}`;
}
// ---------- Apply helpers ----------
/** `codex mcp add <name> [--env K=V ...] -- <command> <args...>`. */
function addArgs(name: string, entry: McpServerEntry): string[] {
const args = ["mcp", "add", name];
for (const [key, value] of Object.entries(entry.env ?? {})) args.push("--env", `${key}=${value}`);
args.push("--", entry.command, ...entry.args);
return args;
}
function applyViaCli(
env: InstallEnv,
payload: McpPayload,
stderr: NodeJS.WriteStream | NodeJS.WritableStream,
): boolean {
const base = codexHome(env);
for (const name of SERVER_NAMES) activeRunner.run(base, ["mcp", "remove", name]);
for (const [name, entry] of [
[OSB_KEY_FULL, payload.full],
[OSB_KEY_WRITER, payload.writer],
] as const) {
const result = activeRunner.run(base, addArgs(name, entry));
if (result.exitCode !== 0) {
stderr.write(
`codex mcp add failed for ${name} (exit ${result.exitCode}): ${result.stderr.trim()}\n`,
);
return false;
}
}
return true;
}
function applyViaFile(
env: InstallEnv,
payload: McpPayload,
stderr: NodeJS.WriteStream | NodeJS.WritableStream,
dryRun: boolean,
): void {
const path = configPath(env);
const next = upsertMcpServers(readFileOrEmpty(path), codexMcpServers(payload));
if (!dryRun) {
const dir = dirname(path);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
atomicWriteFileSync(path, next);
}
stderr.write(`codex: wrote the MCP servers to ${path} (file-fallback mode)\n`);
}
/**
* Strip our two tables, leaving every other section untouched. Returns
* whether the file carried any of them.
*/
function stripOurTables(env: InstallEnv, dryRun: boolean): boolean {
const path = configPath(env);
const current = readFileOrEmpty(path);
if (declaredServers(current).length === 0) return false;
const next = removeMcpServers(current, SERVER_NAMES).replace(/\s*$/, "");
if (!dryRun) atomicWriteFileSync(path, next.length > 0 ? `${next}\n` : "");
return true;
}
// ---------- Adapter ----------
export const codexAdapter: InstallAdapter = {
target: TARGET,
label: LABEL,
detect(env: InstallEnv): DetectResult {
const path = configPath(env);
const declared = declaredServers(readFileOrEmpty(path));
const cliNote = activeRunner.available()
? "codex CLI present; registration goes through `codex mcp add`"
: MERGE_LANE_NOTE;
if (declared.length === SERVER_NAMES.length) {
return { target: TARGET, status: "installed", configPath: path, notes: [cliNote] };
}
if (declared.length > 0) {
return {
target: TARGET,
status: "drift",
configPath: path,
notes: [cliNote, `only ${declared.join(", ")} is declared`],
};
}
return { target: TARGET, status: "not-installed", configPath: path, notes: [cliNote] };
},
plan(rawPayload: McpPayload, env: InstallEnv): InstallPlan {
const path = configPath(env);
// The preview prints the args that will actually be registered, for
// the reason `_json-mcp.ts` prints them: a plan whose command line
// differs from the applied one is a plan the operator cannot use to
// review the change - and the host dimensions this transform adds
// (`--tool-profile`, `--host-target`) are exactly what a reviewer of
// a capped host is looking for.
const payload = codexPayload(rawPayload, env);
if (activeRunner.available()) {
const commands = [
...SERVER_NAMES.map((name) => `codex mcp remove ${name}`),
...(
[
[OSB_KEY_FULL, payload.full],
[OSB_KEY_WRITER, payload.writer],
] as const
).map(([name, entry]) => `codex ${addArgs(name, entry).join(" ")}`),
];
return {
target: TARGET,
steps: [
{
kind: "subprocess",
// Named even though the CLI writes it: this is where the
// registration lands, and an operator reading a plan is owed
// the file it will change.
path,
preview: `${commands.join("; ")} (persisted to ${path})`,
},
],
postNotes: [`codex CLI present; CODEX_HOME resolves to ${codexHome(env)}`],
};
}
const tables = Object.entries(codexMcpServers(payload)).map(
([name, entry]) => `[mcp_servers.${name}] → ${entry.command} ${entry.args.join(" ")}`,
);
return {
target: TARGET,
steps: [
{
kind: "managed-block",
path,
preview:
`codex CLI not on PATH; merge the two [mcp_servers.*] tables into ${path}: ` +
tables.join("; "),
},
],
postNotes: [
"the codex CLI was not detected; using the config.toml merge, which is the same file " +
"`codex mcp add` would have written",
"codex loads the MCP servers on its next session start",
],
};
},
apply(_plan: InstallPlan, rawPayload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult {
const payload = codexPayload(rawPayload, env);
let viaCli: boolean;
if (activeRunner.available()) {
viaCli = opts.dryRun ? true : applyViaCli(env, payload, opts.stderr);
if (!viaCli && !opts.dryRun) applyViaFile(env, payload, opts.stderr, false);
} else {
viaCli = false;
applyViaFile(env, payload, opts.stderr, opts.dryRun);
}
const manifest: ManifestEntry = {
target: TARGET,
applied_at: env.now.toISOString(),
operation: viaCli ? "subprocess" : "managed-block",
config_path: configPath(env),
owned_keys: [...SERVER_NAMES],
...(viaCli ? {} : { fallback_file: configPath(env) }),
};
if (!opts.dryRun) recordEntry(env.vault, manifest);
return { target: TARGET, manifest, steps_executed: opts.dryRun ? 0 : 1 };
},
uninstall(env: InstallEnv, opts: ApplyOpts & { fromSnippet?: boolean }): UninstallResult {
const stored = readManifest(env.vault).installs[TARGET];
if (!stored && !opts.fromSnippet) {
throw new InstallError(
`${TARGET}: no install manifest entry found`,
TARGET,
"manifest-missing",
`o2b uninstall --target ${TARGET} --apply --force-from-snippet`,
);
}
const removed_keys: string[] = [];
const removed_paths: string[] = [];
const skipped: Array<readonly [string, string]> = [];
// A skip is not a failure. "No OSB tables declared" means there was
// nothing left to remove, which is a completed uninstall; only a
// removal this build attempted and could not carry out may keep the
// manifest entry alive. Tracked apart from `skipped` for that reason.
let failed = false;
if (stored?.operation === "subprocess" && activeRunner.available()) {
if (opts.dryRun) {
// A dry run must not touch the host's registry; report what the
// two removals would take out.
removed_keys.push(...SERVER_NAMES);
} else {
for (const name of SERVER_NAMES) {
const result = activeRunner.run(codexHome(env), ["mcp", "remove", name]);
if (result.exitCode === 0) removed_keys.push(name);
else {
skipped.push([name, `codex mcp remove exited ${result.exitCode}`]);
failed = true;
}
}
}
} else if (stripOurTables(env, opts.dryRun)) {
// Also the repair path for a subprocess install whose CLI has since
// left the machine: the registration is in a file either way. The
// file is reported as a touched path, exactly as grok reports its
// hooks file - an uninstall that changed a file and named none left
// the operator nothing to check.
removed_keys.push(...SERVER_NAMES);
removed_paths.push(configPath(env));
} else {
skipped.push([configPath(env), "no OSB tables declared"]);
}
// Dropping the manifest entry after a FAILED removal is what makes the
// retry impossible: the next `o2b uninstall` finds no entry, throws
// `manifest-missing` and demands `--force-from-snippet` for a server
// that is still registered. grok already guards this; codex did not.
if (!opts.dryRun && !failed) removeEntry(env.vault, TARGET);
return { target: TARGET, removed_keys, removed_paths, skipped };
},
verify(env: InstallEnv): VerifyResult {
const stored = readManifest(env.vault).installs[TARGET];
if (!stored) {
return {
target: TARGET,
status: "not-installed",
details: ["no install manifest entry"],
fix_hint: FIX_HINT,
};
}
const path = configPath(env);
const toml = readFileOrEmpty(path);
const probe = probeHost(TARGET, env);
const declaresBoth = declaresBothServers(toml);
if (stored.operation === "subprocess") {
// The Codex CLI owns these bytes, so the host's own answer is the
// strongest evidence available and is taken first. That is only
// sound because the probe is asked about the SAME home this adapter
// resolved - `probeHost` spawns under `hostProbeEnvironment(env)`,
// so a relocated `CODEX_HOME` cannot be verified against the
// operator's ambient `~/.codex`. The file is consulted only where
// that answer is absent or negative - and it is consulted for
// PRESENCE, because this build has no published grammar for the
// layout the CLI writes and will not guess one.
if (probe.kind === HOST_PROBE_RESULT.answered) {
if (probe.missing.length === 0) {
return { target: TARGET, status: "ok", details: [handshakeNote(probe)], fix_hint: null };
}
const verdict = probeRefutedVerdict({
target: TARGET,
label: LABEL,
artifactMatches: declaresBoth,
});
return {
target: TARGET,
status: verdict.status,
details: [
declaresBoth
? `${path}: declares both OSB servers, but ${handshakeNote(probe)}`
: `${path}: ${undeclared(toml)} (${handshakeNote(probe)})`,
],
fix_hint: verdict.fixHint,
};
}
if (!declaresBoth) {
return {
target: TARGET,
status: "drift",
details: [`${path}: ${undeclared(toml)} (${handshakeNote(probe)})`],
fix_hint: FIX_HINT,
};
}
return {
target: TARGET,
status: "ok",
details: [
`${path}: both OSB servers declared, in the layout the codex CLI wrote ` +
`(${handshakeNote(probe)})`,
],
fix_hint: null,
};
}
// File-fallback mode: this build wrote the bytes, so it compares
// them. A probe that answers cannot substitute for that - it reports
// which names are registered and nothing about the command, the
// arguments or the environment behind them.
if (!hasMcpServers(toml, codexMcpServers(expectedPayload(env)))) {
return {
target: TARGET,
status: "drift",
details: [
declaresBoth
? `${path}: the OSB tables differ from the canonical payload`
: `${path}: ${undeclared(toml)}`,
],
fix_hint: FIX_HINT,
};
}
if (probeRefutes(probe)) {
const verdict = probeRefutedVerdict({
target: TARGET,
label: LABEL,
artifactMatches: true,
});
return {
target: TARGET,
status: verdict.status,
details: [`${path}: matches the canonical payload, but ${handshakeNote(probe)}`],
fix_hint: verdict.fixHint,
};
}
return {
target: TARGET,
status: "ok",
details: [`${path}: both OSB tables match the canonical payload (${handshakeNote(probe)})`],
fix_hint: null,
};
},
/**
* Where this runtime keeps session logs, from the one declaration.
* `Codex has moved its rollout files between four subdirectories of $CODEX_HOME across releases; all four are declared.`
*/
sessionPaths(env: InstallEnv): SessionPathsResult | null {
return sessionPathsFor(TARGET, env);
},
};
defaultRegistry.register(codexAdapter);