claude-code-modes 0.2.8 → 0.2.10

package/README.md

@@ -27,6 +27,20 @@ Requires [Bun](https://bun.sh/) and [Claude Code](https://docs.anthropic.com/en/
 
 > **Migrating from an older git clone?** If you previously used `./claude-mode` directly from the repo, that bash wrapper has been removed. Run `bun link` in the repo to put `claude-mode` on your PATH via the package.json bin entry, or switch to the binary install above.
 
+## Updating
+
+If you installed the binary via `install.sh`:
+
+```bash
+claude-mode update              # update to the latest release
+claude-mode update --check      # check without installing
+claude-mode update 0.2.5        # pin a specific version (downgrade or reinstall)
+claude-mode update --force      # reinstall same version (repair a corrupt binary)
+claude-mode update --dry-run    # show what would happen
+```
+
+`update` only works on binaries built from the upstream repo. If you're running from a `git clone` checkout (`bun link`), use `git pull && bun install` instead. If you're running a fork build, update via your fork's release process.
+
 ## Usage
 
 Pick a preset that matches your task:
@@ -40,6 +54,7 @@ claude-mode explore     # Read-only — understand code without changing it
 claude-mode debug       # Investigation-first debugging (chill base)
 claude-mode methodical  # Step-by-step precision (chill base)
 claude-mode director    # Delegate to sub-agents, orchestrate and verify (chill base)
+claude-mode partner     # Pair-of-equals: terse, test-first, decisive on craft (chill base)
 claude-mode none        # Strip all behavioral opinions, use your own CLAUDE.md
 ```
 
@@ -53,6 +68,7 @@ claude-mode none        # Strip all behavioral opinions, use your own CLAUDE.md
 | `debug` | collaborative | pragmatic | narrow | Find root causes — evidence-first, ask for guidance when stuck |
 | `methodical` | surgical | architect | narrow | Step-by-step craftsmanship — follow instructions, stop when done |
 | `director` | collaborative | architect | unrestricted | Orchestrate sub-agents — delegate implementation, verify results |
+| `partner` | partner | pragmatic | adjacent | Pair-of-equals collaboration — decisive on craft, test-first, terse by default |
 | `none` | — | — | — | Strip all behavioral instructions, use your own |
 
 ### Alternative base: chill
@@ -93,10 +109,10 @@ prompts/
   base/         Standard base (derived from upstream Claude Code)
   chill/        Alternative base (emotion-research-informed, leaner)
   axis/         Behavioral prompts organized by three axes
-  modifiers/    Behavioral layers (bold, debug, methodical, director, readonly, context-pacing)
+  modifiers/    Behavioral layers (bold, debug, methodical, director, readonly, context-pacing, speak-plain, tdd)
 ```
 
-Each base has a `base.json` manifest — a flat JSON array declaring fragment order with `"axes"` and `"modifiers"` as reserved insertion points. The standard base is validated against Claude Code **v2.1.121**.
+Each base has a `base.json` manifest — a flat JSON array declaring fragment order with `"axes"` and `"modifiers"` as reserved insertion points. The standard base is validated against Claude Code **v2.1.133**.
 
 The behavioral layer is composed from three independent axes — **agency** (how much initiative), **quality** (what code standard), and **scope** (how far beyond the request). Presets are just named combinations of these three values.
 
@@ -159,6 +175,14 @@ Check the installed version:
 claude-mode --version
 ```
 
+Release builds print a single line (`claude-mode 0.2.8`). Builds compiled from a git checkout — forks, dev builds — also print build provenance (`repo`, `branch`, `commit`, plus `(dirty)` if the worktree had uncommitted changes), so a binary built from a fork is unmistakably identifiable.
+
+`--version` is standalone-only — combining it with any other flag exits with a non-zero status. To pass `--version` through to Claude Code itself, use the `--` escape hatch:
+
+```bash
+claude-mode -- --version    # Forwards --version to claude
+```
+
 ## Config file
 
 Create a `.claude-mode.json` in your project root to define reusable custom modifiers, axis values, and presets. Manage it with the CLI or edit directly.
@@ -236,6 +260,7 @@ claude-mode config remove-preset <name>              # Remove custom preset
 - **autonomous** — Makes decisions, creates files, restructures without asking
 - **collaborative** — Explains reasoning, checks in at decision points
 - **surgical** — Executes exactly what was asked, nothing more
+- **partner** — Pair of equals: commits decisively on execution choices (naming, structure, idiom), defers to the user on direction (priorities, scope, what counts as done), keeps mental models in sync
 
 **Quality** — What code standard should it target?
 - **architect** — Proper abstractions, error handling, forward-thinking structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-modes",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Behaviorally-tuned system prompts for Claude Code",
   "license": "MIT",
   "type": "module",

package/prompts/base/doing-tasks.md

@@ -11,6 +11,7 @@
  - Don't explain WHAT the code does, since well-named identifiers already do that. Don't reference the current task, fix, or callers ("used by X", "added for the Y flow", "handles the case from issue #123"), since those belong in the PR description and rot as the codebase evolves.
  - For UI or frontend changes, start the dev server and use the feature in a browser before reporting the task as complete. Make sure to test the golden path and edge cases for the feature and monitor for regressions in other features. Type checking and test suites verify code correctness, not feature correctness - if you can't test the UI, say so explicitly rather than claiming success.
  - Don't use feature flags or backwards-compatibility shims when you can just change the code.
+ - When reporting results, be accurate about what you verified vs. what you assumed. Distinguish between what you confirmed (ran a command, read a file) and what you believe but did not check. Do not assert assumptions as facts.
  - If the user asks for help or wants to give feedback inform them of the following:
   - /help: Get help with using Claude Code
   - To give feedback, users should report the issue at https://github.com/anthropics/claude-code/issues

package/prompts/base/env.md

@@ -1,6 +1,6 @@
 # Environment
-You have been invoked in the following environment:
- - Primary working directory: {{CWD}}
+You have been invoked in the following environment: 
+ - Primary working directory: {{CWD}}{{WORKTREE_NOTICE}}
  - Is a git repository: {{IS_GIT}}
  - Platform: {{PLATFORM}}
  - Shell: {{SHELL}}

package/prompts/base/session-guidance.md

@@ -1,5 +1,5 @@
 # Session-specific guidance
  - If the user needs to run a shell command themselves (an interactive login like `gcloud auth login`, or something requiring their own credentials), suggest they type `! <command>` — the `!` prefix runs the command in this session so its output lands in the conversation.
  - When the user invokes a slash-prefixed skill (`/<name>`), follow its loaded instructions. Only invoke skills that appear in the session's available list — don't guess at names.
- - For work that would otherwise crowd the main context — broad codebase searches, multi-file investigation, parallel research — delegate to a sub-agent when your toolkit supports them. The point is keeping the main conversation lean, not just offload. Use the Explore-style agent for read-only investigation when one is available; otherwise use your search tools directly. Don't duplicate searches a delegated agent is already doing.
+ - Use sub-agents to keep the main context lean. Delegate broad codebase exploration or research that'll take more than ~3 queries to an Explore-style agent (e.g. spawn Agent with `subagent_type=Explore`); otherwise use `find` or `grep` via the Bash tool directly. Don't duplicate searches a delegated agent is already doing.
  - If the user asks about "ultrareview" or how to run it, explain that /ultrareview launches a multi-agent cloud review of the current branch (or /ultrareview <PR#> for a GitHub PR). It is user-triggered and billed; you cannot launch it yourself. It needs a git repository (offer to "git init" if not in one); the no-arg form bundles the local branch and does not need a GitHub remote.

package/prompts/chill/core.md

@@ -25,6 +25,8 @@ Read code before changing it. Understand what exists before proposing modificati
 
 When something fails, that's normal — it's information, not a setback. Read the error, check your assumptions, try a focused fix. Most bugs have a straightforward cause once you look at them calmly.
 
+When reporting results, be accurate about what you verified vs. what you assumed. Distinguish what you confirmed (ran a command, read a file) from what you believe but didn't check. Don't assert assumptions as facts.
+
 Write secure code. Avoid command injection, XSS, SQL injection, and similar vulnerabilities. If you spot insecure code you wrote, fix it. Use linters and skills to assist you as needed.
 
 For UI or frontend changes, start the dev server and test in a browser before reporting done. Test the golden path and edge cases, monitor for regressions. Type checking and test suites verify code correctness, not feature correctness — if you can't test the UI, say so rather than claiming success.
@@ -71,7 +73,7 @@ In code: default to no comments. Skip multi-paragraph docstrings and comment blo
 
 If a tool denial is confusing, ask the user why. If you need them to run an interactive command, suggest `! <command>` in the prompt.
 
-Using bash operations will require user input, which will slow our efforts. Prefer your specialized agents, like Read, instead of grep. Or Edit, instead of sed or awk. For broader exploration (more than ~3 queries), spawn the Explore agent.
+Using bash operations will require user input, which will slow our efforts. Prefer your specialized agents, like Read, instead of grep. Or Edit, instead of sed or awk. For broader exploration (more than ~3 queries), spawn Agent with `subagent_type=Explore`; otherwise use `find` or `grep` via Bash directly.
 
 Slash commands (e.g., /commit) invoke skills — use the Skill tool for those listed as user-invocable.
 

package/prompts/chill/env.md

@@ -1,5 +1,5 @@
 # Environment
-- Working directory: {{CWD}}
+- Working directory: {{CWD}}{{WORKTREE_NOTICE}}
 - Git repo: {{IS_GIT}}
 - Platform: {{PLATFORM}}
 - Shell: {{SHELL}}

package/src/build-info.ts

@@ -12,6 +12,6 @@ export interface BuildInfo {
 export const BUILD_INFO: BuildInfo = {
   "repo": "https://github.com/nklisch/claude-code-modes",
   "branch": null,
-  "commit": "ed8dffb",
+  "commit": "0938ea3",
   "dirty": false
 };

package/src/cli.ts

@@ -8,6 +8,7 @@ import { assemblePrompt, writeTempPrompt } from "./assemble.js";
 import { detectEnv, buildTemplateVars } from "./env.js";
 import { runConfigCommand } from "./config-cli.js";
 import { runInspectCommand } from "./inspect.js";
+import { runUpdateCommand } from "./update.js";
 import { printUsage } from "./usage.js";
 import { formatVersion } from "./version.js";
 
@@ -63,6 +64,17 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  // Update subcommand routing
+  if (argv[0] === "update") {
+    try {
+      await runUpdateCommand(argv.slice(1));
+    } catch (err) {
+      process.stderr.write(`Error: ${(err as Error).message}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
   let parsed;
   try {
     parsed = parseCliArgs(argv);

package/src/embedded-prompts.ts

@@ -30,6 +30,7 @@ IMPORTANT: You must NEVER generate or guess URLs for the user unless you are con
  - Don't explain WHAT the code does, since well-named identifiers already do that. Don't reference the current task, fix, or callers ("used by X", "added for the Y flow", "handles the case from issue #123"), since those belong in the PR description and rot as the codebase evolves.
  - For UI or frontend changes, start the dev server and use the feature in a browser before reporting the task as complete. Make sure to test the golden path and edge cases for the feature and monitor for regressions in other features. Type checking and test suites verify code correctness, not feature correctness - if you can't test the UI, say so explicitly rather than claiming success.
  - Don't use feature flags or backwards-compatibility shims when you can just change the code.
+ - When reporting results, be accurate about what you verified vs. what you assumed. Distinguish between what you confirmed (ran a command, read a file) and what you believe but did not check. Do not assert assumptions as facts.
  - If the user asks for help or wants to give feedback inform them of the following:
   - /help: Get help with using Claude Code
   - To give feedback, users should report the issue at https://github.com/anthropics/claude-code/issues
@@ -71,12 +72,12 @@ In code: default to writing no comments. Never write multi-paragraph docstrings
   "base/session-guidance.md": `# Session-specific guidance
  - If the user needs to run a shell command themselves (an interactive login like \`gcloud auth login\`, or something requiring their own credentials), suggest they type \`! <command>\` — the \`!\` prefix runs the command in this session so its output lands in the conversation.
  - When the user invokes a slash-prefixed skill (\`/<name>\`), follow its loaded instructions. Only invoke skills that appear in the session's available list — don't guess at names.
- - For work that would otherwise crowd the main context — broad codebase searches, multi-file investigation, parallel research — delegate to a sub-agent when your toolkit supports them. The point is keeping the main conversation lean, not just offload. Use the Explore-style agent for read-only investigation when one is available; otherwise use your search tools directly. Don't duplicate searches a delegated agent is already doing.
+ - Use sub-agents to keep the main context lean. Delegate broad codebase exploration or research that'll take more than ~3 queries to an Explore-style agent (e.g. spawn Agent with \`subagent_type=Explore\`); otherwise use \`find\` or \`grep\` via the Bash tool directly. Don't duplicate searches a delegated agent is already doing.
  - If the user asks about "ultrareview" or how to run it, explain that /ultrareview launches a multi-agent cloud review of the current branch (or /ultrareview <PR#> for a GitHub PR). It is user-triggered and billed; you cannot launch it yourself. It needs a git repository (offer to "git init" if not in one); the no-arg form bundles the local branch and does not need a GitHub remote.
 `,
   "base/env.md": `# Environment
-You have been invoked in the following environment:
- - Primary working directory: {{CWD}}
+You have been invoked in the following environment: 
+ - Primary working directory: {{CWD}}{{WORKTREE_NOTICE}}
  - Is a git repository: {{IS_GIT}}
  - Platform: {{PLATFORM}}
  - Shell: {{SHELL}}
@@ -141,6 +142,8 @@ Read code before changing it. Understand what exists before proposing modificati
 
 When something fails, that's normal — it's information, not a setback. Read the error, check your assumptions, try a focused fix. Most bugs have a straightforward cause once you look at them calmly.
 
+When reporting results, be accurate about what you verified vs. what you assumed. Distinguish what you confirmed (ran a command, read a file) from what you believe but didn't check. Don't assert assumptions as facts.
+
 Write secure code. Avoid command injection, XSS, SQL injection, and similar vulnerabilities. If you spot insecure code you wrote, fix it. Use linters and skills to assist you as needed.
 
 For UI or frontend changes, start the dev server and test in a browser before reporting done. Test the golden path and edge cases, monitor for regressions. Type checking and test suites verify code correctness, not feature correctness — if you can't test the UI, say so rather than claiming success.
@@ -187,7 +190,7 @@ In code: default to no comments. Skip multi-paragraph docstrings and comment blo
 
 If a tool denial is confusing, ask the user why. If you need them to run an interactive command, suggest \`! <command>\` in the prompt.
 
-Using bash operations will require user input, which will slow our efforts. Prefer your specialized agents, like Read, instead of grep. Or Edit, instead of sed or awk. For broader exploration (more than ~3 queries), spawn the Explore agent.
+Using bash operations will require user input, which will slow our efforts. Prefer your specialized agents, like Read, instead of grep. Or Edit, instead of sed or awk. For broader exploration (more than ~3 queries), spawn Agent with \`subagent_type=Explore\`; otherwise use \`find\` or \`grep\` via Bash directly.
 
 Slash commands (e.g., /commit) invoke skills — use the Skill tool for those listed as user-invocable.
 
@@ -230,7 +233,7 @@ Read will work better than cat or grep. Using pgrep and echo for process monitor
 Reserve Bash for commands that genuinely need shell execution.
 `,
   "chill/env.md": `# Environment
-- Working directory: {{CWD}}
+- Working directory: {{CWD}}{{WORKTREE_NOTICE}}
 - Git repo: {{IS_GIT}}
 - Platform: {{PLATFORM}}
 - Shell: {{SHELL}}

package/src/env.ts

@@ -22,11 +22,15 @@ export function detectEnv(): EnvInfo {
   const cwd = process.cwd();
   const isGit = exec("git rev-parse --is-inside-work-tree") === "true";
 
+  let isWorktree = false;
   let gitBranch: string | null = null;
   let gitStatus: string | null = null;
   let gitLog: string | null = null;
 
   if (isGit) {
+    const gitDir = exec("git rev-parse --git-dir");
+    const commonDir = exec("git rev-parse --git-common-dir");
+    isWorktree = gitDir !== null && commonDir !== null && gitDir !== commonDir;
     gitBranch = exec("git branch --show-current");
     gitStatus = exec("git status --short");
     gitLog = exec("git log --oneline -5");
@@ -36,7 +40,7 @@ export function detectEnv(): EnvInfo {
   const shell = basename(process.env.SHELL || "bash");
   const osVersion = exec("uname -sr") ?? "unknown";
 
-  return { cwd, isGit, gitBranch, gitStatus, gitLog, platform, shell, osVersion };
+  return { cwd, isGit, isWorktree, gitBranch, gitStatus, gitLog, platform, shell, osVersion };
 }
 
 // Hardcoded model info — update when Claude Code updates
@@ -58,6 +62,10 @@ export function buildTemplateVars(env: EnvInfo): TemplateVars {
     gitStatusBlock = parts.join("\n");
   }
 
+  const worktreeNotice = env.isWorktree
+    ? "\n - This is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT `cd` to the original repository root."
+    : "";
+
   return {
     CWD: env.cwd,
     IS_GIT: env.isGit ? "true" : "false",
@@ -68,5 +76,6 @@ export function buildTemplateVars(env: EnvInfo): TemplateVars {
     MODEL_ID,
     KNOWLEDGE_CUTOFF,
     GIT_STATUS: gitStatusBlock,
+    WORKTREE_NOTICE: worktreeNotice,
   };
 }

package/src/types.ts

@@ -71,6 +71,7 @@ export interface ModeConfig {
 export interface EnvInfo {
   cwd: string;
   isGit: boolean;
+  isWorktree: boolean;
   gitBranch: string | null;
   gitStatus: string | null;
   gitLog: string | null;
@@ -90,6 +91,7 @@ export interface TemplateVars {
   MODEL_ID: string;
   KNOWLEDGE_CUTOFF: string;
   GIT_STATUS: string;
+  WORKTREE_NOTICE: string;
 }
 
 export interface AssembleOptions {

package/src/update.ts

@@ -0,0 +1,467 @@
+import { writeFileSync, chmodSync, renameSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { VERSION } from "./version.js";
+import { BUILD_INFO, type BuildInfo } from "./build-info.js";
+
+// ----------------------------------------------------------------------
+// Constants
+// ----------------------------------------------------------------------
+
+/** Upstream repo slug — also referenced by install.sh and the release workflow. */
+const UPSTREAM_REPO = "nklisch/claude-code-modes";
+
+/** Normalized form of the upstream remote URL captured by build-info. */
+const UPSTREAM_REPO_URL = "https://github.com/nklisch/claude-code-modes.git";
+
+const USER_AGENT = `claude-mode/${VERSION}`;
+
+const GITHUB_API_BASE = "https://api.github.com";
+
+/** Basenames of interpreter runtimes — signals we're running from source. */
+const SOURCE_EXEC_NAMES = new Set(["bun", "bun-debug", "node"]);
+
+// ----------------------------------------------------------------------
+// Public types
+// ----------------------------------------------------------------------
+
+export interface UpdateOptions {
+  check: boolean;
+  force: boolean;
+  dryRun: boolean;
+  /** Positional version: "0.2.5" or "v0.2.5"; null for "latest". */
+  targetTag: string | null;
+}
+
+export type InstallClassification =
+  | { kind: "source"; reason: string }
+  | { kind: "dirty"; reason: string }
+  | { kind: "fork"; reason: string }
+  | { kind: "release"; binaryPath: string };
+
+export interface ReleaseAsset {
+  name: string;
+  url: string;
+}
+
+export interface ReleaseInfo {
+  /** "v0.2.8" — exact tag from GitHub. */
+  tag: string;
+  /** "0.2.8" — tag with leading "v" stripped, comparable to package.json. */
+  version: string;
+  assets: ReleaseAsset[];
+}
+
+export interface PlatformArtifact {
+  binary: ReleaseAsset;
+  checksums: ReleaseAsset;
+  /** "claude-mode-linux-x64" etc. */
+  artifactName: string;
+}
+
+export type UpdateAction = "install" | "no-op" | "downgrade" | "reinstall";
+
+export interface UpdatePlan {
+  current: string;
+  target: string;
+  tag: string;
+  artifact: PlatformArtifact;
+  binaryPath: string;
+  action: UpdateAction;
+}
+
+/** Injectable transport — default uses global fetch; tests inject a fake. */
+export interface UpdateTransport {
+  fetchJson(url: string): Promise<unknown>;
+  fetchBytes(url: string): Promise<Uint8Array>;
+  fetchText(url: string): Promise<string>;
+}
+
+// ----------------------------------------------------------------------
+// Default transport
+// ----------------------------------------------------------------------
+
+async function apiFetch(url: string): Promise<Response> {
+  const res = await fetch(url, {
+    redirect: "follow",
+    headers: { "User-Agent": USER_AGENT },
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} fetching ${url}`);
+  }
+  return res;
+}
+
+export const defaultTransport: UpdateTransport = {
+  async fetchJson(url: string): Promise<unknown> {
+    const res = await apiFetch(url);
+    return res.json();
+  },
+  async fetchBytes(url: string): Promise<Uint8Array> {
+    const res = await apiFetch(url);
+    const buf = await res.arrayBuffer();
+    return new Uint8Array(buf);
+  },
+  async fetchText(url: string): Promise<string> {
+    const res = await apiFetch(url);
+    return res.text();
+  },
+};
+
+// ----------------------------------------------------------------------
+// Public API — pure helpers
+// ----------------------------------------------------------------------
+
+/** Parses argv (after "update" has been stripped). Throws on unknown flags. */
+export function parseUpdateArgs(argv: string[]): UpdateOptions {
+  const opts: UpdateOptions = { check: false, force: false, dryRun: false, targetTag: null };
+
+  for (const arg of argv) {
+    if (arg === "--check") {
+      opts.check = true;
+    } else if (arg === "--force") {
+      opts.force = true;
+    } else if (arg === "--dry-run") {
+      opts.dryRun = true;
+    } else if (arg.startsWith("--")) {
+      throw new Error(`Unknown flag: ${arg}`);
+    } else {
+      // Positional argument (version tag)
+      if (opts.targetTag !== null) {
+        throw new Error(`Unexpected argument: ${arg}`);
+      }
+      opts.targetTag = arg;
+    }
+  }
+
+  return opts;
+}
+
+/** Determines whether the running binary is safe to self-update. Pure. */
+export function classifyInstall(
+  execPath: string = process.execPath,
+  buildInfo: BuildInfo = BUILD_INFO,
+): InstallClassification {
+  // 1. Runtime interpreter → source mode
+  if (SOURCE_EXEC_NAMES.has(basename(execPath))) {
+    return {
+      kind: "source",
+      reason: `Running as ${basename(execPath)} runtime (source mode)`,
+    };
+  }
+
+  // 2. Dirty working tree → dev build
+  if (buildInfo.dirty === true) {
+    return {
+      kind: "dirty",
+      reason: "Binary was built from a dirty working tree",
+    };
+  }
+
+  // 3. Non-upstream repo → fork build
+  if (buildInfo.repo && buildInfo.repo !== UPSTREAM_REPO_URL) {
+    return {
+      kind: "fork",
+      reason: `Binary was built from a fork: ${buildInfo.repo}`,
+    };
+  }
+
+  // 4. Otherwise → safe to update
+  return { kind: "release", binaryPath: execPath };
+}
+
+/** Maps process.platform/process.arch → release artifact name. Throws on unsupported. */
+export function detectArtifactName(
+  platformVal: string = process.platform,
+  archVal: string = process.arch,
+): string {
+  const SUPPORTED_PLATFORMS = ["linux", "darwin"] as const;
+  const SUPPORTED_ARCHES = ["x64", "arm64"] as const;
+
+  type SupportedPlatform = (typeof SUPPORTED_PLATFORMS)[number];
+  type SupportedArch = (typeof SUPPORTED_ARCHES)[number];
+
+  if (!(SUPPORTED_PLATFORMS as readonly string[]).includes(platformVal)) {
+    throw new Error(
+      `Unsupported platform: "${platformVal}". ` +
+      `claude-mode update only supports: ${SUPPORTED_PLATFORMS.join(", ")}.`,
+    );
+  }
+  if (!(SUPPORTED_ARCHES as readonly string[]).includes(archVal)) {
+    throw new Error(
+      `Unsupported architecture: "${archVal}". ` +
+      `claude-mode update only supports: ${SUPPORTED_ARCHES.join(", ")}.`,
+    );
+  }
+
+  const platform = platformVal as SupportedPlatform;
+  const arch = archVal as SupportedArch;
+  return `claude-mode-${platform}-${arch}`;
+}
+
+/** Hits GET /repos/{repo}/releases/latest. */
+export async function fetchLatestRelease(transport: UpdateTransport): Promise<ReleaseInfo> {
+  const url = `${GITHUB_API_BASE}/repos/${UPSTREAM_REPO}/releases/latest`;
+  const data = await transport.fetchJson(url);
+  return parseReleaseJson(data);
+}
+
+/** Hits GET /repos/{repo}/releases/tags/v{tag}. Accepts "0.2.5" or "v0.2.5". */
+export async function fetchReleaseByTag(
+  tag: string,
+  transport: UpdateTransport,
+): Promise<ReleaseInfo> {
+  const normalizedTag = tag.startsWith("v") ? tag : `v${tag}`;
+  const url = `${GITHUB_API_BASE}/repos/${UPSTREAM_REPO}/releases/tags/${normalizedTag}`;
+  try {
+    const data = await transport.fetchJson(url);
+    return parseReleaseJson(data);
+  } catch (err) {
+    throw new Error(`Could not find release ${normalizedTag}: ${(err as Error).message}`);
+  }
+}
+
+/** Picks the binary asset and checksums.txt from a release. Throws if either is missing. */
+export function selectArtifact(release: ReleaseInfo, artifactName: string): PlatformArtifact {
+  const binary = release.assets.find((a) => a.name === artifactName);
+  const checksums = release.assets.find((a) => a.name === "checksums.txt");
+
+  if (!binary) {
+    const available = release.assets.map((a) => a.name).join(", ");
+    throw new Error(
+      `Could not find binary "${artifactName}" in release ${release.tag}. ` +
+      `Available assets: ${available}`,
+    );
+  }
+  if (!checksums) {
+    throw new Error(
+      `Could not find "checksums.txt" in release ${release.tag}. ` +
+      `Available assets: ${release.assets.map((a) => a.name).join(", ")}`,
+    );
+  }
+
+  return { binary, checksums, artifactName };
+}
+
+/** Reads "<sha256>  <filename>" lines and returns the hash for artifactName. */
+export function parseChecksum(text: string, artifactName: string): string {
+  const lines = text.split("\n");
+  for (const line of lines) {
+    const match = line.match(/^([0-9a-f]{64})\s+\*?(.+)$/i);
+    if (match && match[2].trim() === artifactName) {
+      return match[1].toLowerCase();
+    }
+  }
+  throw new Error(`Could not find checksum for "${artifactName}" in checksums.txt`);
+}
+
+/** Returns lowercase hex SHA-256 of data. */
+export function computeSha256(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex").toLowerCase();
+}
+
+/** Throws Error with expected/actual hashes if they don't match. */
+export function verifyChecksum(data: Uint8Array, expected: string): void {
+  const actual = computeSha256(data);
+  if (actual !== expected.toLowerCase()) {
+    throw new Error(
+      `Checksum mismatch!\n` +
+      `  Expected: ${expected.toLowerCase()}\n` +
+      `  Actual:   ${actual}`,
+    );
+  }
+}
+
+/** Numeric compare of "X.Y.Z" strings. -1 / 0 / 1. */
+export function compareSemver(a: string, b: string): number {
+  const parseVer = (v: string): number[] =>
+    v.replace(/^v/, "").split(".").map((n) => parseInt(n, 10));
+
+  const aParts = parseVer(a);
+  const bParts = parseVer(b);
+
+  for (let i = 0; i < 3; i++) {
+    const diff = (aParts[i] ?? 0) - (bParts[i] ?? 0);
+    if (diff < 0) return -1;
+    if (diff > 0) return 1;
+  }
+  return 0;
+}
+
+/** Picks the action given current, target, and --force. */
+export function computeAction(
+  current: string,
+  target: string,
+  force: boolean,
+): UpdateAction {
+  if (force) return "reinstall";
+  const cmp = compareSemver(current, target);
+  if (cmp === 0) return "no-op";
+  if (cmp < 0) return "install";
+  return "downgrade";
+}
+
+/**
+ * Atomic install: write to "<binaryPath>.new", chmod 0755, drop macOS
+ * quarantine xattr (best-effort), rename over binaryPath.
+ */
+export function installBinary(
+  data: Uint8Array,
+  target: { binaryPath: string; isDarwin: boolean },
+): void {
+  const stagingPath = `${target.binaryPath}.new`;
+  writeFileSync(stagingPath, data);
+  chmodSync(stagingPath, 0o755);
+
+  if (target.isDarwin) {
+    try {
+      execSync(`xattr -d com.apple.quarantine "${stagingPath}" 2>/dev/null`, { stdio: "ignore" });
+    } catch {
+      // Best-effort — missing xattr attribute is normal
+    }
+  }
+
+  renameSync(stagingPath, target.binaryPath);
+}
+
+// ----------------------------------------------------------------------
+// Orchestrator internals (unexported)
+// ----------------------------------------------------------------------
+
+function guidanceFor(kind: "source" | "dirty" | "fork"): string {
+  if (kind === "source") {
+    return "To update, use: git pull && bun install";
+  }
+  if (kind === "dirty") {
+    return "Commit or stash your changes, build a clean binary, then run update.";
+  }
+  // fork
+  return "Update via your fork's release process.";
+}
+
+function printDryRunPlan(plan: UpdatePlan): void {
+  process.stdout.write(`Dry-run plan:\n`);
+  process.stdout.write(`  Action:         ${plan.action}\n`);
+  process.stdout.write(`  Current:        ${plan.current}\n`);
+  process.stdout.write(`  Target:         ${plan.target} (${plan.tag})\n`);
+  process.stdout.write(`  Binary URL:     ${plan.artifact.binary.url}\n`);
+  process.stdout.write(`  Checksums URL:  ${plan.artifact.checksums.url}\n`);
+  process.stdout.write(`  Artifact:       ${plan.artifact.artifactName}\n`);
+  process.stdout.write(`  Install path:   ${plan.binaryPath}\n`);
+  process.stdout.write(`  (No changes written)\n`);
+}
+
+async function executePlan(plan: UpdatePlan, transport: UpdateTransport): Promise<void> {
+  // Fetch binary and checksums in parallel
+  const [binaryData, checksumsText] = await Promise.all([
+    transport.fetchBytes(plan.artifact.binary.url),
+    transport.fetchText(plan.artifact.checksums.url),
+  ]);
+
+  const expectedHash = parseChecksum(checksumsText, plan.artifact.artifactName);
+  verifyChecksum(binaryData, expectedHash);
+
+  installBinary(binaryData, {
+    binaryPath: plan.binaryPath,
+    isDarwin: process.platform === "darwin",
+  });
+}
+
+/** Parses a raw GitHub release API response into a ReleaseInfo. */
+function parseReleaseJson(data: unknown): ReleaseInfo {
+  const raw = data as Record<string, unknown>;
+  const tag = raw["tag_name"] as string;
+  const version = tag.startsWith("v") ? tag.slice(1) : tag;
+  const rawAssets = (raw["assets"] as Record<string, unknown>[]) ?? [];
+  const assets: ReleaseAsset[] = rawAssets.map((a) => ({
+    name: a["name"] as string,
+    url: a["browser_download_url"] as string,
+  }));
+  return { tag, version, assets };
+}
+
+// ----------------------------------------------------------------------
+// Orchestrator (public entry point)
+// ----------------------------------------------------------------------
+
+/**
+ * Orchestrates the whole update operation. argv excludes the leading
+ * "update" subcommand. Throws on any failure; cli.ts converts to stderr+exit.
+ */
+export async function runUpdateCommand(
+  argv: string[],
+  transport: UpdateTransport = defaultTransport,
+): Promise<void> {
+  // 1. Parse args
+  const opts = parseUpdateArgs(argv);
+
+  // 2. Classify install — refuse if not a release build
+  const classification = classifyInstall();
+  if (classification.kind !== "release") {
+    const guidance = guidanceFor(classification.kind);
+    throw new Error(
+      `Cannot self-update: ${classification.reason}.\n${guidance}`,
+    );
+  }
+  const binaryPath = classification.binaryPath;
+
+  // 3. Detect artifact name for this platform
+  const artifactName = detectArtifactName();
+
+  // 4. Fetch the target release
+  process.stdout.write("Checking for updates...\n");
+  const release = opts.targetTag
+    ? await fetchReleaseByTag(opts.targetTag, transport)
+    : await fetchLatestRelease(transport);
+
+  // 5. Compute action
+  const action = computeAction(VERSION, release.version, opts.force);
+
+  // 6. Print status
+  process.stdout.write(`Current: ${VERSION}\n`);
+  process.stdout.write(`Latest:  ${release.version}\n`);
+
+  // 7. --check: print human-readable status and return
+  if (opts.check) {
+    if (action === "no-op") {
+      process.stdout.write("Up to date.\n");
+    } else if (action === "install") {
+      process.stdout.write(`Update available: ${VERSION} -> ${release.version}\n`);
+    } else if (action === "downgrade") {
+      process.stdout.write(`Older version available: ${release.version} (current: ${VERSION})\n`);
+    } else {
+      // reinstall (--force + --check)
+      process.stdout.write(`Will reinstall: ${release.version}\n`);
+    }
+    return;
+  }
+
+  // 8. no-op without --force
+  if (action === "no-op") {
+    process.stdout.write("Already up to date.\n");
+    return;
+  }
+
+  // 9. Select the platform artifact
+  const artifact = selectArtifact(release, artifactName);
+
+  const plan: UpdatePlan = {
+    current: VERSION,
+    target: release.version,
+    tag: release.tag,
+    artifact,
+    binaryPath,
+    action,
+  };
+
+  // 10. --dry-run: print the plan and return
+  if (opts.dryRun) {
+    printDryRunPlan(plan);
+    return;
+  }
+
+  // 11. Execute
+  await executePlan(plan, transport);
+  process.stdout.write(`Installed claude-mode ${plan.target} at ${binaryPath}\n`);
+}

package/src/usage.ts

@@ -4,6 +4,13 @@ export function printUsage(): void {
 Subcommands:
   config            Manage configuration
   inspect [--print] Show prompt assembly plan with provenance and warnings
+  update [version]  Update the installed binary from GitHub Releases
+
+Update flags (passed after the "update" subcommand):
+  --check           Check for updates without installing
+  --force           Reinstall the same version (repair a corrupted install)
+  --dry-run         Show what would happen without writing anything
+  <version>         Install a specific release tag (e.g. "0.2.5"); default is latest
 
 Info:
   --version         Print claude-mode version and exit
@@ -58,7 +65,11 @@ Examples:
   claude-mode director                        # delegate to sub-agents
   claude-mode partner                         # equal-pair: speak plainly, TDD by default
   claude-mode create --modifier bold          # confident, idiomatic code
-  claude-mode create -- --verbose --model sonnet`;
+  claude-mode create -- --verbose --model sonnet
+  claude-mode update                          # update to the latest release
+  claude-mode update --check                  # check for updates without installing
+  claude-mode update 0.2.5                    # pin to a specific version (downgrade or reinstall)
+  claude-mode update --force                  # reinstall the same version (repair)`;
 
   process.stdout.write(usage + "\n");
 }