JuliusBrussee/caveman · error · Error

could not install caveman-cloud MCP for ${agent}

Error message

could not install caveman-cloud MCP for ${agent}

What it means

installAgentNativeCloudMcp() registers the caveman-cloud MCP server for claude (via installMcpJson into ~/.claude.json mcpServers) or codex (via installMcpForAgent). When the underlying installer returns falsy — it could not write the registration — this error aborts the bundle install. The writeMcpServerMarker call after it is what makes the registration Caveman-journaled, so failing install must never continue.

Source

Thrown at packages/cli/src/index.ts:2371

    exact_shape: keys.length === 2 && keys[0] === "args" && keys[1] === "command",
  };
}

function agentNativeCloudMcpMatches(agent: "claude" | "codex", mcp: { command: string; args: string[] }): boolean {
  if (agent === "codex") return codexMcpRegistrationMatches("caveman-cloud", mcp);
  const actual = claudeMcpRegistration("caveman-cloud");
  return actual.present && actual.exact_shape && actual.command === mcp.command && JSON.stringify(actual.args) === JSON.stringify(mcp.args);
}

function installAgentNativeCloudMcp(agent: "claude" | "codex", mcp: { command: string; args: string[] }): void {
  if (agentNativeCloudMcpMatches(agent, mcp)) {
    writeMcpServerMarker(agent, "caveman-cloud", mcp, "caveman_context");
    return;
  }
  const installed = agent === "claude"
    ? installMcpJson(join(homedir(), ".claude.json"), ["mcpServers", "caveman-cloud"], { command: mcp.command, args: mcp.args })
    : installMcpForAgent(findAgent(agent)!, mcp, "caveman-cloud");
  if (!installed) throw new Error(`could not install caveman-cloud MCP for ${agent}`);
  writeMcpServerMarker(agent, "caveman-cloud", mcp, "caveman_context");
}

function uninstallAgentNativeCloudMcp(agent: "claude" | "codex"): void {
  const removed = agent === "claude"
    ? removeMcpJson(join(homedir(), ".claude.json"), ["mcpServers", "caveman-cloud"])
    : uninstallMcpForAgent(findAgent(agent)!, "caveman-cloud");
  if (!removed) throw new Error(`could not remove caveman-cloud MCP for ${agent}`);
  try { unlinkSync(mcpServerMarkerPath(agent, "caveman-cloud")); } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
  }
}

function agentNativeSkillFiles(agent: "claude" | "codex"): Array<{ name: string; file: string; body: string }> {
  const names = AGENT_SKILL_SUITES["agent-native"] ?? [];
  const root = agent === "claude" ? join(homedir(), ".claude", "skills") : join(homedir(), ".codex", "skills");
  return names.map((name) => ({ name, file: join(root, name, "SKILL.md"), body: SKILLS[name]! }));
}

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Check that ~/.claude.json (or ~/.codex/config.toml) is valid JSON/TOML and writable by the current user
2. Fix file permissions (chmod/chown) on the agent config
3. Back up and remove a corrupted config so the agent and caveman can regenerate it, then re-run setup
4. Ensure CODEX_HOME points at the config you expect when running setup

import { readFileSync, accessSync, constants } from "node:fs";
function claudeConfigWritable(p = join(homedir(), ".claude.json")): boolean {
  try {
    if (existsSync(p)) { JSON.parse(readFileSync(p, "utf8")); accessSync(p, constants.W_OK); }
    return true;
  } catch { return false; }
}

function isMcpInstallError(e: unknown): boolean {
  return e instanceof Error && e.message.startsWith("could not install caveman-cloud MCP for ");
}

try {
  runCavemanSetup();
} catch (e) {
  if (isMcpInstallError(e)) {
    // validate ~/.claude.json / ~/.codex/config.toml, fix permissions, re-run
  } else throw e;
}

When it happens

Trigger: `caveman setup` / agent-native install where ~/.claude.json is unreadable/unwritable, malformed JSON so the installer cannot merge mcpServers, ~/.codex/config.toml cannot be edited, or findAgent(agent) cannot resolve a writable config path for the agent.

Common situations: Permissions problems on ~/.claude.json; another tool holding/reformatting the file; a corrupted config from a different tool; codex installed under a non-default CODEX_HOME.

Related errors

• could not remove caveman-cloud MCP for ${agent}
• cannot read ${agent} agent-native bundle journal: ${(error a
• cannot read pending ${agent} agent-native bundle journal: ${
• ${agent} caveman-cloud MCP changed during interrupted setup;
• ${profile.display_name} not found on PATH

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/153f4bea7b056507. Report an issue: GitHub.