@useshifu/coding-harness 0.3.16 → 0.3.17

package/README.md

@@ -104,7 +104,7 @@ Missing local turns are reported in `unavailableSegments`. A partial overlap wit
 The context branch adds a remote MCP connection using the same saved Codex key:
 
 ```sh
-npx --yes @useshifu/coding-harness@0.3.16 mcp-setup --harness codex --mcp-url https://YOUR-BRANCH-HOST/mcp
+npx --yes @useshifu/coding-harness@0.3.17 mcp-setup --harness codex --mcp-url https://YOUR-BRANCH-HOST/mcp
 ```
 
 Before this release is published, install dependencies and run from the checkout root:
@@ -133,13 +133,29 @@ Official configuration reference: https://learn.chatgpt.com/docs/config-file/con
 OpenCode uses the same `/mcp` endpoint and three tools, authenticated with its own saved OpenCode connection key:
 
 ```sh
-npx --yes @useshifu/coding-harness@0.3.16 mcp-setup --harness opencode --mcp-url https://YOUR-SHIFU-HOST/mcp
+npx --yes @useshifu/coding-harness@0.3.17 mcp-setup --harness opencode --mcp-url https://YOUR-SHIFU-HOST/mcp
 ```
 
-Until 0.3.16 is published, install dependencies with `npm ci --prefix packages/shifu-coding-harness --ignore-scripts` from the checkout root, then run the checkout CLI with the same arguments. Setup preserves existing sync settings and other MCP servers, checks authenticated initialization and tool discovery, and installs the `shifu-context` usage instructions. A missing OpenCode connection prompts for its key in the terminal. A Codex key cannot authorize an OpenCode connection.
+Until 0.3.17 is published, install dependencies with `npm ci --prefix packages/shifu-coding-harness --ignore-scripts` from the checkout root, then run the checkout CLI with the same arguments. Setup preserves existing sync settings and other MCP servers, checks authenticated initialization and tool discovery, and installs the `shifu-context` usage instructions. A missing OpenCode connection prompts for its key in the terminal. A Codex key cannot authorize an OpenCode connection.
 
 The installer adds a remote `shifu` entry with `oauth: false` to OpenCode's JSON or JSONC configuration, preserving existing content and comments. Its Authorization header uses OpenCode's `{file:...}` substitution to read a protected local credential file; the key stays out of configuration, command arguments and chat. Replacing the saved connection key refreshes that file; disconnect removes it. Restart OpenCode and start a new session after setup. Project-specific configuration can override global MCP settings; inspect `opencode mcp list` in the project if tools do not appear.
 
 The API derives the harness and tenant from the authenticated connector key. Memory updates from OpenCode carry `opencode` provenance; personal eligibility, general retrieval and evidence verification use the same rules as Codex. Coding-session sync remains separate. No additional local MCP server or OpenCode plugin is required.
 
 Official references: [MCP servers](https://docs.opencode.ai/docs/mcp-servers/) and [configuration](https://docs.opencode.ai/docs/config/).
+
+## Claude Code context and memory
+
+Claude Code connects to the same `/mcp` endpoint and three tools with its own saved connection key:
+
+```sh
+npx --yes @useshifu/coding-harness@0.3.17 mcp-setup --harness claude_code --mcp-url https://YOUR-SHIFU-HOST/mcp
+```
+
+Until 0.3.17 is published, install checkout dependencies as above and run the checkout CLI with these arguments. Setup checks the existing Claude Code key, authenticated initialization and tool discovery, and installs the `shifu-context` skill. It preserves the sync endpoint, schedule, checkpoints and other MCP servers. A missing connection prompts for a Claude Code key in the terminal; do not substitute a Codex or OpenCode key.
+
+The user-scope HTTP connection uses Claude Code's `headersHelper` to read the protected local Shifu connection file. The key is absent from MCP configuration and command arguments. Replacing the saved key is picked up when the helper runs on reconnection. Restart Claude Code or start a new session after setup; use `/mcp` to inspect or reconnect Shifu. Local or project MCP configuration can override a user-scope server with the same name.
+
+The API records memory provenance as `claude_code` from the authenticated key. Context retrieval and memory behavior match Codex and OpenCode; ordinary session sync continues independently. This setup requires local macOS/Linux and a Claude Code CLI supporting HTTP `headersHelper`, verified with Claude Code 2.1.295. Unsupported or broken older clients need an update using Claude Code's official installation instructions; there is no plaintext credential fallback. `CLAUDE_CONFIG_DIR` is honored for MCP configuration, installed skills and session discovery.
+
+Official reference: [Claude Code MCP connections](https://code.claude.com/docs/en/mcp).

package/bin/shifu-harness.js

@@ -40,7 +40,7 @@ const MAX_TURNS_PER_SEGMENT = 12;
 const MAX_TITLE_LENGTH = 160;
 const MAX_WORK_DETAIL_LENGTH = 600;
 const CONFIG_VERSION = 2;
-const RUNNER_VERSION = "0.3.16";
+const RUNNER_VERSION = "0.3.17";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -94,7 +94,7 @@ function codexSessionsRoot() {
 }
 
 function claudeSessionsRoot() {
-  return process.env.SHIFU_CLAUDE_SESSIONS_ROOT || path.join(os.homedir(), ".claude", "projects");
+  return process.env.SHIFU_CLAUDE_SESSIONS_ROOT || path.join(claudeHome(), "projects");
 }
 
 function opencodeQuery(query) {
@@ -1085,7 +1085,7 @@ function removeCodexHooks() {
 
 function installDestination(harness) {
   if (harness === "codex") return path.join(codexHome(), "skills", "shifu-sync");
-  if (harness === "claude_code") return path.join(os.homedir(), ".claude", "skills", "shifu-sync");
+  if (harness === "claude_code") return path.join(claudeHome(), "skills", "shifu-sync");
   return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "skills", "shifu-sync");
 }
 
@@ -1120,7 +1120,7 @@ function install(harness, quiet = false) {
       .replaceAll("npx --yes @useshifu/coding-harness", `"${process.execPath}" "${installedRunnerPath()}"`);
     fs.writeFileSync(skill, content, { mode: 0o600 });
   }
-  if (harness === "codex" || harness === "opencode") {
+  if (Object.hasOwn(HARNESS_NAMES, harness)) {
     const contextDestination = path.join(path.dirname(installDestination(harness)), "shifu-context");
     copyDirectory(path.join(__dirname, "..", "skills", "shifu-context"), contextDestination);
     const contextFile = path.join(contextDestination, "SKILL.md");
@@ -1310,8 +1310,12 @@ function codexHome() {
   return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }
 
+function claudeHome() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}
+
 function mcpHeaders(harness) {
-  if (harness !== "codex" && harness !== "opencode") throw new Error("Shifu MCP currently supports Codex and OpenCode.");
+  requireHarness(harness);
   const file = configPath(harness);
   const stat = fs.lstatSync(file);
   if (!stat.isFile() || (process.platform !== "win32" && ((stat.mode & 0o077) || stat.uid !== process.getuid()))) {
@@ -1322,8 +1326,8 @@ function mcpHeaders(harness) {
   return { Authorization: `Bearer ${config.token}` };
 }
 
-function helperCommand() {
-  const args = [process.execPath, installedRunnerPath(), "mcp-headers", "--harness", "codex", "--config-root", path.resolve(configRoot())];
+function helperCommand(harness = "codex") {
+  const args = [process.execPath, path.resolve(installedRunnerPath()), "mcp-headers", "--harness", harness, "--config-root", path.resolve(configRoot())];
   if (process.platform === "win32") throw new Error("Prompt-driven MCP credential setup currently supports macOS and Linux. Windows requires a supported local credential-helper launcher.");
   return args.map((value) => `'${value.replaceAll("'", "'\\''")}'`).join(" ");
 }
@@ -1415,7 +1419,8 @@ async function verifyMcp(mcpUrl, token) {
 
 function prepareCodexMcpConfig(mcpUrl, helper) {
   const file = path.join(codexHome(), "config.toml");
-  const original = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const exists = fs.existsSync(file);
+  const original = exists ? fs.readFileSync(file, "utf8") : "";
   const temporaryHome = fs.mkdtempSync(path.join(os.tmpdir(), "shifu-codex-mcp-"));
   const candidateFile = path.join(temporaryHome, "config.toml");
   const environment = { ...process.env, CODEX_HOME: temporaryHome };
@@ -1432,7 +1437,7 @@ function prepareCodexMcpConfig(mcpUrl, helper) {
     if (!parsed.transport?.http_headers_helper || parsed.transport.type !== "streamable_http" || parsed.transport.url !== mcpUrl) {
       throw new Error("This Codex version does not support local HTTP header helpers. Update Codex before MCP setup.");
     }
-    return { file, original, candidate };
+    return { file, exists, original, candidate };
   } catch (error) {
     if (error?.code === "ENOENT") throw new Error("The codex command is unavailable. Install Codex CLI before MCP setup.");
     if (error instanceof Error && !error.stdout && !error.stderr) throw error;
@@ -1542,10 +1547,66 @@ function removeOpenCodeMcpConfig() {
   fs.rmSync(openCodeTokenPath(), { force: true });
 }
 
+function claudeMcpConfig() {
+  const file = process.env.CLAUDE_CONFIG_DIR ? path.resolve(claudeHome(), ".claude.json") : path.join(os.homedir(), ".claude.json");
+  const exists = fs.existsSync(file);
+  if (exists && !fs.lstatSync(file).isFile()) throw new Error("Claude Code configuration must be a regular file, not a link. Nothing was changed.");
+  const original = exists ? fs.readFileSync(file, "utf8") : "";
+  let value;
+  try { value = JSON.parse(original || "{}"); }
+  catch { throw new Error("Claude Code configuration is invalid. Fix its JSON before MCP setup; nothing was changed."); }
+  if (!value || typeof value !== "object" || Array.isArray(value) || (value.mcpServers !== undefined && (!value.mcpServers || typeof value.mcpServers !== "object" || Array.isArray(value.mcpServers)))) {
+    throw new Error("Claude Code configuration is invalid. Nothing was changed.");
+  }
+  return { file, exists, original, value };
+}
+
+function editClaudeMcp(original, entry) {
+  return jsonc.applyEdits(original || "{}\n", jsonc.modify(original || "{}\n", ["mcpServers", "shifu"], entry, { formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" } }));
+}
+
+function prepareClaudeMcpConfig(mcpUrl, helper) {
+  const config = claudeMcpConfig();
+  const entry = { type: "http", url: mcpUrl, headersHelper: helper, timeout: 120_000 };
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "shifu-claude-mcp-"));
+  const environment = { ...process.env, HOME: temporary, CLAUDE_CONFIG_DIR: temporary, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" };
+  delete environment.CLAUDECODE;
+  delete environment.CLAUDE_CODE_SESSION_ID;
+  try {
+    const claude = process.env.SHIFU_CLAUDE_BIN || "claude";
+    const version = execFileSync(claude, ["--version"], { cwd: temporary, env: environment, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024 }).match(/^(\d+\.\d+\.\d+)\b/m)?.[1];
+    if (!version || olderPackageVersion(version, "1.0.119")) throw new Error("Claude Code predates HTTP credential-helper support.");
+    const temporaryConfig = path.join(temporary, ".claude.json");
+    // Validate through Claude without letting its incidental settings writes replace ours.
+    fs.writeFileSync(temporaryConfig, editClaudeMcp(config.original, undefined), { mode: 0o600 });
+    execFileSync(claude, ["mcp", "add-json", "shifu", JSON.stringify(entry), "--scope", "user"], { cwd: temporary, env: environment, stdio: ["ignore", "pipe", "pipe"], timeout: 20_000, maxBuffer: 1024 * 1024 });
+    const accepted = JSON.parse(fs.readFileSync(temporaryConfig, "utf8")).mcpServers?.shifu;
+    if (accepted?.type !== entry.type || accepted.url !== mcpUrl || accepted.headersHelper !== helper || accepted.timeout !== entry.timeout) throw new Error("Claude Code did not accept the expected MCP credential helper.");
+    return { ...config, candidate: editClaudeMcp(config.original, entry) };
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error("The claude command is unavailable. Install Claude Code before MCP setup.");
+    // Native diagnostics can include settings and credentials from other servers.
+    throw new Error("Claude Code could not validate its HTTP MCP credential helper. Update Claude Code or fix its existing config; nothing was changed.");
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function removeClaudeMcpConfig(expectedHelper) {
+  const config = claudeMcpConfig();
+  if (config.value.mcpServers?.shifu?.headersHelper !== expectedHelper) return;
+  if (!unchangedConfig(config)) throw new Error("Claude Code configuration changed during disconnect. Retry to preserve those changes.");
+  writePrivateText(config.file, editClaudeMcp(config.original, undefined));
+}
+
+function unchangedMcpConfig(prepared) {
+  return (prepared.configs || [prepared]).every(unchangedConfig);
+}
+
 async function setupMcp(harness) {
-  if (harness !== "codex" && harness !== "opencode") throw new Error("Shifu MCP currently supports Codex and OpenCode.");
+  requireHarness(harness);
   if (process.platform !== "darwin" && process.platform !== "linux") throw new Error("Prompt-driven MCP credential setup currently supports local macOS and Linux.");
-  const helper = harness === "codex" ? helperCommand() : undefined;
+  const helper = harness === "opencode" ? undefined : helperCommand(harness);
   if (fs.existsSync(configPath(harness)) && !fs.lstatSync(configPath(harness)).isFile()) {
     throw new Error(`The saved ${HARNESS_NAMES[harness]} connection must be a regular private file, not a link.`);
   }
@@ -1562,8 +1623,8 @@ async function setupMcp(harness) {
   if (!TOKEN_PATTERN.test(config.token)) throw new Error(`The saved ${HARNESS_NAMES[harness]} connection key is invalid. Run connect again.`);
   await validateConnection(config.apiUrl, config.token, harness);
   const tools = await verifyMcp(mcpUrl, config.token);
-  const prepared = harness === "codex" ? prepareCodexMcpConfig(mcpUrl, helper) : prepareOpenCodeMcpConfig(mcpUrl);
-  if (harness === "opencode" ? prepared.configs.some((config) => !unchangedConfig(config)) : (fs.existsSync(prepared.file) ? fs.readFileSync(prepared.file, "utf8") : "") !== prepared.original) {
+  const prepared = harness === "codex" ? prepareCodexMcpConfig(mcpUrl, helper) : harness === "opencode" ? prepareOpenCodeMcpConfig(mcpUrl) : prepareClaudeMcpConfig(mcpUrl, helper);
+  if (!unchangedMcpConfig(prepared)) {
     throw new Error(`${HARNESS_NAMES[harness]} configuration changed during setup. Run mcp-setup again to preserve those changes.`);
   }
   fs.chmodSync(configPath(harness), 0o600);
@@ -1573,12 +1634,12 @@ async function setupMcp(harness) {
     throw new Error("The shifu-context skill is missing. Run mcp-setup from the package or branch checkout to install it.");
   }
   if (fs.readFileSync(configPath(harness), "utf8") !== originalConnection) throw new Error("The saved Shifu connection changed during setup. Run mcp-setup again to preserve those changes.");
-  if (harness === "opencode" && prepared.configs.some((config) => !unchangedConfig(config))) throw new Error("OpenCode configuration changed during setup. Run mcp-setup again to preserve those changes.");
+  if (!unchangedMcpConfig(prepared)) throw new Error(`${HARNESS_NAMES[harness]} configuration changed during setup. Run mcp-setup again to preserve those changes.`);
   if (harness === "opencode") writePrivateText(openCodeTokenPath(), config.token);
   writePrivateText(prepared.file, prepared.candidate);
-  writeJSON(configPath(harness), { ...config, mcpUrl });
+  writeJSON(configPath(harness), { ...config, mcpUrl, ...(harness === "claude_code" ? { mcpHeadersHelper: helper } : {}) });
   console.error(`Verified Shifu MCP tools: ${tools.join(", ")}. ${HARNESS_NAMES[harness]} configuration and usage instructions are installed.`);
-  console.error(`The existing connection key is read ${harness === "codex" ? "by a local credential helper" : "from a private credential file"}; it was not copied into MCP configuration. The sync endpoint and schedule were preserved.`);
+  console.error(`The existing connection key is read ${harness === "opencode" ? "from a private credential file" : "by a local credential helper"}; it was not copied into MCP configuration. The sync endpoint and schedule were preserved.`);
   console.error(`Reload ${HARNESS_NAMES[harness]} or start a new chat to load the MCP tools and shifu-context skill. This setup check does not prove the current chat has loaded them.`);
 }
 
@@ -1586,6 +1647,7 @@ function disconnect(harness) {
   const config = readConfig(harness);
   if (fs.existsSync(lockPath(harness))) throw new Error("A Shifu sync is running. Try disconnecting again after it finishes.");
   if (harness === "opencode" && (config.mcpUrl || fs.existsSync(openCodeTokenPath()))) removeOpenCodeMcpConfig();
+  if (harness === "claude_code" && config.mcpUrl) removeClaudeMcpConfig(config.mcpHeadersHelper || helperCommand("claude_code"));
   removeSchedule(harness);
   for (const file of [configPath(harness), statePath(harness), pendingPath(harness)]) {
     try { fs.unlinkSync(file); } catch (error) { if (error?.code !== "ENOENT") throw error; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "Scheduled, redacted coding-harness activity sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",

package/skills/shifu-context/SKILL.md

@@ -13,9 +13,9 @@ When asked to connect Shifu context, run:
 npx --yes @useshifu/coding-harness mcp-setup --harness codex
 ```
 
-For a branch deployment, append `--mcp-url` with the user's supplied HTTPS endpoint ending in `/mcp`. Keep the existing sync API endpoint. The CLI reuses this harness's saved key, checks the authenticated tools, and preserves existing settings. Codex uses a local credential helper; OpenCode uses its native `{file:...}` substitution pointing to a private credential file. The key is never placed literally in MCP configuration. If no connection exists, the CLI asks for this harness's key in the terminal. Never request or print the key in chat or place it in command arguments. When input is unavailable, have the user run the command in an interactive terminal. Do not substitute plaintext credentials for an unsupported credential mechanism.
+For a branch deployment, append `--mcp-url` with the user's supplied HTTPS endpoint ending in `/mcp`. Keep the existing sync API endpoint. The CLI reuses this harness's saved key, checks the authenticated tools, and preserves existing settings. Codex and Claude Code use local credential helpers; OpenCode uses its native `{file:...}` substitution pointing to a private credential file. The key is never placed literally in MCP configuration. If no connection exists, the CLI asks for this harness's key in the terminal. Never request or print the key in chat or place it in command arguments. When input is unavailable, have the user run the command in an interactive terminal. Do not substitute plaintext credentials for an unsupported credential mechanism.
 
-Reload the harness or start a new chat after setup. Check that the tools are actually available before claiming this chat can use them. Setup supports local macOS/Linux connections; remote execution environments cannot read this device's credential helper or file. OpenCode requires the v1 config schema (verified with 1.18.30); unsupported versions or config schemas fail before MCP settings change.
+Reload the harness or start a new chat after setup. Check that the tools are actually available before claiming this chat can use them. Setup supports local macOS/Linux connections; remote execution environments cannot read this device's credential helper or file. OpenCode requires the v1 config schema (verified with 1.18.30). Claude Code requires HTTP MCP with `headersHelper` (verified with 2.1.295); setup validates it through the installed CLI. If Claude Code is outdated, help the user update it using official installation instructions before retrying. The connection uses user scope and honors `CLAUDE_CONFIG_DIR`. Restart Claude Code and start a new session, or use `/mcp` to reconnect after rotating the saved key. Unsupported versions or config schemas fail before MCP settings change.
 
 ## Consult context