Files
reverse-engineering-anything/src/application/SupportedClients.ts
T

2200 lines
74 KiB
TypeScript

import type {
ClientRegistrationConnectionProfile,
ClientRegistrationProfile,
NativeStdioIncompatibility,
} from "./ClientRegistrationProfile.js";
import type {
ClientConfigurationFormat,
ClientInlineConfiguration,
} from "./ClientConfigurationDocument.js";
import { dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
import { fileURLToPath } from "node:url";
import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
import { err, ok, type Result } from "../domain/result.js";
import {
HermesClientPathError,
resolveHermesClientHome,
} from "./HermesClientHome.js";
import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
import {
absoluteCallerPath,
appendCallerPath,
} from "../filesystem/callerPath.js";
import {
absoluteClientRoot,
clientPathDependence,
absoluteXdgConfigHome,
type ClientRootFailure,
mcporterExpandHome,
mcporterXdgConfigHome,
vscodeUserDirectory,
xdgConfigHomeOrDefault,
} from "./ClientConfigRoots.js";
import { resolveWindowsClaudeDesktopLocation } from "./ClaudeDesktopConfigLocation.js";
import { resolveClineCliSettingsPath } from "./ClineCliLocation.js";
import type { JunieLocationSettings } from "./JunieClientSettings.js";
import { ConfigurationError } from "../domain/configurationErrors.js";
import {
kiloDefaultLocation,
kiloGlobalLocation,
type KiloLocationContext,
} from "./KiloClientLocation.js";
import {
type MsixPackageView,
windowsAppDataRoots,
} from "./MsixPackageStorage.js";
import { kiloProjectLocation } from "./McpRegistrationKiloLocations.js";
import type {
McpRegistrationLocation,
McpRegistrationLocationContext,
} from "./McpRegistrationLocations.js";
import { errorMessage } from "../kernel/errorMessage.js";
/** One supported client configuration location. */
export interface SetupClient {
readonly name: string;
readonly registrationProfile: ClientRegistrationProfile;
readonly displayName?: string;
readonly configPath: string;
/** User configuration files in increasing precedence, including the write target. */
readonly configPaths?: readonly string[];
/** Read-only configuration the client merges over every file layer. */
readonly inlineConfiguration?: ClientInlineConfiguration;
/** Read-only Gemini scopes and trust inputs; never setup write targets. */
readonly geminiSettings?: {
readonly systemPath: string;
readonly defaultsPath: string;
readonly workspaceDirectory: string;
readonly trustedFoldersPath: string;
readonly trustOverride?: boolean;
readonly platform: NodeJS.Platform;
};
/** Inputs deciding whether Junie loads its default user MCP location. */
readonly junieSettings?: JunieLocationSettings;
/** Unresolved path evidence only; consumers must not perform I/O on it. */
readonly configPathError?: string;
/** The access failure behind `configPathError`, when one was observed. */
readonly configPathFailure?: ConfigurationError;
/** Same-scope fallback ZCode stops loading after its first native server. */
readonly zcodeFallbackPath?: string;
readonly markerPath?: string;
/**
* Registration storage shared with other products. Its presence never proves
* this product is installed; only a recognizable REA-owned row in it proves
* ownership of a registration REA wrote.
*/
readonly sharedRegistration?: boolean;
/**
* Only a registration REA wrote makes this client applicable: setup never
* detects it, and doctor reports it only when its file holds a `rea` row.
*/
readonly registrationApplicability?: true;
/**
* The configuration is a private profile: folder 0700, file 0600. `home` is
* the caller's home folder, which that folder mode must never reach.
*/
readonly privateProfile?: { readonly home: string };
/**
* Layers before `configPath` belong to the system or an administrator: REA
* reads them for the effective registration but changes only `configPath`.
*/
readonly readOnlyLowerLayers?: true;
/** MSIX package storage that decides which configuration the client reads. */
readonly msixPackage?: MsixPackageView;
/** A running client can rewrite its configuration from memory. */
readonly quitBeforeSetup?: boolean;
/** Product-specific applicability evidence when configuration storage is shared. */
readonly discoveryPaths?: readonly string[];
readonly format?:
| "json"
| "claude_code"
| "toml"
| "vscode"
| "copilot_cli"
| "opencode"
| "commandcode"
| "grok"
| "omp"
| "pi"
| "kimi"
| "lm_studio"
| "hermes"
| "zcode_fallback"
| "zcode"
| "dsh"
| "zed"
| "amp"
| "fx"
| "goose"
| "kilo"
| "unsupported";
}
interface ClientPathFailure extends ClientRootFailure {
readonly msixPackage?: MsixPackageView;
/** The access failure that left the path unresolved, with its cause. */
readonly failure?: ConfigurationError;
}
type ClientPathResult = Result<string, ClientPathFailure>;
type ClientPath =
| readonly string[]
| ((paths: ClientPathContext) => string | ClientPathResult);
interface ClientPathContext {
readonly home: string;
readonly platform: NodeJS.Platform;
readonly env: Readonly<NodeJS.ProcessEnv>;
readonly systemPaths?: ClientSystemPaths;
}
/**
* Fixed system-wide files a client reads that no environment variable moves.
* Omitted entries use the client's native location; a caller supplies one only
* to isolate the host's real file.
*/
export interface ClientSystemPaths {
readonly gooseSystemConfig?: string;
}
/**
* A user-scope location decided by which configuration layers exist, which
* only an asynchronous probe can observe.
*/
interface ClientLayeredLocation {
readonly configPath: string;
/** Every file layer in load order, including `configPath`. */
readonly configPaths: readonly string[];
readonly inlineConfiguration?: ClientInlineConfiguration;
}
/** One resolved configuration location and its detection evidence. */
interface ClientLocation {
readonly configPath: string;
readonly markerPath: string;
readonly msixPackage?: MsixPackageView;
}
type ClientDefinition = ClientDefinitionBase & ClientDefinitionLocation;
type ClientDefinitionLocation =
| {
readonly configPath: ClientPath;
readonly markerPath: ClientPath;
readonly location?: undefined;
}
| {
/** Resolve configuration and marker together when they share probes. */
readonly location: (
context: ClientPathContext,
) => Result<ClientLocation, ClientPathFailure>;
readonly configPath?: undefined;
readonly markerPath?: undefined;
};
/**
* How `rea mcp add` selects this client beyond its user-scope registration.
* The registration itself uses this row's location, format, profile and
* read-scope facts, so both commands share one definition.
*/
type McpAddExposure = {
/** add-mcp agent aliases that select this client. */
readonly aliases?: readonly string[];
/** Dialect of the project document when it differs from the user one. */
readonly projectFormat?: ClientConfigurationFormat;
} & (
| {
/** Project documents in native precedence; absent means global-only. */
readonly projectPaths?: readonly [string, ...string[]];
readonly projectLocation?: undefined;
}
| {
/** A project location only an asynchronous probe can decide. */
readonly projectLocation: (
context: McpRegistrationLocationContext,
) => Promise<McpRegistrationLocation>;
readonly projectPaths?: undefined;
}
);
interface ClientDefinitionBase {
readonly name: string;
readonly registrationProfile: ClientRegistrationProfile;
readonly displayName: string;
readonly mcpAdd?: McpAddExposure;
readonly discoveryPaths?: (context: ClientPathContext) => readonly string[];
readonly sharedRegistration?: true;
readonly registrationApplicability?: true;
readonly privateProfile?: true;
readonly readOnlyLowerLayers?: true;
readonly format: NonNullable<SetupClient["format"]>;
readonly quitBeforeSetup?: boolean;
readonly zcodeFallbackPath?: (context: ClientPathContext) => string;
readonly skillPath?: ClientPath;
readonly configPaths?: (context: ClientPathContext) => readonly string[];
readonly geminiSettings?: (
context: ClientPathContext,
) => NonNullable<SetupClient["geminiSettings"]>;
/** Junie's location inputs, from the context and its resolved home. */
readonly junieSettings?: (
context: ClientPathContext,
location: ClientLocation,
) => JunieLocationSettings;
/**
* The write target and layers once present layers are observed.
* `resolveSupportedClients` applies it; the synchronous row keeps the
* default target and every candidate layer.
*/
readonly layeredLocation?: (
context: ClientPathContext,
) => Promise<Result<ClientLayeredLocation, ClientPathFailure>>;
}
const traeUserDirectory = ({
home,
platform,
env,
}: ClientPathContext): string => {
if (platform === "win32")
return join(windowsAppDataRoots(home, env).roaming, "Trae", "User");
if (platform === "darwin")
return join(home, "Library", "Application Support", "Trae", "User");
return join(xdgConfigHomeOrDefault({ home, env }), "Trae", "User");
};
/** Windows packaging decides which file Claude Desktop reads; see its resolver. */
const claudeDesktopLocation = (
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
if (context.platform === "win32")
return resolveWindowsClaudeDesktopLocation(context.home, context.env);
const directory =
context.platform === "linux"
? join(xdgConfigHomeOrDefault(context), "Claude")
: join(context.home, "Library", "Application Support", "Claude");
return ok({
configPath: join(directory, "claude_desktop_config.json"),
markerPath: directory,
});
};
const claudeCodeConfigDirectory = ({ home, env }: ClientPathContext): string =>
env.CLAUDE_CONFIG_DIR || home;
const claudeCodeMarkerDirectory = ({ home, env }: ClientPathContext): string =>
env.CLAUDE_CONFIG_DIR || join(home, ".claude");
const codexDirectory = ({ home, env }: ClientPathContext): string =>
env.CODEX_HOME || join(home, ".codex");
/** Kimi Code stores MCP declarations beside the rest of its home data. */
const kimiDirectory = ({ home, env }: ClientPathContext): string =>
env.KIMI_CODE_HOME || join(home, ".kimi-code");
/**
* LM Studio's findLMStudioHome, read-only: a home pointer file wins, then an
* existing ~/.cache/lm-studio, then ~/.lmstudio. Setup never writes the pointer.
*/
const lmStudioLocation = ({
home,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const pointerPath = join(home, ".lmstudio-home-pointer");
let directory: string;
try {
directory = readFileSync(pointerPath, "utf8").trim();
} catch (cause: unknown) {
if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
return err({
path: pointerPath,
message: `${pointerPath} could not be read, so REA cannot establish which LM Studio home holds mcp.json: ${errorMessage(cause)}. Repair access to that file, then rerun.`,
});
const cache = join(home, ".cache", "lm-studio");
directory = existsSync(cache) ? cache : join(home, ".lmstudio");
}
if (!isAbsolute(directory))
return err({
path: pointerPath,
message: `${pointerPath} does not hold an absolute LM Studio home path. Correct or remove that file, then rerun.`,
});
return ok({ configPath: join(directory, "mcp.json"), markerPath: directory });
};
const qoderDirectory = ({ home, env }: ClientPathContext): string =>
env.QODER_CONFIG_DIR || join(home, ".qoder");
/** Droid's override selects the home containing .factory, including personal skills. */
const factoryDirectory = ({ home, env }: ClientPathContext): string =>
join(env.FACTORY_HOME_OVERRIDE || home, ".factory");
/** Match Qwen Code's home override, including tilde and cwd-relative paths. */
const qwenCodeDirectory = ({ home, env }: ClientPathContext): string => {
const override = env.QWEN_HOME;
if (!override) return join(home, ".qwen");
const expanded =
override === "~"
? home
: override.startsWith("~/") || override.startsWith("~\\")
? join(
home,
...override
.slice(2)
.split(/[/\\]+/)
.filter(Boolean),
)
: override;
return isAbsolute(expanded) ? expanded : resolve(expanded);
};
const grokDirectory = ({ home, env }: ClientPathContext): string =>
env.GROK_HOME || join(home, ".grok");
/** Match Harness home-paths for both independent roots; trim only to detect blanks. */
const dshDirectory = (
home: string,
override: string | undefined,
fallback: string,
): string => {
const selected =
override !== undefined && override.trim().length > 0
? override
: join(home, fallback);
const expanded =
selected === "~"
? home
: selected.startsWith("~/") || selected.startsWith("~\\")
? join(home, selected.slice(2))
: selected;
return resolve(expanded);
};
const dshHomeDirectory = ({ home, env }: ClientPathContext): string =>
dshDirectory(home, env.DSH_HOME, ".dsh");
const dshPatchDirectory = (context: ClientPathContext): string =>
join(dshHomeDirectory(context), "cordis.patch.yml");
const hermesDirectory = ({ home, platform, env }: ClientPathContext): string =>
resolveHermesClientHome(home, platform, env);
/** Grok Bot uses an absolute SAND_DATA_ROOT; anything else stays ~/.grokbot. */
const grokBotDirectory = ({ home, env }: ClientPathContext): string => {
const root = env.SAND_DATA_ROOT;
return root !== undefined && root !== "" && isAbsolute(root)
? root
: join(home, ".grokbot");
};
/**
* Grok Bot stores connectors in the signed-in account and runs them on its
* hosted computer. The data directory is only a detection marker.
*/
export const GROK_BOT_MANUAL_REGISTRATION_REMEDIATION =
"Grok Bot keeps connectors in the signed-in account and runs them on its hosted computer. Setup does not write that account store, and a data-directory mcp.json is not a registration. In the Grok Bot chat, add a custom MCP server named rea that runs on the Bot's computer with `npx -y rea-agents@<version> mcp`. Do not put credentials in the command or arguments. A stdio server on this machine is not attached.";
/** Remediation for a client whose connector is not a local configuration file. */
export const manualRegistrationRemediation = (
clientName: string,
): string | undefined =>
clientName === "grok_bot"
? GROK_BOT_MANUAL_REGISTRATION_REMEDIATION
: undefined;
/**
* Facts a setup plan must disclose so an approved registration persists:
* which file an MSIX package reads, and that a running client can overwrite it.
*/
export const registrationPersistenceDetail = (
client: SetupClient,
): string | undefined => {
const name = client.displayName ?? client.name;
const msix = client.msixPackage;
const packageDetail =
msix === undefined
? undefined
: client.configPath === msix.privateConfigPath
? `${name} is installed as MSIX package ${msix.packageFamilyName}, which reads this package-private file instead of ${msix.appDataConfigPath}.`
: `${name} is installed as MSIX package ${msix.packageFamilyName}, which reads this file until it saves its own copy at ${msix.privateConfigPath}.`;
const quitDetail =
client.quitBeforeSetup === true
? `Quit ${name} fully before approving; closing its window is not enough. A running ${name} can rewrite this file from memory and drop the registration. Start it again after setup.`
: undefined;
const details = [packageDetail, quitDetail].filter(
(detail): detail is string => detail !== undefined,
);
return details.length === 0 ? undefined : details.join(" ");
};
/**
* What a direct registration (no approval step) must tell the caller after it
* wrote a client that can rewrite its configuration from memory.
*/
export const runningClientRewriteNotice = (
client: Pick<SetupClient, "name" | "displayName" | "quitBeforeSetup">,
): string | undefined => {
if (client.quitBeforeSetup !== true) return undefined;
const name = client.displayName ?? client.name;
return `A running ${name} can rewrite its configuration from memory and drop the registration. If ${name} was running, quit it fully (closing its window is not enough), rerun rea mcp add, then start ${name} again.`;
};
/**
* Why this process must not change an MSIX client's configuration. A process
* the running app started sees its redirected AppData, and the app would
* overwrite the change from memory; an unknown view cannot rule that out.
*/
export const registrationWriteBlocker = (
client: SetupClient,
operation: "setup" | "uninstall" | "mcp add",
): string | undefined => {
const msix = client.msixPackage;
if (msix === undefined || msix.processView === "direct") return undefined;
const name = client.displayName ?? client.name;
if (msix.processView === "redirected")
return `This process was started from ${name}'s MSIX package ${msix.packageFamilyName}: its AppData is redirected into that package, so ${name} is running and would overwrite ${msix.privateConfigPath} from memory. Quit ${name} fully, then rerun ${operation} from a terminal that ${name} did not start.`;
// Registration writes the configuration the app reads; uninstall cleans both files.
const manualEdit =
operation !== "uninstall"
? `Add REA's entry to ${client.configPath} by hand`
: `Remove REA's entry by hand from each of ${msix.privateConfigPath} and ${msix.appDataConfigPath} that has one`;
return `REA cannot tell whether ${name}'s MSIX package ${msix.packageFamilyName} started this process, because no private file under ${dirname(dirname(msix.privateConfigPath))} could be compared with ${dirname(dirname(msix.appDataConfigPath))}, and a ${name} that started it would overwrite the change from memory. ${manualEdit} while ${name} is fully quit, or rerun ${operation} from a terminal that ${name} did not start once REA can compare a private file there.`;
};
/** The MSIX package view, if any, that redirects this process's AppData writes. */
export const appDataRedirection = (
clients: readonly SetupClient[],
): MsixPackageView | undefined =>
clients.find(({ msixPackage }) => msixPackage?.processView === "redirected")
?.msixPackage;
const OMP_PROFILE_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
const OMP_RESERVED_PROFILE =
/^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/iu;
/**
* The OMP agent directory whose `mcp.json` holds user-scope MCP servers. OMP
* joins PI_CONFIG_DIR to the home directory, and a named profile ignores
* PI_CODING_AGENT_DIR. Relative overrides use the setup process working directory.
*/
const ompAgentDirectory = (context: ClientPathContext): ClientPathResult => {
const root = join(context.home, context.env.PI_CONFIG_DIR || ".omp");
// OMP_PROFILE wins even when empty. Match OMP's validation on every host.
const profile = (context.env.OMP_PROFILE ?? context.env.PI_PROFILE)?.trim();
if (profile !== undefined && profile !== "" && profile !== "default") {
if (
!OMP_PROFILE_NAME.test(profile) ||
profile.endsWith(".") ||
OMP_RESERVED_PROFILE.test(profile)
)
return err({
path: root,
message: `Invalid OMP profile ${JSON.stringify(profile)}: names must match ^[a-z0-9][a-z0-9._-]{0,63}$, cannot end with ".", and cannot be a Windows reserved device name (CON, PRN, AUX, NUL, COM0-9, LPT0-9, including extensions). Repair OMP_PROFILE or PI_PROFILE before configuring OMP.`,
});
return ok(join(root, "profiles", profile, "agent"));
}
const override = context.env.PI_CODING_AGENT_DIR;
return ok(override ? resolve(override) : join(root, "agent"));
};
/**
* Pi's public getAgentDir()/normalizePath semantics, not OMP's profiles.
* Keep relative overrides relative: filesystem consumers resolve them in cwd.
*/
const piAgentDirectory = ({
home,
platform,
env,
}: ClientPathContext): string => {
const paths = platform === "win32" ? win32 : { join };
let directory = env.PI_CODING_AGENT_DIR;
if (!directory) return paths.join(home, ".pi", "agent");
if (
platform === "win32" &&
directory.startsWith("/") &&
!directory.startsWith("//") &&
!directory.includes("\\")
) {
const drive = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/iu.exec(
directory,
);
if (drive !== null)
directory = `${drive[1]?.toUpperCase()}:\\${drive[2]?.replaceAll("/", "\\") ?? ""}`;
}
if (directory === "~") return home;
if (
directory.startsWith("~/") ||
(platform === "win32" && directory.startsWith("~\\"))
)
return paths.join(home, directory.slice(2));
if (directory.startsWith("file://"))
return fileURLToPath(directory, { windows: platform === "win32" });
return directory;
};
const copilotDirectory = ({ home, env }: ClientPathContext): string =>
env.COPILOT_HOME || join(home, ".copilot");
const commandCodeDirectory = ({ home }: ClientPathContext): string =>
join(home, ".commandcode");
/**
* OpenCode appends `OPENCODE_CONFIG_DIR` only when the value is non-empty.
* An empty variable is the same as unset and leaves the XDG directory in place.
*/
const openCodeOverrideDirectory = (
env: ClientPathContext["env"],
): string | undefined => {
const directory = env.OPENCODE_CONFIG_DIR;
return directory === undefined || directory === "" ? undefined : directory;
};
const opencodeDirectory = (context: ClientPathContext): string =>
openCodeOverrideDirectory(context.env) ??
join(xdgConfigHomeOrDefault(context), "opencode");
/** OpenCode loads global JSON before JSONC, then explicit file and directory overrides. */
const openCodeConfigurationPaths = (
context: ClientPathContext,
): readonly string[] => {
const directory = join(xdgConfigHomeOrDefault(context), "opencode");
const overrideDirectory = openCodeOverrideDirectory(context.env);
const paths = [
join(directory, "config.json"),
join(directory, "opencode.json"),
join(directory, "opencode.jsonc"),
...(context.env.OPENCODE_CONFIG ? [context.env.OPENCODE_CONFIG] : []),
...(overrideDirectory !== undefined
? [
join(overrideDirectory, "opencode.json"),
join(overrideDirectory, "opencode.jsonc"),
]
: []),
];
const resolved = paths.map((path) => resolve(path));
return resolved.filter((path, index) => resolved.lastIndexOf(path) === index);
};
const existingOpenCodeConfigPath = (context: ClientPathContext): string => {
// The selected directory is loaded after an explicit file by OpenCode V1.
const overrideDirectory = openCodeOverrideDirectory(context.env);
const candidates =
overrideDirectory !== undefined
? [
join(overrideDirectory, "opencode.json"),
join(overrideDirectory, "opencode.jsonc"),
].map((path) => resolve(path))
: context.env.OPENCODE_CONFIG
? [resolve(context.env.OPENCODE_CONFIG)]
: [
join(opencodeDirectory(context), "opencode.json"),
join(opencodeDirectory(context), "opencode.jsonc"),
].map((path) => resolve(path));
return (
[...candidates].reverse().find((path) => {
try {
lstatSync(path);
return true;
} catch (cause: unknown) {
return !(
cause instanceof Error &&
"code" in cause &&
cause.code === "ENOENT"
);
}
}) ??
resolve(
overrideDirectory !== undefined
? join(overrideDirectory, "opencode.json")
: context.env.OPENCODE_CONFIG ||
join(opencodeDirectory(context), "opencode.json"),
)
);
};
const geminiSettings = ({
home,
platform,
env,
}: ClientPathContext): NonNullable<SetupClient["geminiSettings"]> => {
const system =
env.GEMINI_CLI_SYSTEM_SETTINGS_PATH ||
(platform === "darwin"
? "/Library/Application Support/GeminiCli/settings.json"
: platform === "win32"
? "C:\\ProgramData\\gemini-cli\\settings.json"
: "/etc/gemini-cli/settings.json");
const trustOverride =
env.GEMINI_RESTRICTED_MODE === "true" ||
env.GEMINI_CLI_TRUST_WORKSPACE === "false"
? false
: env.GEMINI_CLI_TRUST_WORKSPACE === "true"
? true
: undefined;
return {
systemPath: system,
defaultsPath:
env.GEMINI_CLI_SYSTEM_DEFAULTS_PATH ||
join(dirname(system), "system-defaults.json"),
workspaceDirectory: process.cwd(),
trustedFoldersPath:
env.GEMINI_CLI_TRUSTED_FOLDERS_PATH ||
join(env.GEMINI_CLI_HOME || home, ".gemini", "trustedFolders.json"),
...(trustOverride === undefined ? {} : { trustOverride }),
platform,
};
};
const devinDirectory = ({ home, platform, env }: ClientPathContext): string =>
platform === "win32"
? join(windowsAppDataRoots(home, env).roaming, "devin")
: join(xdgConfigHomeOrDefault({ home, env }), "devin");
/** The Cline extension's settings in one editor's global storage. */
const clineSettingsDirectory =
(dataFolder: string) =>
(context: ClientPathContext): string =>
join(
vscodeUserDirectory(context, dataFolder),
"globalStorage",
"saoudrizwan.claude-dev",
"settings",
);
const clineVscodeSettingsDirectory = clineSettingsDirectory("Code");
/** Flathub's Zed (`dev.zed.Zed`) gets this XDG_CONFIG_HOME inside its sandbox. */
const ZED_FLATPAK_CONFIG = [".var", "app", "dev.zed.Zed", "config"] as const;
const directoryPresent = (path: string): Result<boolean, ClientPathFailure> => {
try {
lstatSync(path);
return ok(true);
} catch (cause: unknown) {
if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
return ok(false);
return err({
path,
message: `Cannot determine whether ${path} exists: ${errorMessage(cause)}. Repair its access before configuring Zed.`,
});
}
};
/** Whether two existing paths resolve to the same folder, by device and inode. */
const sameDirectory = (
first: string,
second: string,
): Result<boolean, ClientPathFailure> => {
const identities: { dev: bigint; ino: bigint }[] = [];
for (const path of [first, second]) {
try {
const { dev, ino } = statSync(path, { bigint: true });
identities.push({ dev, ino });
} catch (cause: unknown) {
return err({
path,
message: `Cannot resolve ${path}: ${errorMessage(cause)}. Repair it before configuring Zed.`,
});
}
}
const [a, b] = identities;
return ok(
a !== undefined && b !== undefined && a.dev === b.dev && a.ino === b.ino,
);
};
/**
* Zed's `paths::config_dir`. On Windows it reads the RoamingAppData known
* folder, which APPDATA normally names. On Linux and FreeBSD,
* `FLATPAK_XDG_CONFIG_HOME` wins, then `dirs::config_dir`, which admits only an
* absolute XDG_CONFIG_HOME. A Flathub Zed reads its sandbox's config folder,
* so REA uses it when only that folder exists and refuses to guess when a
* native configuration exists too.
*/
const zedLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const at = (directory: string): ClientLocation => ({
configPath: join(directory, "settings.json"),
markerPath: directory,
});
if (platform === "darwin") return ok(at(join(home, ".config", "zed")));
if (platform === "win32")
return ok(at(join(windowsAppDataRoots(home, env).roaming, "Zed")));
const flatpakOverride = env.FLATPAK_XDG_CONFIG_HOME;
if (flatpakOverride) {
const selected = absoluteClientRoot(
flatpakOverride,
"FLATPAK_XDG_CONFIG_HOME",
"Zed",
platform,
);
return selected.ok ? ok(at(join(selected.value, "zed"))) : selected;
}
const native = join(absoluteXdgConfigHome({ home, env }), "zed");
const sandboxed = join(home, ...ZED_FLATPAK_CONFIG, "zed");
const flatpak = directoryPresent(sandboxed);
if (!flatpak.ok) return flatpak;
if (!flatpak.value) return ok(at(native));
const nativePresent = directoryPresent(native);
if (!nativePresent.ok) return nativePresent;
if (!nativePresent.value) return ok(at(sandboxed));
// XDG_CONFIG_HOME or a link may make both names one folder.
const same = sameDirectory(native, sandboxed);
if (!same.ok) return same;
return same.value
? ok(at(native))
: err({
path: sandboxed,
message: `Both ${native} and the Flatpak Zed folder ${sandboxed} exist, so REA cannot tell which Zed you use. Remove the configuration of the Zed you no longer use, then configure Zed again.`,
});
};
const regularPathPresent = (
path: string,
): Result<boolean, ClientPathFailure> => {
try {
lstatSync(path);
return ok(true);
} catch (cause: unknown) {
if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
return ok(false);
return err({
path,
message: `Cannot determine whether ${path} exists: ${errorMessage(cause)}. Repair its access before configuring MCPorter.`,
});
}
};
/**
* MCPorter's home layer (`listConfigLayerPaths`): a non-empty
* `MCPORTER_CONFIG` is the only file it loads; otherwise the first existing of
* the XDG and legacy `~/.mcporter` candidates (`mcporterConfigCandidates`),
* where only an absolute `XDG_CONFIG_HOME` counts. A new file goes where
* `mcporter config add --scope home` puts it. A relative `MCPORTER_CONFIG`
* follows each invocation's directory, which REA cannot know.
*/
const mcporterLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const pathApi = platform === "win32" ? win32 : posix;
const legacy = join(home, ".mcporter");
const selected = env.MCPORTER_CONFIG?.trim();
if (selected) {
const path = mcporterExpandHome(selected, home);
// MCPorter applies path.resolve: `..` collapses lexically, not through
// links. The selected file is also the evidence that MCPorter is in use.
const absolute = absoluteClientRoot(
path,
"MCPORTER_CONFIG",
"MCPorter",
platform,
);
return absolute.ok
? ok({
configPath: pathApi.resolve(absolute.value),
markerPath: pathApi.resolve(absolute.value),
})
: absolute;
}
const configHome = mcporterXdgConfigHome({ home, platform, env });
const base = configHome === undefined ? legacy : join(configHome, "mcporter");
const candidates = [base, ...(base === legacy ? [] : [legacy])].flatMap(
(directory) => [
join(directory, "mcporter.json"),
join(directory, "mcporter.jsonc"),
],
);
for (const candidate of candidates) {
const present = regularPathPresent(candidate);
if (!present.ok) return present;
// The loaded file's folder is the evidence, even when it is the legacy one.
if (present.value)
return ok({ configPath: candidate, markerPath: dirname(candidate) });
}
return ok({ configPath: join(base, "mcporter.json"), markerPath: base });
};
/** mcporter getUrl's native nullish priority; an empty first value suppresses later aliases. */
const MCPORTER_URL_FIELDS = [
"baseUrl",
"base_url",
"url",
"serverUrl",
"server_url",
] as const;
const MCPORTER_STDIO_INCOMPATIBILITIES: readonly NativeStdioIncompatibility[] =
[
// RawEntrySchema admits only optional strings, including an empty string.
...MCPORTER_URL_FIELDS.map((field): NativeStdioIncompatibility => ({
kind: "invalid-string",
field,
})),
...MCPORTER_URL_FIELDS.map((field, index): NativeStdioIncompatibility =>
index === 0
? { kind: "truthy", field }
: {
kind: "all",
conditions: [
...MCPORTER_URL_FIELDS.slice(0, index).map(
(prior): NativeStdioIncompatibility => ({
kind: "nullish",
field: prior,
}),
),
{ kind: "truthy", field },
],
},
),
];
/**
* Amp's user settings: `settings.json` or `settings.jsonc` in
* `~/.config/amp` on every platform. Amp does not document which one wins
* when both exist, so that case stays unresolved.
*/
const ampLocation = ({
home,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const directory = join(home, ".config", "amp");
const candidates = ["settings.json", "settings.jsonc"].map((name) =>
join(directory, name),
);
const present: string[] = [];
for (const candidate of candidates) {
try {
lstatSync(candidate);
present.push(candidate);
} catch (cause: unknown) {
if (
!(cause instanceof Error && "code" in cause && cause.code === "ENOENT")
)
return err({
path: candidate,
message: `Cannot determine whether ${candidate} exists: ${errorMessage(cause)}. Repair its access before configuring Amp.`,
});
}
}
if (present.length > 1)
return err({
path: directory,
message: `Both ${candidates[0]} and ${candidates[1]} exist, and Amp does not document which one it reads. Merge them into one file before configuring Amp.`,
});
return ok({
configPath: present[0] ?? join(directory, "settings.json"),
markerPath: directory,
});
};
/**
* fx's profile folder (`useFxHome`): a non-empty `FX_HOME` must be absolute
* and name neither the root nor the home folder, ignoring trailing slashes;
* otherwise `~/.fx`. fx refuses an invalid value, so REA does too.
*/
const fxLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const value = env.FX_HOME;
const pathApi = platform === "win32" ? win32 : posix;
if (!value) {
const directory = join(home, ".fx");
return ok({
configPath: join(directory, "mcp.json"),
markerPath: directory,
});
}
const trimmed = value.replace(/\/+$/u, "");
// fx opens FX_HOME as written, so `.` and `..` resolve through links on the
// filesystem. Refusing them keeps REA's file and its root/home check on the
// folder fx opens, so the private profile mode can never land on home.
const dotSegment = trimmed
.split(/[\\/]/u)
.some((segment) => segment === "." || segment === "..");
if (
!pathApi.isAbsolute(value) ||
trimmed.length === 0 ||
dotSegment ||
pathApi.parse(trimmed).root === trimmed ||
trimmed === home.replace(/[\\/]+$/u, "")
)
return err({
path: value,
message:
"FX_HOME must be an absolute path without . or .. segments, other than the root and home folders. Repair FX_HOME before configuring fx; no settings were written.",
});
return ok({
configPath: pathApi.join(trimmed, "mcp.json"),
markerPath: trimmed,
});
};
/**
* Junie's home: `JUNIE_HOME` for Junie CLI, else `~/.junie`. add-mcp notes the
* JetBrains plugin always reads `~/.junie`. Junie resolves a relative
* `JUNIE_HOME` against its own working directory, so REA refuses one.
*/
const junieLocation = ({
home,
platform,
env,
}: ClientPathContext): Result<ClientLocation, ClientPathFailure> => {
const selected = env.JUNIE_HOME
? absoluteClientRoot(env.JUNIE_HOME, "JUNIE_HOME", "Junie", platform)
: ok(join(home, ".junie"));
return selected.ok
? ok({
configPath: join(selected.value, "mcp", "mcp.json"),
markerPath: selected.value,
})
: selected;
};
/**
* Goose's user configuration (`Paths::config_dir`): an absolute
* `GOOSE_PATH_ROOT` selects `<root>/config`; otherwise etcetera's app strategy,
* where only an absolute `XDG_CONFIG_HOME` counts.
*/
const gooseUserConfigPath = ({ home, platform, env }: ClientPathContext) => {
const pathApi = platform === "win32" ? win32 : posix;
const root = env.GOOSE_PATH_ROOT;
if (root && pathApi.isAbsolute(root))
return pathApi.join(root, "config", "config.yaml");
return platform === "win32"
? join(
windowsAppDataRoots(home, env).roaming,
"Block",
"goose",
"config",
"config.yaml",
)
: join(absoluteXdgConfigHome({ home, env }), "goose", "config.yaml");
};
/**
* `GOOSE_ADDITIONAL_CONFIG_FILES`, split as Rust's `env::split_paths`: `:` on
* Unix; on Windows `;` outside double quotes, which are removed.
*/
const gooseAdditionalConfigFiles = ({
platform,
env,
}: Pick<ClientPathContext, "platform" | "env">): string[] => {
const value = env.GOOSE_ADDITIONAL_CONFIG_FILES ?? "";
if (platform !== "win32")
return value.split(":").filter((path) => path.length > 0);
const paths: string[] = [];
let current = "";
let quoted = false;
for (const character of value) {
if (character === '"') quoted = !quoted;
else if (character === ";" && !quoted) {
paths.push(current);
current = "";
} else current += character;
}
paths.push(current);
return paths.filter((path) => path.length > 0);
};
/**
* Goose's layers in increasing precedence (`Config::default`): the system
* file, each `GOOSE_ADDITIONAL_CONFIG_FILES` entry, then the user file it
* writes. A relative additional entry follows Goose's working directory, and a
* Windows drive-less one its current drive, which REA cannot know.
*/
const gooseLocation = (
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
const configPath = gooseUserConfigPath(context);
for (const path of gooseAdditionalConfigFiles(context)) {
const dependence = clientPathDependence(path, context.platform);
if (dependence === "relative")
return err({
path,
message: `GOOSE_ADDITIONAL_CONFIG_FILES names the relative path ${path}, which Goose resolves against its own working directory. Use absolute paths before configuring Goose.`,
});
if (dependence === "driveless")
return err({
path,
message: `GOOSE_ADDITIONAL_CONFIG_FILES names ${path}, which has no drive, so the file Goose reads depends on its current drive. Use a path with a drive letter or a UNC path before configuring Goose.`,
});
}
return ok({ configPath, markerPath: configPath });
};
/**
* Goose's load order: the system file, each additional file, then the user
* file it writes. An additional entry can name the user file too; Goose then
* loads it twice, and its last load decides precedence.
*/
const gooseConfigPaths = (context: ClientPathContext) => [
context.systemPaths?.gooseSystemConfig ??
(context.platform === "win32"
? win32.join(
context.env.PROGRAMDATA || "C:\\ProgramData",
"goose",
"config.yaml",
)
: "/etc/goose/config.yaml"),
...gooseAdditionalConfigFiles(context),
gooseUserConfigPath(context),
];
/**
* FreeBuff's own profile directory (its `state.json` root, fixed under
* `.config` on every platform). The shared `~/.agents` folder is not
* FreeBuff-specific: REA's own skill installs create it, so it cannot
* prove FreeBuff is installed.
*/
const freebuffProfileDirectory = ({ home }: ClientPathContext): string =>
join(home, ".config", "freebuff-desktop");
type ClientDefinitionInput = Omit<ClientDefinitionBase, "registrationProfile"> &
ClientDefinitionLocation & {
readonly registrationConnection: ClientRegistrationConnectionProfile;
};
/** Bind native identity once while retaining the original definition's literal name. */
/**
* Kilo resolves its configured paths against its own working directory, which
* setup cannot know, so the table accepts only absolute ones.
*/
const kiloTableContext = (context: ClientPathContext): KiloLocationContext => ({
root: context,
path: (path) => {
// Normalized as rea mcp add normalizes it, so joined layer paths compare.
const dependence = clientPathDependence(path, context.platform);
if (dependence === undefined)
return absoluteCallerPath(path, { platform: context.platform });
throw new KiloPathDependenceError(path, dependence);
},
});
class KiloPathDependenceError extends Error {
constructor(
readonly path: string,
dependence: "relative" | "driveless",
) {
super(
dependence === "relative"
? `Kilo's configuration path ${path} is relative, so the file Kilo reads depends on its working directory. Set an absolute path before configuring Kilo.`
: `Kilo's configuration path ${path} has no drive, so the file Kilo reads depends on its current drive. Set a path with a drive letter or a UNC path before configuring Kilo.`,
);
}
}
const kiloPathFailure = (cause: unknown): ClientPathFailure => {
if (cause instanceof KiloPathDependenceError)
return { path: cause.path, message: cause.message };
throw cause;
};
const kiloLocation = (
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
try {
const { configPath, markerPath } = kiloDefaultLocation(
kiloTableContext(context),
);
return ok({ configPath, markerPath });
} catch (cause: unknown) {
return err(kiloPathFailure(cause));
}
};
const kiloLayeredLocation = async (
context: ClientPathContext,
): Promise<Result<ClientLayeredLocation, ClientPathFailure>> => {
const kilo = kiloTableContext(context);
try {
const { configPath, configPaths, inlineConfiguration } =
await kiloGlobalLocation(kilo);
return ok({
configPath,
configPaths,
...(inlineConfiguration === undefined ? {} : { inlineConfiguration }),
});
} catch (cause: unknown) {
if (cause instanceof ConfigurationError)
return err({
path: kiloDefaultLocation(kilo).markerPath,
message: cause.message,
failure: cause,
});
return err(kiloPathFailure(cause));
}
};
/** Candidate layers when relative paths leave the location unresolved. */
const kiloCandidatePaths = (context: ClientPathContext): readonly string[] => {
try {
return kiloDefaultLocation(kiloTableContext(context)).configPaths;
} catch (cause: unknown) {
kiloPathFailure(cause);
return [];
}
};
const kiloDiscoveryPaths = (context: ClientPathContext): readonly string[] => {
try {
return kiloDefaultLocation(kiloTableContext(context)).discoveryPaths;
} catch (cause: unknown) {
kiloPathFailure(cause);
return [];
}
};
const defineClient = <const Definition extends ClientDefinitionInput>(
definition: Definition,
) => {
const { registrationConnection, ...metadata } = definition;
return {
...metadata,
registrationProfile: {
nativeClient: definition.name,
connection: registrationConnection,
},
};
};
/** Stable product metadata used to derive setup discovery and documentation. */
export const SUPPORTED_CLIENT_DEFINITIONS = [
defineClient({
name: "claude_code",
mcpAdd: { projectPaths: [".mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Claude Code",
skillPath: (context: ClientPathContext) =>
join(claudeCodeMarkerDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
join(claudeCodeConfigDirectory(context), ".claude.json"),
markerPath: claudeCodeMarkerDirectory,
format: "claude_code",
}),
defineClient({
name: "claude_desktop",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["type"],
stdio: [{ kind: "optional-enum", field: "type", values: ["stdio"] }],
},
displayName: "Claude Desktop",
location: claudeDesktopLocation,
quitBeforeSetup: true,
format: "json",
}),
defineClient({
name: "codex",
mcpAdd: { projectPaths: [".codex/config.toml"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "non-nullish", field: "url" }],
},
displayName: "Codex",
configPath: (context: ClientPathContext) =>
appendCallerPath(codexDirectory(context), "config.toml"),
markerPath: codexDirectory,
format: "toml",
}),
defineClient({
name: "cursor",
mcpAdd: { projectPaths: [".cursor/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Cursor",
configPath: [".cursor", "mcp.json"],
markerPath: [".cursor"],
format: "json",
}),
defineClient({
name: "codebuddy",
registrationConnection: {
kind: "stdio-only",
documentedFields: ["env", "type"],
},
displayName: "CodeBuddy",
skillPath: [".codebuddy", "skills"],
configPath: [".codebuddy", "mcp.json"],
markerPath: [".codebuddy"],
format: "json",
}),
defineClient({
// Cline discovers the shared ~/.agents/skills directory. Keep REA's
// existing shared destination instead of managing another skill copy.
name: "cline",
mcpAdd: {},
registrationConnection: { kind: "cline" },
displayName: "Cline CLI",
location: ({ home, env, platform }: ClientPathContext) => {
const selected = resolveClineCliSettingsPath({
home,
platform,
environment: env,
});
const pathApi = platform === "win32" ? win32 : posix;
return selected.ok
? ok({
configPath: selected.value,
markerPath: pathApi.dirname(selected.value),
})
: selected;
},
format: "json",
}),
defineClient({
name: "gemini_cli",
mcpAdd: { aliases: ["gemini"], projectPaths: [".gemini/settings.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url", "httpUrl"],
stdio: [
{ kind: "truthy", field: "httpUrl" },
{ kind: "truthy", field: "url" },
],
},
displayName: "Gemini CLI",
geminiSettings,
configPath: ({ home, env }: ClientPathContext) =>
join(env.GEMINI_CLI_HOME || home, ".gemini", "settings.json"),
markerPath: ({ home, env }: ClientPathContext) =>
join(env.GEMINI_CLI_HOME || home, ".gemini"),
// Antigravity keeps its configuration under the same .gemini directory,
// so the directory alone does not show Gemini CLI. Its own settings,
// trusted-folder records and session state do.
discoveryPaths: (context: ClientPathContext) => {
const root = join(context.env.GEMINI_CLI_HOME || context.home, ".gemini");
return [
join(root, "settings.json"),
geminiSettings(context).trustedFoldersPath,
join(root, "tmp"),
];
},
skillPath: ({ home, env }: ClientPathContext) =>
join(env.GEMINI_CLI_HOME || home, ".agents", "skills"),
format: "json",
}),
defineClient({
name: "windsurf",
mcpAdd: { aliases: ["codeium", "cascade"] },
registrationConnection: {
kind: "flat",
fields: ["serverUrl", "url"],
stdio: [
{ kind: "present", field: "serverUrl" },
{ kind: "present", field: "url" },
],
},
displayName: "Windsurf",
configPath: [".codeium", "windsurf", "mcp_config.json"],
markerPath: [".codeium", "windsurf"],
format: "json",
}),
defineClient({
name: "devin",
registrationConnection: {
kind: "flat",
fields: ["url", "transport"],
stdio: [
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Devin",
configPath: ({ home, platform, env }: ClientPathContext) =>
join(devinDirectory({ home, platform, env }), "mcp_config.json"),
markerPath: devinDirectory,
format: "json",
}),
defineClient({
name: "opencode",
mcpAdd: {
projectPaths: [
"opencode.jsonc",
"opencode.json",
".opencode/opencode.jsonc",
".opencode/opencode.json",
],
},
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "required-enum", field: "type", values: ["local"] }],
},
displayName: "OpenCode",
configPath: existingOpenCodeConfigPath,
configPaths: openCodeConfigurationPaths,
markerPath: opencodeDirectory,
format: "opencode",
}),
defineClient({
name: "antigravity",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["serverUrl", "url"],
stdio: [
{ kind: "present", field: "serverUrl" },
{ kind: "present", field: "url" },
],
},
displayName: "Antigravity",
skillPath: [".gemini", "config", "skills"],
configPath: [".gemini", "config", "mcp_config.json"],
markerPath: [".gemini", "config"],
format: "json",
}),
defineClient({
name: "copilot_cli",
mcpAdd: {
projectPaths: [".mcp.json", ".github/mcp.json"],
projectFormat: "copilot_cli_project",
},
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio", "local"] },
{ kind: "present", field: "url" },
],
},
displayName: "GitHub Copilot CLI",
configPath: (context: ClientPathContext) =>
join(copilotDirectory(context), "mcp-config.json"),
markerPath: copilotDirectory,
format: "copilot_cli",
}),
defineClient({
name: "commandcode",
registrationConnection: { kind: "commandcode" },
displayName: "Command Code",
configPath: (context: ClientPathContext) =>
join(commandCodeDirectory(context), "mcp.json"),
markerPath: commandCodeDirectory,
format: "commandcode",
}),
defineClient({
name: "qwen_code",
registrationConnection: {
kind: "flat",
fields: ["type", "httpUrl", "url"],
stdio: [
{ kind: "truthy", field: "httpUrl" },
{ kind: "truthy", field: "url" },
{ kind: "equals", field: "type", value: "sdk" },
],
},
displayName: "Qwen Code",
configPath: (context: ClientPathContext) =>
join(qwenCodeDirectory(context), "settings.json"),
markerPath: qwenCodeDirectory,
format: "json",
}),
defineClient({
name: "kimi",
mcpAdd: { aliases: ["kimi"], projectPaths: [".kimi-code/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url", "transport"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Kimi Code",
configPath: (context: ClientPathContext) =>
join(kimiDirectory(context), "mcp.json"),
markerPath: kimiDirectory,
format: "kimi",
}),
defineClient({
name: "vscode",
mcpAdd: { aliases: ["github-copilot"], projectPaths: [".vscode/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url", "transport"],
stdio: [
{ kind: "required-enum", field: "type", values: ["stdio"] },
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "VS Code",
configPath: (context: ClientPathContext) =>
join(vscodeUserDirectory(context), "mcp.json"),
markerPath: vscodeUserDirectory,
format: "vscode",
}),
defineClient({
name: "trae",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Trae",
skillPath: [".trae", "skills"],
configPath: (context: ClientPathContext) =>
join(traeUserDirectory(context), "mcp.json"),
markerPath: traeUserDirectory,
format: "json",
}),
defineClient({
name: "workbuddy",
registrationConnection: { kind: "stdio-only", documentedFields: ["env"] },
displayName: "WorkBuddy",
skillPath: [".workbuddy", "skills"],
configPath: [".workbuddy", "mcp.json"],
markerPath: [".workbuddy"],
format: "json",
}),
defineClient({
name: "lm_studio",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "LM Studio",
location: lmStudioLocation,
format: "lm_studio",
}),
defineClient({
name: "grok_build",
mcpAdd: { aliases: ["grok"], projectPaths: [".grok/config.toml"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "non-nullish", field: "url" }],
},
displayName: "Grok Build",
configPath: (context: ClientPathContext) =>
join(grokDirectory(context), "config.toml"),
markerPath: grokDirectory,
format: "grok",
}),
defineClient({
name: "omp",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "optional-enum", field: "type", values: ["stdio"] }],
},
displayName: "OMP",
configPath: (context: ClientPathContext) => {
const directory = ompAgentDirectory(context);
return directory.ok ? ok(join(directory.value, "mcp.json")) : directory;
},
markerPath: ompAgentDirectory,
format: "omp",
}),
defineClient({
name: "pi",
mcpAdd: { aliases: ["pi-agent"], projectPaths: [".pi/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{
kind: "all",
conditions: [
{ kind: "missing", field: "type" },
{ kind: "string", field: "url" },
],
},
],
},
displayName: "Pi",
configPath: (context: ClientPathContext) =>
(context.platform === "win32" ? win32 : { join }).join(
piAgentDirectory(context),
"mcp.json",
),
markerPath: piAgentDirectory,
format: "pi",
}),
defineClient({
name: "hermes",
mcpAdd: { aliases: ["hermes-agent"] },
registrationConnection: {
kind: "flat",
fields: ["url", "transport"],
stdio: [
{ kind: "optional-enum", field: "transport", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Hermes",
skillPath: (context: ClientPathContext) =>
appendCallerPath(hermesDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
appendCallerPath(hermesDirectory(context), "config.yaml"),
markerPath: hermesDirectory,
format: "hermes",
}),
defineClient({
name: "qoder",
registrationConnection: {
kind: "flat",
fields: ["type", "url", "qoder_url", "tcp"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
{ kind: "present", field: "qoder_url" },
{ kind: "present", field: "tcp" },
],
},
displayName: "Qoder",
skillPath: (context: ClientPathContext) =>
join(qoderDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
join(qoderDirectory(context), "settings.json"),
markerPath: qoderDirectory,
format: "json",
}),
defineClient({
name: "droid",
mcpAdd: {
aliases: ["droid", "factory"],
projectPaths: [".factory/mcp.json"],
},
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "Factory Droid",
skillPath: (context: ClientPathContext) =>
join(factoryDirectory(context), "skills"),
configPath: (context: ClientPathContext) =>
join(factoryDirectory(context), "mcp.json"),
markerPath: factoryDirectory,
format: "json",
}),
defineClient({
name: "zcode",
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
zcodeFallbackPath: ({ home }: ClientPathContext) =>
join(home, ".agents", "mcp.json"),
displayName: "ZCode",
configPath: [".zcode", "cli", "config.json"],
markerPath: [".zcode", "cli"],
skillPath: [".zcode", "skills"],
discoveryPaths: ({ home }: ClientPathContext) => [
join(home, ".zcode", "cli"),
],
format: "zcode",
}),
defineClient({
name: "dsh",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "required-enum", field: "transport", values: ["stdio"] }],
},
displayName: "DeepSeek Harness",
// The home Cordis patch applies to every profile; the skill directory is
// shared agent storage Harness discovers.
skillPath: ({ home, env }: ClientPathContext) =>
join(dshDirectory(home, env.DSH_AGENTS_HOME, ".agents"), "skills"),
configPath: dshPatchDirectory,
markerPath: dshHomeDirectory,
format: "dsh",
}),
defineClient({
name: "freebuff",
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
displayName: "FreeBuff",
// FreeBuff discovers personal skills in the shared user agents directory.
skillPath: ({ home }: ClientPathContext) => join(home, ".agents", "skills"),
// FreeBuff loads MCP servers from the shared user agents directory.
configPath: ({ home }: ClientPathContext) =>
join(home, ".agents", "mcp.json"),
markerPath: freebuffProfileDirectory,
discoveryPaths: (context: ClientPathContext) => [
freebuffProfileDirectory(context),
],
// The same file doubles as ZCode's user-scope fallback, so its presence
// proves neither product is installed; see clientOwnershipEvidencePaths.
sharedRegistration: true,
format: "json",
}),
defineClient({
name: "cline_vscode",
mcpAdd: { aliases: ["cline-vscode"] },
registrationConnection: { kind: "cline" },
displayName: "Cline VS Code extension",
configPath: (context: ClientPathContext) =>
join(clineVscodeSettingsDirectory(context), "cline_mcp_settings.json"),
markerPath: clineVscodeSettingsDirectory,
format: "json",
}),
defineClient({
name: "cline_vscode_insiders",
registrationConnection: { kind: "cline" },
displayName: "Cline in VS Code Insiders",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("Code - Insiders")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("Code - Insiders"),
format: "json",
}),
defineClient({
name: "cline_vscodium",
registrationConnection: { kind: "cline" },
displayName: "Cline in VSCodium",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("VSCodium")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("VSCodium"),
format: "json",
}),
defineClient({
name: "cline_cursor",
registrationConnection: { kind: "cline" },
displayName: "Cline in Cursor",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("Cursor")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("Cursor"),
format: "json",
}),
defineClient({
name: "cline_windsurf",
registrationConnection: { kind: "cline" },
displayName: "Cline in Windsurf",
configPath: (context: ClientPathContext) =>
join(
clineSettingsDirectory("Windsurf")(context),
"cline_mcp_settings.json",
),
markerPath: clineSettingsDirectory("Windsurf"),
format: "json",
}),
defineClient({
name: "kiro",
mcpAdd: { aliases: ["kiro"], projectPaths: [".kiro/settings/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["type", "url"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["stdio"] },
{ kind: "present", field: "url" },
],
},
// The IDE, CLI and web clients share the user file.
displayName: "Kiro",
configPath: [".kiro", "settings", "mcp.json"],
markerPath: [".kiro"],
format: "json",
}),
defineClient({
name: "mastracode",
mcpAdd: { aliases: ["mastra"], projectPaths: [".mastracode/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "string", field: "url" }],
},
displayName: "Mastra Code",
configPath: [".mastracode", "mcp.json"],
markerPath: [".mastracode"],
format: "json",
}),
defineClient({
name: "zed",
mcpAdd: { projectPaths: [".zed/settings.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Zed",
location: zedLocation,
format: "zed",
}),
defineClient({
name: "amp",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Amp",
location: ampLocation,
format: "amp",
}),
defineClient({
name: "mcporter",
mcpAdd: { projectPaths: ["config/mcporter.json"] },
registrationConnection: {
kind: "flat",
fields: [...MCPORTER_URL_FIELDS, "executable"],
stdio: MCPORTER_STDIO_INCOMPATIBILITIES,
},
displayName: "MCPorter",
location: mcporterLocation,
// MCPorter imports setup-managed clients' registrations by default, so a
// registration of its own is opt-in.
registrationApplicability: true,
format: "json",
}),
defineClient({
name: "fx",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["url", "args"],
stdio: [
{ kind: "optional-enum", field: "type", values: ["local", "stdio"] },
{
kind: "all",
conditions: [
{ kind: "missing", field: "type" },
{ kind: "present", field: "url" },
],
},
],
},
displayName: "fx",
location: fxLocation,
privateProfile: true,
format: "fx",
}),
defineClient({
name: "junie",
mcpAdd: { projectPaths: [".junie/mcp/mcp.json"] },
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "present", field: "url" }],
},
displayName: "Junie",
location: junieLocation,
junieSettings: (context: ClientPathContext, { markerPath }) => ({
userConfigPath: join(markerPath, "config.json"),
...(context.env.JUNIE_MCP_DEFAULT_LOCATIONS === undefined
? {}
: { mcpDefaultLocations: context.env.JUNIE_MCP_DEFAULT_LOCATIONS }),
...(context.env.JUNIE_CONFIG_LOCATION === undefined
? {}
: { configLocation: context.env.JUNIE_CONFIG_LOCATION }),
...(context.env.JUNIE_CONFIG_DEFAULT_LOCATIONS === undefined
? {}
: {
configDefaultLocations: context.env.JUNIE_CONFIG_DEFAULT_LOCATIONS,
}),
}),
format: "json",
}),
defineClient({
name: "goose",
mcpAdd: {},
registrationConnection: {
kind: "flat",
fields: ["uri"],
stdio: [{ kind: "required-enum", field: "type", values: ["stdio"] }],
},
displayName: "Goose",
location: gooseLocation,
configPaths: gooseConfigPaths,
readOnlyLowerLayers: true,
format: "goose",
}),
defineClient({
name: "kilo",
registrationConnection: {
kind: "flat",
fields: ["url"],
stdio: [{ kind: "required-enum", field: "type", values: ["local"] }],
},
displayName: "Kilo Code",
mcpAdd: {
aliases: ["kilo", "kilocode"],
projectLocation: kiloProjectLocation,
},
location: kiloLocation,
configPaths: kiloCandidatePaths,
discoveryPaths: kiloDiscoveryPaths,
layeredLocation: kiloLayeredLocation,
format: "kilo",
}),
defineClient({
name: "grok_bot",
registrationConnection: {
kind: "unavailable",
reason:
"Grok Bot has no supported configuration writer. Configure its MCP connection manually.",
},
displayName: "Grok Bot",
configPath: grokBotDirectory,
markerPath: grokBotDirectory,
format: "unsupported",
}),
] as const satisfies readonly ClientDefinition[];
export type SupportedClientName =
(typeof SUPPORTED_CLIENT_DEFINITIONS)[number]["name"];
/** One client's row, for selection surfaces such as `rea mcp add` that project it. */
export const supportedClientDefinition = (
name: SupportedClientName,
): Pick<
ClientDefinition,
"name" | "displayName" | "format" | "registrationProfile" | "mcpAdd"
> => {
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
const definition = definitions.find((candidate) => candidate.name === name);
if (definition === undefined)
throw new Error(`No supported client definition for ${name}`);
return definition;
};
/**
* Paths whose presence means the product itself is applicable, so doctor and
* setup should inspect the client. Layered sources count: OpenCode still loads
* its XDG files when a custom directory override does not exist. Shared
* registration storage never establishes applicability; see
* {@link clientOwnershipEvidencePaths}.
*/
export const clientEvidencePaths = (
client: Pick<
SetupClient,
"configPath" | "configPaths" | "markerPath" | "discoveryPaths"
>,
): readonly string[] => [
...new Set(
(
client.discoveryPaths ?? [
client.configPath,
...(client.configPaths ?? []),
client.markerPath,
]
).filter((path): path is string => path !== undefined && path.length > 0),
),
];
/**
* Paths where a recognizable REA-owned row proves ownership of a registration
* REA wrote, never that the product is installed: shared storage is created by
* other products and by REA's own skill installs. A client whose registration
* is product-local declares no shared storage, so this stays empty for it.
*/
export const clientOwnershipEvidencePaths = (
client: Pick<
SetupClient,
"configPath" | "configPaths" | "sharedRegistration"
>,
): readonly string[] =>
client.sharedRegistration === true
? [client.configPath, ...(client.configPaths ?? [])].filter(
(path): path is string => path !== undefined && path.length > 0,
)
: [];
/**
* Registration storage this client shares with another product: its own shared
* configuration plus any same-scope fallback another client also loads. Only
* this storage may be retained when product applicability is unproven, because
* failing closed on it would block REA removals for files REA does not own.
* Product-local configuration is REA's own boundary and stays fail-closed.
*/
export const clientSharedRegistrationPaths = (
client: Pick<
SetupClient,
"configPath" | "configPaths" | "sharedRegistration" | "zcodeFallbackPath"
>,
): ReadonlySet<string> =>
new Set([
...clientOwnershipEvidencePaths(client),
...(client.zcodeFallbackPath === undefined
? []
: [client.zcodeFallbackPath]),
]);
const resolvePath = (
path: ClientPath,
context: ClientPathContext,
): ClientPathResult => {
const resolved =
typeof path === "function" ? path(context) : join(context.home, ...path);
return typeof resolved === "string" ? ok(resolved) : resolved;
};
const resolveLocation = (
definition: ClientDefinition,
context: ClientPathContext,
): Result<ClientLocation, ClientPathFailure> => {
if (definition.location !== undefined) return definition.location(context);
const config = resolvePath(definition.configPath, context);
if (!config.ok) return config;
const marker = resolvePath(definition.markerPath, context);
return marker.ok
? ok({ configPath: config.value, markerPath: marker.value })
: marker;
};
/**
* Layers in increasing precedence, ending with the writable file unless the
* row already places it. A file loaded more than once takes effect at its last
* load, so only that occurrence is kept.
*/
const layerLoadOrder = (
paths: readonly string[],
configPath: string,
): readonly string[] => {
const ordered = paths.includes(configPath) ? paths : [...paths, configPath];
return ordered.filter((path, index) => ordered.lastIndexOf(path) === index);
};
/** Describe every client location that setup, doctor, or uninstall may inspect. */
export const supportedClients = (
home: string,
platform: NodeJS.Platform,
env: ClientPathContext["env"] = process.env,
systemPaths: ClientSystemPaths = {},
): readonly SetupClient[] => {
const context = { home, platform, env, systemPaths };
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
return definitions.map((definition) => {
try {
const location = resolveLocation(definition, context);
if (!location.ok)
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
format: definition.format,
configPath: location.error.path,
configPathError: location.error.message,
...(location.error.msixPackage === undefined
? {}
: { msixPackage: location.error.msixPackage }),
};
const { configPath, markerPath, msixPackage } = location.value;
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
configPath,
...(definition.geminiSettings === undefined
? {}
: { geminiSettings: definition.geminiSettings(context) }),
...(definition.junieSettings === undefined
? {}
: {
junieSettings: definition.junieSettings(context, location.value),
}),
...(definition.configPaths === undefined
? {}
: {
configPaths: layerLoadOrder(
definition.configPaths(context),
configPath,
),
}),
...(definition.zcodeFallbackPath === undefined
? {}
: { zcodeFallbackPath: definition.zcodeFallbackPath(context) }),
markerPath,
...(msixPackage === undefined ? {} : { msixPackage }),
...(definition.quitBeforeSetup === true
? { quitBeforeSetup: true }
: {}),
...(definition.discoveryPaths === undefined
? {}
: { discoveryPaths: definition.discoveryPaths(context) }),
...(definition.privateProfile === true
? { privateProfile: { home } }
: {}),
...(definition.readOnlyLowerLayers === true
? { readOnlyLowerLayers: true }
: {}),
...(definition.registrationApplicability === true
? { registrationApplicability: true }
: {}),
...(definition.sharedRegistration === true
? { sharedRegistration: true }
: {}),
format: definition.format,
};
} catch (cause: unknown) {
if (cause instanceof HermesClientPathError)
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
format: definition.format,
configPath: cause.path,
configPathError: cause.message,
};
if (definition.name !== "pi") throw cause;
return {
name: definition.name,
registrationProfile: definition.registrationProfile,
displayName: definition.displayName,
format: definition.format,
configPath: env.PI_CODING_AGENT_DIR ?? "",
configPathError: `Invalid PI_CODING_AGENT_DIR: ${errorMessage(cause)}. Repair the override before configuring Pi.`,
};
}
});
};
/**
* The client table with each layered location resolved: the rows setup,
* doctor, update and uninstall act on.
*/
export const resolveSupportedClients = async (
home: string,
platform: NodeJS.Platform,
env: ClientPathContext["env"] = process.env,
systemPaths: ClientSystemPaths = {},
): Promise<readonly SetupClient[]> => {
const context = { home, platform, env, systemPaths };
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
const rows = supportedClients(home, platform, env, systemPaths);
return Promise.all(
rows.map(async (row) => {
const resolve = definitions.find(
({ name }) => name === row.name,
)?.layeredLocation;
if (resolve === undefined || row.configPathError !== undefined)
return row;
const location = await resolve(context);
return location.ok
? { ...row, ...location.value }
: {
...row,
configPath: location.error.path,
configPathError: location.error.message,
...(location.error.failure === undefined
? {}
: { configPathFailure: location.error.failure }),
};
}),
);
};
/** Resolved destinations and unresolved selections share one path-resolution owner. */
export const clientSkillDirectories = (
home: string,
clientIds: readonly string[] | undefined,
environment: Readonly<NodeJS.ProcessEnv>,
platform: NodeJS.Platform,
): {
readonly directories: readonly {
readonly client: string;
readonly directory: string;
}[];
readonly unresolved: readonly {
readonly client: string;
readonly path: string;
readonly detail: string;
}[];
} => {
const unresolved: { client: string; path: string; detail: string }[] = [];
const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;
const selected =
clientIds === undefined
? [
"shared",
...definitions
.filter(({ skillPath }) => skillPath !== undefined)
.map(({ name }) => name),
]
: clientIds.length === 0
? ["shared"]
: clientIds;
const sharedDirectory = appendCallerPath(home, ".agents/skills", platform);
const destinations = new Map<string, { client: string; directory: string }>();
for (const client of selected) {
const definition = definitions.find(({ name }) => name === client);
if (definition === undefined && client !== "shared") {
unresolved.push({
client,
path: client,
detail: `Unsupported skill client: ${client}`,
});
continue;
}
let directory: string;
try {
const resolved =
definition?.skillPath === undefined
? ok(sharedDirectory)
: resolvePath(definition.skillPath, {
home,
platform,
env: environment,
});
if (!resolved.ok) {
unresolved.push({
client,
path: resolved.error.path,
detail: resolved.error.message,
});
continue;
}
directory = resolved.value;
} catch (cause: unknown) {
if (cause instanceof HermesClientPathError) {
unresolved.push({ client, path: cause.path, detail: cause.message });
continue;
}
throw cause;
}
if (!destinations.has(directory))
destinations.set(directory, {
client: directory === sharedDirectory ? "shared" : client,
directory,
});
}
return {
directories: [...destinations.values()].sort((left, right) =>
compareUnicodeCodePoints(left.directory, right.directory),
),
unresolved,
};
};