trekoon 0.4.1 → 0.4.3

package/src/commands/error-utils.ts

@@ -29,8 +29,46 @@ function readErrorMessage(error: unknown): string | null {
   return null;
 }
 
+// Keys whose values must never appear in surfaced error output.
+// Handles formats: key=val, key: val, key="val", 'key':'val', "key":"val",
+// Authorization: Bearer val, Authorization: Basic val.
+const SENSITIVE_KEY_PATTERN =
+  /(["']?)(token|secret|password|bearer|authorization|api[_-]?key|client[_-]?secret|private[_-]?key|cookie|session[_-]?id)(["']?\s*[:=]\s*(?:Bearer\s+|Basic\s+)?["']?)([^\s"',;&\]}{)<>]+)/giu;
+
+// Tag-style sensitive values: <key>value</key>.
+const SENSITIVE_TAG_PATTERN =
+  /(<\s*(token|secret|password|bearer|authorization|api[_-]?key|client[_-]?secret|private[_-]?key|cookie|session[_-]?id)\s*>)([^<]+)/giu;
+
+// Standalone "Bearer xyz" / "Basic xyz" anywhere in the message.
+// SENSITIVE_KEY_PATTERN runs first and consumes Authorization: Bearer/Basic forms; this
+// catches bare occurrences that remain (e.g. "got Bearer eyJ..." or "auth: Basic dXNl...").
+const STANDALONE_AUTH_SCHEME_PATTERN = /\b(Bearer|Basic)\s+([A-Za-z0-9._\-+/=]+)/giu;
+
+// JWT shape heuristic: three base64url segments separated by dots, each starting
+// with a base64url-encoded JSON header/payload/signature. The first two segments
+// of any JWT begin with "eyJ" because they encode JSON objects (`{"...`).
+// Catches bare JWTs that slip past the keyed and Bearer/Basic patterns above
+// (e.g. raw token pasted into an error message without an "Authorization:" prefix).
+const JWT_PATTERN = /\beyJ[A-Za-z0-9_\-]+\.eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+/gu;
+
+export function redactSensitive(input: string): string {
+  const keyRedacted = input.replace(
+    SENSITIVE_KEY_PATTERN,
+    (_match, open, key, sep) => `${open}${key}${sep}REDACTED`,
+  );
+  const tagRedacted = keyRedacted.replace(
+    SENSITIVE_TAG_PATTERN,
+    (_match, openTag) => `${openTag}REDACTED`,
+  );
+  const authRedacted = tagRedacted.replace(
+    STANDALONE_AUTH_SCHEME_PATTERN,
+    (_match, scheme) => `${scheme} REDACTED`,
+  );
+  return authRedacted.replace(JWT_PATTERN, "REDACTED");
+}
+
 function sanitizeErrorMessage(message: string): string {
-  const normalized = message.replace(/\s+/gu, " ").trim();
+  const normalized = redactSensitive(message.replace(/\s+/gu, " ").trim());
   if (normalized.length <= 240) {
     return normalized;
   }
@@ -109,3 +147,18 @@ export function safeErrorMessage(error: unknown, fallback: string): string {
   const message = readErrorMessage(error);
   return message === null ? fallback : sanitizeErrorMessage(message);
 }
+
+/**
+ * Redact a stack trace before logging. Routes the input through
+ * `redactSensitive` (the canonical secret-stripping pass) so absolute paths
+ * and any inline credentials are scrubbed. The function is intentionally
+ * shallow — additional heuristics (e.g. JWT shape detection) live in
+ * `redactSensitive` itself so future contributors only need to extend that
+ * single regex pipeline.
+ */
+export function redactStack(stack: string | undefined): string {
+  if (typeof stack !== "string" || stack.length === 0) {
+    return "";
+  }
+  return redactSensitive(stack);
+}

package/src/commands/help.ts

@@ -13,6 +13,7 @@ const ROOT_HELP = [
   "  --json       Structured JSON output",
   "  --toon       TOON-encoded output (preferred for agents)",
   "  --compat <mode>  Machine compatibility mode",
+  "  --daemon     (experimental) Route the call through trekoon serve over a Unix socket",
   "  --help       Show help for root or a command",
   "  --version    Print CLI version",
   "",
@@ -27,12 +28,13 @@ const ROOT_HELP = [
   "  subtask      Create, list, update, and search subtasks",
   "  dep          Manage dependency edges between tasks and subtasks",
   "  events       Prune old sync event log rows",
-  "  migrate      Check schema version or roll back migrations",
+  "  migrate      Check schema version, roll back migrations, or snapshot a backup",
   "  session      Agent orientation (diagnostics + sync + next task)",
   "  suggest      Priority-ranked next-action suggestions",
   "  sync         Pull events and resolve conflicts across branches",
   "  skills       Install, link, or update the Trekoon skill",
   "  update       Alias for skills update",
+  "  serve        (experimental) Run a long-lived daemon over a Unix socket",
 ].join("\n");
 
 const INIT_HELP = [
@@ -94,11 +96,18 @@ const BOARD_HELP = [
   "          and open the browser. Returns the board URL and a fallback URL.",
   "  update  Refresh board runtime assets only. No server, no browser.",
   "",
+  "Token visibility:",
+  "  By default the board token is redacted from machine output (shown as ****).",
+  "  Pass --reveal-token to print the raw token value.",
+  "    trekoon board open --reveal-token",
+  "  Treat the token like a password: it grants full board access over loopback.",
+  "",
   "Environment:",
   "  TREKOON_BOARD_ASSET_ROOT  Override the bundled asset source (tests/dev only).",
   "",
   "Examples:",
   "  trekoon board open",
+  "  trekoon board open --reveal-token",
   "  trekoon --json board update",
 ].join("\n");
 
@@ -106,13 +115,13 @@ const EPIC_HELP = [
   "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress|export> [options]",
   "",
   "Create:",
-  "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
-  "  trekoon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  trekoon --toon epic create --title \"...\" --description \"...\" [--status <status>]",
+  "  trekoon --toon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
   "  When the full tree is known, the second form creates everything in one shot",
   "  and returns mappings/counts. Same compact spec grammar as epic expand.",
   "",
   "Expand:",
-  "  trekoon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  trekoon --toon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
   "  --task <temp-key>|<title>|<description>|<status>",
   `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (${"@"}<temp-key> for new parents)`,
   `  --dep <source-ref>|<depends-on-ref>  (refs can be IDs or ${"@"}<temp-key>)`,
@@ -170,7 +179,7 @@ const EPIC_HELP = [
 ].join("\n");
 
 const TASK_HELP = [
-  "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete> [options]",
+  "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete|claim> [options]",
   "",
   "Create-many:",
   "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
@@ -216,10 +225,18 @@ const TASK_HELP = [
   "  Cascades atomically through descendant subtasks.",
   "  Blocked descendants abort the whole update. Only --status done|todo is supported.",
   "  Don't combine positional ID + --all with --ids, --append, --description, or --title.",
+  "",
+  "Claim:",
+  "  trekoon task claim <task-id> --owner <owner>",
+  "  Atomically claim a task using SQL compare-and-swap.",
+  "  Sets status=in_progress and owner=<owner> only when the task is todo or blocked",
+  "  and the owner field is NULL or already set to <owner>.",
+  "  Returns claimed (true|false), currentOwner, currentStatus, and the full task record on success.",
+  "  Two concurrent claim calls return exactly one claimed=true.",
 ].join("\n");
 
 const SUBTASK_HELP = [
-  "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete> [options]",
+  "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete|claim> [options]",
   "",
   "Create-many:",
   "  trekoon subtask create-many [<task-id>] [--task <task-id>] --subtask <spec> [--subtask <spec> ...]",
@@ -250,6 +267,14 @@ const SUBTASK_HELP = [
   "  trekoon subtask update <subtask-id> --all --status done|todo",
   "  Accepted for consistency, but just updates the one subtask (no descendants).",
   "  Don't combine positional ID + --all with --ids, --append, --description, or --title.",
+  "",
+  "Claim:",
+  "  trekoon subtask claim <subtask-id> --owner <owner>",
+  "  Atomically claim a subtask using SQL compare-and-swap.",
+  "  Sets status=in_progress and owner=<owner> only when the subtask is todo or blocked",
+  "  and the owner field is NULL or already set to <owner>.",
+  "  Returns claimed (true|false), currentOwner, currentStatus, and the full subtask record on success.",
+  "  Two concurrent claim calls return exactly one claimed=true.",
 ].join("\n");
 
 const DEP_HELP = [
@@ -292,16 +317,27 @@ const EVENTS_HELP = [
 ].join("\n");
 
 const MIGRATE_HELP = [
-  "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
+  "Usage: trekoon migrate <status|rollback|backup> [--to-version <n>] [--retain <n>]",
   "",
   "Subcommands:",
   "  status                Show current schema version, latest version, and pending count.",
   "  rollback [--to-version <n>]  Roll back migrations. Defaults to one version back.",
+  "  backup [--retain <n>] Snapshot .trekoon/trekoon.db to a timestamped sibling file",
+  "                        before any manual migration recovery.",
+  "                        --retain keeps the last n timestamped backups",
+  "                        (default 10); older siblings are pruned.",
+  "",
+  "Notes:",
+  "  Migrations 0004, 0005, and 0006 are irreversible (ALTER TABLE / data cleanup).",
+  "  Rolling back below those versions errors with code migration_down_unsupported.",
+  "  Take a backup first; restore by copying the backup over .trekoon/trekoon.db.",
   "",
   "Examples:",
   "  trekoon migrate status",
   "  trekoon migrate rollback",
   "  trekoon migrate rollback --to-version 1",
+  "  trekoon migrate backup",
+  "  trekoon migrate backup --retain 5",
 ].join("\n");
 
 const SYNC_HELP = [
@@ -405,8 +441,8 @@ const SUGGEST_HELP = [
 
 const SKILLS_HELP = [
   "Usage:",
-  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
-  "  trekoon skills install -g|--global [--editor opencode|claude|pi]",
+  "  trekoon skills install [--link --editor opencode|claude|codex|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills install -g|--global [--editor opencode|claude|codex|pi]",
   "  trekoon skills update",
   "",
   "Installs or refreshes the Trekoon skill so AI agents can plan and execute.",
@@ -415,7 +451,7 @@ const SKILLS_HELP = [
   "  Creates a symlink at .agents/skills/trekoon pointing to the bundled source,",
   "  so the skill always matches the installed CLI version.",
   "  --link            Also create an editor symlink named 'trekoon'.",
-  "  --editor <name>   Required with --link (opencode|claude|pi).",
+  "  --editor <name>   Required with --link (opencode|claude|codex|pi).",
   "  --to <path>       Override the symlink root for --link only.",
   "  --allow-outside-repo  Allow links outside the repo (requires --link).",
   "",
@@ -441,6 +477,34 @@ const SKILLS_HELP = [
   "  trekoon update",
 ].join("\n");
 
+const SERVE_HELP = [
+  "Usage: trekoon serve [--json|--toon]",
+  "",
+  "Status: EXPERIMENTAL spike. Not on by default. The default one-shot CLI",
+  "behavior is unchanged when this command is not running.",
+  "",
+  "Starts a foreground Trekoon daemon on a Unix-domain socket inside the",
+  "shared .trekoon directory. The daemon holds the SQLite connection and the",
+  "CLI shell in memory, so subsequent invocations skip Bun startup, module",
+  "load, and database open.",
+  "",
+  "Activate the client side with one of:",
+  "  TREKOON_DAEMON=1 trekoon session",
+  "  trekoon --daemon session",
+  "If the socket is missing or unreachable, the client transparently falls",
+  "back to the in-process one-shot path.",
+  "",
+  "Security:",
+  "  - Socket file mode is 0o600.",
+  "  - Parent .trekoon directory is forced to 0o700.",
+  "  - Stale sockets from prior crashes are cleaned up on start.",
+  "  - On Ctrl-C / SIGTERM the socket is unlinked.",
+  "",
+  "Examples:",
+  "  trekoon serve",
+  "  trekoon --daemon session",
+].join("\n");
+
 const COMMAND_HELP: Record<string, string> = {
   init: INIT_HELP,
   board: BOARD_HELP,
@@ -457,6 +521,7 @@ const COMMAND_HELP: Record<string, string> = {
   suggest: SUGGEST_HELP,
   skills: SKILLS_HELP,
   update: "Usage: trekoon update [--json|--toon]\n\nAlias for: trekoon skills update\n\nProbes and repairs all installed global and local skill symlinks.",
+  serve: SERVE_HELP,
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 

package/src/commands/migrate.ts

@@ -1,12 +1,18 @@
-import { parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+import { findUnknownOption, parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
 import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
+import { DomainError } from "../domain/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
+import { createMigrationBackup, DEFAULT_BACKUP_RETENTION } from "../storage/backup";
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 import { describeMigrations, rollbackDatabase } from "../storage/migrations";
 
-const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback> [--to-version <n>]";
+const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback|backup> [--to-version <n>] [--retain <n>]";
+
+const STATUS_OPTIONS: readonly string[] = [];
+const ROLLBACK_OPTIONS: readonly string[] = ["to-version"];
+const BACKUP_OPTIONS: readonly string[] = ["retain"];
 
 function usage(message: string): CliResult {
   return failResult({
@@ -20,6 +26,19 @@ function usage(message: string): CliResult {
   });
 }
 
+function unknownOptionResult(command: string, option: string): CliResult {
+  const message = `Unknown option --${option}.`;
+  return failResult({
+    command,
+    human: message,
+    data: { option: `--${option}` },
+    error: {
+      code: "unknown_option",
+      message,
+    },
+  });
+}
+
 function parseVersion(rawValue: string | undefined): number | null {
   if (rawValue === undefined) {
     return null;
@@ -40,19 +59,107 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
     return usage("Missing migrate subcommand.");
   }
 
-  const missingOption = readMissingOptionValue(parsed.missingOptionValues, "to-version");
-  if (missingOption !== undefined) {
-    return failResult({
-      command: "migrate",
-      human: `Option --${missingOption} requires a value.`,
-      data: {
-        option: missingOption,
-      },
-      error: {
-        code: "invalid_input",
-        message: `Option --${missingOption} requires a value.`,
-      },
-    });
+  for (const optionName of ["to-version", "retain"] as const) {
+    const missingOption = readMissingOptionValue(parsed.missingOptionValues, optionName);
+    if (missingOption !== undefined) {
+      return failResult({
+        command: "migrate",
+        human: `Option --${missingOption} requires a value.`,
+        data: {
+          option: missingOption,
+        },
+        error: {
+          code: "invalid_input",
+          message: `Option --${missingOption} requires a value.`,
+        },
+      });
+    }
+  }
+
+  // The backup subcommand never opens the live DB through the standard
+  // openTrekoonDatabase pathway: backups must work even when the DB is
+  // in a partially-migrated or otherwise diagnostic-blocked state.
+  if (subcommand === "backup") {
+    const unknown = findUnknownOption(parsed, BACKUP_OPTIONS);
+    if (unknown !== undefined) {
+      return unknownOptionResult("migrate.backup", unknown);
+    }
+
+    const retainRaw: string | undefined = readOption(parsed.options, "retain");
+    let retain: number = DEFAULT_BACKUP_RETENTION;
+    if (retainRaw !== undefined) {
+      if (!/^\d+$/.test(retainRaw)) {
+        return failResult({
+          command: "migrate.backup",
+          human: "--retain must be a positive integer.",
+          data: { option: "retain" },
+          error: {
+            code: "invalid_input",
+            message: "--retain must be a positive integer.",
+          },
+        });
+      }
+
+      const parsedRetain: number = Number.parseInt(retainRaw, 10);
+      if (parsedRetain < 1) {
+        return failResult({
+          command: "migrate.backup",
+          human: "--retain must be at least 1 (the new backup itself).",
+          data: { option: "retain" },
+          error: {
+            code: "invalid_input",
+            message: "--retain must be at least 1 (the new backup itself).",
+          },
+        });
+      }
+
+      retain = parsedRetain;
+    }
+
+    try {
+      const result = createMigrationBackup({ cwd: context.cwd, retain });
+      return okResult({
+        command: "migrate.backup",
+        human: [
+          `Backed up Trekoon database to ${result.backupPath}`,
+          `Bytes: ${result.bytes}`,
+          `Schema version at backup: ${result.migrationVersion} of ${result.latestVersion}`,
+          `Retained backups: ${result.retainedCount} (pruned ${result.prunedPaths.length})`,
+        ].join("\n"),
+        data: {
+          backupPath: result.backupPath,
+          bytes: result.bytes,
+          migrationVersion: result.migrationVersion,
+          latestVersion: result.latestVersion,
+          timestamp: result.timestamp,
+          retain,
+          retainedCount: result.retainedCount,
+          prunedPaths: result.prunedPaths,
+        },
+      });
+    } catch (error: unknown) {
+      if (error instanceof DomainError) {
+        return failResult({
+          command: "migrate.backup",
+          human: error.message,
+          data: { code: error.code, ...(error.details ?? {}) },
+          error: { code: error.code, message: error.message },
+        });
+      }
+
+      const busyFailure = sqliteBusyFailure("migrate.backup", error);
+      if (busyFailure !== null) {
+        return busyFailure;
+      }
+
+      const message = safeErrorMessage(error, "Unknown backup failure.");
+      return failResult({
+        command: "migrate.backup",
+        human: message,
+        data: { reason: "backup_failed" },
+        error: { code: "backup_failed", message },
+      });
+    }
   }
 
   let storage: TrekoonDatabase | undefined;
@@ -60,6 +167,11 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
   try {
     storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
     if (subcommand === "status") {
+      const unknown = findUnknownOption(parsed, STATUS_OPTIONS);
+      if (unknown !== undefined) {
+        return unknownOptionResult("migrate.status", unknown);
+      }
+
       const status = describeMigrations(storage.db);
 
       return okResult({
@@ -74,6 +186,11 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
     }
 
     if (subcommand === "rollback") {
+      const unknown = findUnknownOption(parsed, ROLLBACK_OPTIONS);
+      if (unknown !== undefined) {
+        return unknownOptionResult("migrate.rollback", unknown);
+      }
+
       const status = describeMigrations(storage.db);
       const parsedVersion: number | null = parseVersion(readOption(parsed.options, "to-version"));
 
@@ -92,16 +209,28 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
       }
 
       const targetVersion: number = parsedVersion ?? Math.max(0, status.currentVersion - 1);
-      const summary = rollbackDatabase(storage.db, targetVersion);
+      try {
+        const summary = rollbackDatabase(storage.db, targetVersion);
 
-      return okResult({
-        command: "migrate.rollback",
-        human: [
-          `Rolled back ${summary.rolledBack} migration(s).`,
-          `From version ${summary.fromVersion} to ${summary.toVersion}.`,
-        ].join("\n"),
-        data: summary,
-      });
+        return okResult({
+          command: "migrate.rollback",
+          human: [
+            `Rolled back ${summary.rolledBack} migration(s).`,
+            `From version ${summary.fromVersion} to ${summary.toVersion}.`,
+          ].join("\n"),
+          data: summary,
+        });
+      } catch (error: unknown) {
+        if (error instanceof DomainError) {
+          return failResult({
+            command: "migrate.rollback",
+            human: error.message,
+            data: { code: error.code, ...(error.details ?? {}) },
+            error: { code: error.code, message: error.message },
+          });
+        }
+        throw error;
+      }
     }
 
     return usage(`Unknown migrate subcommand '${subcommand}'.`);

package/src/commands/quickstart.ts

@@ -57,9 +57,11 @@ const QUICKSTART_TEXT = [
   "  Filtered list:         trekoon --toon task list --status in_progress,todo --limit 20",
   "  Paginate:              trekoon --toon task list --cursor <n>",
   "  Bulk update:           trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
+  "  Atomic claim:          trekoon --toon task claim <task-id> --owner <owner>",
   "  Ready queue:           trekoon --toon task ready [--limit <n>] [--epic <id>]",
   "  Next candidate:        trekoon --toon task next [--epic <id>]",
   "  Export epic to MD:     trekoon --toon epic export <epic-id> [--path <path>] [--overwrite]",
+  "  Snapshot the DB:       trekoon --toon migrate backup",
   "",
   "6) List and view defaults",
   "  Default scope: open work (in_progress, todo), limit 10.",
@@ -153,7 +155,9 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task list --status in_progress,todo --limit 20",
         "trekoon --toon task list --cursor <n>",
         "trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
+        "trekoon --toon task claim <task-id> --owner <owner>",
         "trekoon --toon epic export <epic-id>",
+        "trekoon --toon migrate backup",
       ],
       machineExamples: [
         "trekoon --toon quickstart",
@@ -162,6 +166,7 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon suggest",
         "trekoon --toon epic progress <epic-id>",
         "trekoon --toon task done <task-id>",
+        "trekoon --toon task claim <task-id> --owner <owner>",
         "trekoon --toon task show <task-id> --all",
         "trekoon --toon epic show <epic-id> --all",
         "trekoon --toon sync status",
@@ -169,6 +174,8 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task next",
         "trekoon --toon dep reverse <task-or-subtask-id>",
         "trekoon --toon epic export <epic-id>",
+        "trekoon --toon migrate status",
+        "trekoon --toon migrate backup",
       ],
       wipeWarning: {
         command: "trekoon wipe --yes",

package/src/commands/skills.ts

@@ -10,11 +10,11 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 
 const SKILLS_USAGE = [
   "Usage:",
-  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
-  "  trekoon skills install -g|--global [--editor opencode|claude|pi]",
+  "  trekoon skills install [--link --editor opencode|claude|codex|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills install -g|--global [--editor opencode|claude|codex|pi]",
   "  trekoon skills update",
 ].join("\n");
-const EDITOR_NAMES = ["opencode", "claude", "pi"] as const;
+const EDITOR_NAMES = ["opencode", "claude", "codex", "pi"] as const;
 const ALLOW_OUTSIDE_REPO_FLAG = "allow-outside-repo";
 
 type EditorName = (typeof EDITOR_NAMES)[number];
@@ -88,6 +88,10 @@ function resolveLinkRoot(cwd: string, editor: EditorName, toOverride: string | u
     return join(cwd, ".claude", "skills");
   }
 
+  if (editor === "codex") {
+    return join(cwd, ".codex", "skills");
+  }
+
   return join(cwd, ".pi", "skills");
 }
 
@@ -222,6 +226,10 @@ function resolveEditorConfigDir(cwd: string, editor: EditorName): string {
     return join(cwd, ".claude");
   }
 
+  if (editor === "codex") {
+    return join(cwd, ".codex");
+  }
+
   return join(cwd, ".pi");
 }
 
@@ -235,6 +243,10 @@ function resolveGlobalEditorSkillsDir(editor: EditorName): string {
     return join(home, ".claude", "skills");
   }
 
+  if (editor === "codex") {
+    return join(home, ".codex", "skills");
+  }
+
   return join(home, ".pi", "skills");
 }
 
@@ -542,7 +554,7 @@ function runSkillsInstall(context: CliContext): CliResult {
 
   // Validate editor early (shared by both modes).
   if (rawEditor !== undefined && !EDITOR_NAMES.includes(rawEditor as EditorName)) {
-    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude, pi", {
+    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude, codex, pi", {
       editor: rawEditor,
       allowedEditors: EDITOR_NAMES,
     });
@@ -588,7 +600,7 @@ function runSkillsInstall(context: CliContext): CliResult {
   }
 
   if (wantsLink && rawEditor === undefined) {
-    return invalidArgs("skills install --link requires --editor opencode|claude|pi.");
+    return invalidArgs("skills install --link requires --editor opencode|claude|codex|pi.");
   }
 
   const editor: EditorName | undefined = rawEditor as EditorName | undefined;