portable-agent-layer 0.15.1 → 0.17.0

package/README.md

@@ -2,7 +2,7 @@
 
 A cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge.
 
-PAL lets you carry your agent context across **Windows**, **macOS**, and **Linux**, and work across different agent runtimes and interfaces such as **Claude** and **OpenCode**. Its core idea is simple: your knowledge and workflows should belong to **you**, not to a single machine, tool, or vendor.
+PAL lets you carry your agent context across **Windows**, **macOS**, and **Linux**, and work across different agent runtimes and interfaces such as **Claude Code**, **opencode**, **Cursor**, and **Codex**. Its core idea is simple: your knowledge and workflows should belong to **you**, not to a single machine, tool, or vendor.
 
 > Inspired in part by [Daniel Miessler](https://danielmiessler.com)'s work on [Personal AI Infrastructure](https://github.com/danielmiessler/Personal_AI_Infrastructure). PAL is an independent open-source implementation focused on portability across platforms and agents. It is not affiliated with or endorsed by Daniel Miessler.
 
@@ -33,7 +33,7 @@ With PAL, you can:
 > **Bun is required.** PAL is built on [Bun](https://bun.sh) and will not work with Node.js or other runtimes. Install it with `curl -fsSL https://bun.sh/install | bash`.
 
 - [Bun](https://bun.sh) >= 1.3.0
-- At least one of: [Claude Code](https://claude.ai/code) or [opencode](https://opencode.ai)
+- At least one of: [Claude Code](https://claude.ai/code), [opencode](https://opencode.ai), [Cursor](https://cursor.com), or [Codex](https://openai.com/index/introducing-codex/)
 
 ### Package mode (recommended)
 
@@ -90,9 +90,19 @@ pal cli status        # check your setup
 ```bash
 pal cli install --claude      # Claude Code only
 pal cli install --opencode    # opencode only
-pal cli install               # both (default)
+pal cli install --cursor      # Cursor only
+pal cli install               # all available (default)
 ```
 
+### Supported agents
+
+| Agent | Support | Skills | Hooks | AGENTS.md | Subagents |
+|-------|---------|--------|-------|-----------|-----------|
+| Claude Code | Full | Yes | Yes | Yes | Yes |
+| opencode | Full | Yes | Yes (plugin) | Yes | Yes |
+| Cursor | Full | Yes | Yes | Yes (injected via hook) | Yes |
+| Codex | Partial | Yes | No | Yes | No |
+
 ---
 
 ## Environment variables
@@ -112,6 +122,8 @@ pal cli install               # both (default)
 | `PAL_PKG` | Override package root |
 | `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |
 | `PAL_OPENCODE_DIR` | Override opencode config dir (default: `~/.config/opencode`) |
+| `PAL_CURSOR_DIR` | Override Cursor config dir (default: `~/.cursor`) |
+| `PAL_CODEX_DIR` | Override Codex config dir (default: `~/.codex`) |
 | `PAL_AGENTS_DIR` | Override agents dir (default: `~/.agents`) |
 
 ---
@@ -160,7 +172,7 @@ Your setup should be able to travel with you.
 ## Features
 
 - **Cross-platform**: works on Windows, macOS, and Linux
-- **Cross-agent**: designed to work across multiple agent ecosystems
+- **Cross-agent**: full support for Claude Code, opencode, and Cursor; partial support for Codex
 - **Portable knowledge**: export and import accumulated knowledge
 - **TypeScript-first**: built in TypeScript from day one
 - **Open source**: hackable, inspectable, extensible

package/assets/templates/AGENTS.md.template

@@ -19,7 +19,7 @@ Your first output MUST be the mode header. No freeform output. No skipping this
 For greetings and brief acknowledgments only.
 
 ```
-══════════════ PAL ══════════════
+══════ PAL ══════
 🗣️ {{IDENTITY_NAME}}: [response]
 ```
 
@@ -28,7 +28,7 @@ For greetings and brief acknowledgments only.
 FOR: Simple tasks that won't take much effort or time. More advanced tasks use ALGORITHM below.
 
 ```
-══════════════ PAL | NATIVE ══════════════
+══════ PAL | NATIVE ══════
 🗒️ TASK: [brief description]
 [work]
 🔄 ITERATION on: [16 words of context if this is a follow-up]
@@ -47,7 +47,7 @@ FOR: Multi-step, complex, or difficult work. Troubleshooting, debugging, buildin
 **MANDATORY FIRST ACTION:** Read `~/.agents/PAL/ALGORITHM.md` and follow its instructions exactly.
 
 Start your response with the following header in this mode:
-══════════════ PAL | ALGORITHM ══════════════
+══════ PAL | ALGORITHM ══════
 
 ---
 

package/assets/templates/PAL/README.md

@@ -1,12 +1,12 @@
 # PAL — Portable Agent Layer
 
-PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge. It runs inside any compatible AI coding agent (Claude Code, opencode) as an interconnected set of skills, hooks, tools, memory, and configuration — all orchestrated by The Algorithm.
+PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge. It runs inside any compatible AI coding agent (Claude Code, opencode, Cursor, Codex) as an interconnected set of skills, hooks, tools, memory, and configuration — all orchestrated by The Algorithm.
 
 ## How It Works
 
 **CLAUDE.md** (or the agent equivalent) is the entry point — generated from a template by the CLI installer. It defines execution modes, The Algorithm routing, and the context routing table. The agent loads it natively every session. A SessionStart hook keeps it fresh automatically.
 
-**The PAL home directory (`~/.agents/PAL/`)** contains all system documentation, user context (TELOS), and routing files. The rest of the system lives in the PAL package (`src/`) and the agent's config directory (`~/.claude/` or `~/.config/opencode/`).
+**The PAL home directory (`~/.agents/PAL/`)** contains all system documentation, user context (TELOS), and routing files. The rest of the system lives in the PAL package (`src/`) and the agent's config directory (`~/.claude/`, `~/.config/opencode/`, `~/.cursor/`, or `~/.codex/`).
 
 ## Directory Structure
 
@@ -29,7 +29,7 @@ PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows
     hooks/                         # Session lifecycle hooks
       handlers/                    # Individual stop/prompt handlers
       lib/                         # Shared utilities
-    targets/                       # Agent-specific installers (Claude, opencode)
+    targets/                       # Agent-specific installers (Claude, opencode, Cursor)
     tools/                         # Standalone CLI tools
   assets/
     skills/                        # Bundled skills (16+)
@@ -104,6 +104,7 @@ pal                          # Start agent session with auto-summary on exit
 pal cli init                 # Scaffold PAL home + install hooks
 pal cli install [--claude]   # Register hooks/skills for Claude Code
 pal cli install [--opencode] # Register hooks/skills for opencode
+pal cli install [--cursor]   # Register hooks/skills for Cursor
 pal cli uninstall            # Remove hooks/skills
 pal cli status               # Show configuration
 pal cli doctor               # Check prerequisites and health
@@ -116,8 +117,8 @@ pal cli update               # Update PAL
 
 PAL is designed to work identically across:
 - **Platforms:** macOS, Linux, Windows
-- **Agents:** Claude Code, opencode (and future tools)
-- **Environment overrides:** `PAL_HOME`, `PAL_PKG`, `PAL_CLAUDE_DIR`, `PAL_OPENCODE_DIR`, `PAL_AGENTS_DIR`
+- **Agents:** Claude Code (full), opencode (full), Cursor (full), Codex (partial — AGENTS.md and skills only, no hooks or subagents)
+- **Environment overrides:** `PAL_HOME`, `PAL_PKG`, `PAL_CLAUDE_DIR`, `PAL_OPENCODE_DIR`, `PAL_CURSOR_DIR`, `PAL_CODEX_DIR`, `PAL_AGENTS_DIR`
 
 ## Extending PAL
 

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -433,9 +433,14 @@ src/targets/
 │   ├── install.ts   # Register hooks + skills in opencode config
 │   ├── uninstall.ts
 │   └── plugin.ts    # opencode plugin interface
+├── cursor/          # Cursor specific
+│   ├── install.ts   # Register hooks + skills in ~/.cursor/
+│   └── uninstall.ts
 └── lib.ts           # Shared: JSON read/write, settings merge, TELOS scaffold
 ```
 
+Codex support is partial — AGENTS.md is symlinked to `~/.codex/AGENTS.md` automatically (no dedicated target installer needed).
+
 ### Path Resolution
 
 All paths resolve through `src/hooks/lib/paths.ts`:
@@ -446,6 +451,8 @@ All paths resolve through `src/hooks/lib/paths.ts`:
 | PAL package | Auto-detected from source | `PAL_PKG` |
 | Claude config | `~/.claude` | `PAL_CLAUDE_DIR` |
 | opencode config | `~/.config/opencode` | `PAL_OPENCODE_DIR` |
+| Cursor config | `~/.cursor` | `PAL_CURSOR_DIR` |
+| Codex config | `~/.codex` | `PAL_CODEX_DIR` |
 | Agents dir | `~/.agents` | `PAL_AGENTS_DIR` |
 
 ### Portability Contract

package/assets/templates/hooks.cursor.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+      }
+    ],
+    "preToolUse": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+      },
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      }
+    ],
+    "stop": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -8,8 +8,8 @@
  *
  * Admin commands (pal cli ...):
  *   init                              Scaffold PAL home, install hooks for all targets
- *   install [--claude] [--opencode]   Register hooks/skills for targets
- *   uninstall [--claude] [--opencode] Remove hooks/skills for targets
+ *   install [--claude] [--opencode] [--cursor]   Register hooks/skills for targets
+ *   uninstall [--claude] [--opencode] [--cursor] Remove hooks/skills for targets
  *   update                             Update PAL (git pull or npm update)
  *   export [path] [--dry-run]         Export user state to zip
  *   import [path] [--dry-run]         Import user state from zip
@@ -197,9 +197,9 @@ function showHelp() {
     pal cli <command> [options]             Admin commands
 
   Admin commands:
-    pal cli init [--claude] [--opencode]    Scaffold and install (default: all)
-    pal cli install [--claude] [--opencode] Register hooks for targets
-    pal cli uninstall [--claude] [--opencode] Remove hooks for targets
+    pal cli init [--claude] [--opencode] [--cursor]    Scaffold and install (default: all)
+    pal cli install [--claude] [--opencode] [--cursor] Register hooks for targets
+    pal cli uninstall [--claude] [--opencode] [--cursor] Remove hooks for targets
     pal cli update                          Update PAL (git pull or npm update)
     pal cli export [path] [--dry-run]       Export state to zip
     pal cli import [path] [--dry-run]       Import state from zip
@@ -211,6 +211,7 @@ function showHelp() {
     PAL_PKG               Override package root
     PAL_CLAUDE_DIR        Override Claude config dir (default: ~/.claude)
     PAL_OPENCODE_DIR      Override opencode config dir (default: ~/.config/opencode)
+    PAL_CURSOR_DIR        Override Cursor config dir (default: ~/.cursor)
     PAL_AGENTS_DIR        Override agents dir (default: ~/.agents)
 `);
 }
@@ -218,30 +219,35 @@ function showHelp() {
 function parseTargets(args: string[]): {
   claude: boolean;
   opencode: boolean;
+  cursor: boolean;
 } {
   let claude = false;
   let opencode = false;
+  let cursor = false;
   for (const arg of args) {
     if (arg === "--claude") claude = true;
     else if (arg === "--opencode") opencode = true;
+    else if (arg === "--cursor") cursor = true;
     else if (arg === "--all") {
       claude = true;
       opencode = true;
+      cursor = true;
     }
   }
-  if (!claude && !opencode) return { claude: true, opencode: true };
-  return { claude, opencode };
+  if (!claude && !opencode && !cursor)
+    return { claude: true, opencode: true, cursor: true };
+  return { claude, opencode, cursor };
 }
 
 /** Resolve targets against available agents. Errors if explicitly requested but missing. */
 function resolveTargets(
   args: string[],
   health?: DoctorResult
-): { claude: boolean; opencode: boolean } {
+): { claude: boolean; opencode: boolean; cursor: boolean } {
   const requested = parseTargets(args);
   const h = health || doctor(true);
   const explicit = args.some(
-    (a) => a === "--claude" || a === "--opencode" || a === "--all"
+    (a) => a === "--claude" || a === "--opencode" || a === "--cursor" || a === "--all"
   );
 
   if (explicit) {
@@ -254,6 +260,10 @@ function resolveTargets(
       log.error("opencode is not installed. Run 'pal cli doctor' for details.");
       process.exit(1);
     }
+    if (requested.cursor && !h.cursor.available) {
+      log.error("Cursor is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
     return requested;
   }
 
@@ -261,10 +271,12 @@ function resolveTargets(
   const targets = {
     claude: h.claude.available,
     opencode: h.opencode.available,
+    cursor: h.cursor.available,
   };
 
   if (!targets.claude) log.info("Skipping Claude Code (not installed)");
   if (!targets.opencode) log.info("Skipping opencode (not installed)");
+  if (!targets.cursor) log.info("Skipping Cursor (not installed)");
 
   return targets;
 }
@@ -312,6 +324,7 @@ interface DoctorResult {
   bun: ToolCheck;
   claude: ToolCheck;
   opencode: ToolCheck;
+  cursor: ToolCheck;
   hasAgent: boolean;
 }
 
@@ -322,6 +335,7 @@ function doctor(silent = false): DoctorResult {
       bun: { name: "bun", available: true, version: Bun.version },
       claude: { name: "claude", available: true },
       opencode: { name: "opencode", available: true },
+      cursor: { name: "cursor", available: true },
       hasAgent: true,
     };
   }
@@ -329,7 +343,8 @@ function doctor(silent = false): DoctorResult {
   const bun = { name: "bun", available: true, version: Bun.version };
   const claude = checkTool("claude");
   const opencode = checkTool("opencode");
-  const hasAgent = claude.available || opencode.available;
+  const cursor = checkTool("cursor");
+  const hasAgent = claude.available || opencode.available || cursor.available;
 
   const home = palHome();
   const isRepo = existsSync(resolve(palPkg(), ".palroot"));
@@ -355,6 +370,9 @@ function doctor(silent = false): DoctorResult {
     opencode.available
       ? ok(`opencode ${opencode.version || ""}`.trim())
       : fail("opencode — not found");
+    cursor.available
+      ? ok(`Cursor ${cursor.version || ""}`.trim())
+      : fail("Cursor — not found");
     ok(`PAL home: ${home} (${isRepo ? "repo" : "package"} mode)`);
     telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
 
@@ -384,7 +402,7 @@ function doctor(silent = false): DoctorResult {
     console.log("");
   }
 
-  return { bun, claude, opencode, hasAgent };
+  return { bun, claude, opencode, cursor, hasAgent };
 }
 
 // ── Commands ──
@@ -424,7 +442,7 @@ async function init(args: string[]) {
   }
 }
 
-async function install(targets: { claude: boolean; opencode: boolean }) {
+async function install(targets: { claude: boolean; opencode: boolean; cursor: boolean }) {
   // Scaffold TELOS + PAL settings, then prompt for missing identity
   const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");
@@ -444,6 +462,12 @@ async function install(targets: { claude: boolean; opencode: boolean }) {
     console.log("");
   }
 
+  if (targets.cursor) {
+    console.log("━━━ Cursor ━━━");
+    await import("../targets/cursor/install");
+    console.log("");
+  }
+
   log.success("Done. Existing config was preserved — only new entries were added.");
 }
 
@@ -462,6 +486,12 @@ async function uninstall(args: string[]) {
     console.log("");
   }
 
+  if (targets.cursor) {
+    console.log("━━━ Cursor ━━━");
+    await import("../targets/cursor/uninstall");
+    console.log("");
+  }
+
   log.success(
     `PAL uninstalled. Your TELOS, skills, and memory are still in ${palHome()}.`
   );
@@ -641,6 +671,7 @@ async function status() {
 
   log.info(`Claude:   ${platform.claudeDir()}`);
   log.info(`opencode: ${platform.opencodeDir()}`);
+  log.info(`Cursor:   ${platform.cursorDir()}`);
   log.info(`Agents:   ${platform.agentsDir()}`);
   console.log("");
 

package/src/hooks/LoadContext.ts

@@ -6,7 +6,7 @@
  * learning digest, signal trends, failure patterns, active work state.
  */
 
-import { regenerateIfNeeded } from "./lib/claude-md";
+import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { buildSystemReminder } from "./lib/context";
 import { logDebug, logError } from "./lib/log";
 
@@ -28,11 +28,21 @@ try {
   logError("LoadContext:regenerate", err);
 }
 
-// --- Dynamic system-reminder to stdout (empty = nothing injected) ---
+// --- Context to stdout ---
 try {
   const reminder = buildSystemReminder();
-  if (reminder) console.log(reminder);
-  logDebug("LoadContext", `Reminder injected: ${reminder ? reminder.length : 0} chars`);
+  if (!reminder) process.exit(0);
+
+  if (process.env.CURSOR_VERSION) {
+    // Cursor: no native user-level rules — inject AGENTS.md + dynamic context
+    const agentsMd = buildClaudeMd();
+    const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
+    process.stdout.write(JSON.stringify({ additional_context: context }));
+  } else {
+    // Claude Code: raw text
+    console.log(reminder);
+  }
+  logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
 } catch (err) {
   logError("LoadContext:reminder", err);
 }

package/src/hooks/SecurityValidator.ts

@@ -5,6 +5,7 @@
  * Fail-open design: if anything goes wrong, the command is allowed through.
  */
 
+import { blockResponse } from "./lib/agent";
 import { checkBashCommand, checkFilePath, WARN_COMMANDS } from "./lib/security";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -22,27 +23,30 @@ try {
 
   const { tool_name, tool_input } = input;
 
-  // Check Bash commands
-  if (tool_name === "Bash" && tool_input.command) {
+  // Normalize tool names: Claude uses "Bash", Cursor uses "Shell"
+  const isBash = tool_name === "Bash" || tool_name === "Shell";
+  const isFileWrite = tool_name === "Write" || tool_name === "Edit";
+
+  // Check shell commands
+  if (isBash && tool_input.command) {
     const reason = checkBashCommand(tool_input.command);
     if (reason) {
-      console.log(JSON.stringify({ decision: "block", reason: `Blocked: ${reason}` }));
+      process.stdout.write(blockResponse(`Blocked: ${reason}`));
       process.exit(0);
     }
 
     for (const pattern of WARN_COMMANDS) {
       if (pattern.test(tool_input.command)) {
-        // Log but don't block — Claude Code's own permission system handles confirmation
         break;
       }
     }
   }
 
-  // Check file path operations (Write, Edit)
-  if ((tool_name === "Write" || tool_name === "Edit") && tool_input.file_path) {
+  // Check file path operations
+  if (isFileWrite && tool_input.file_path) {
     const fileReason = checkFilePath(tool_input.file_path);
     if (fileReason) {
-      console.log(JSON.stringify({ decision: "block", reason: fileReason }));
+      process.stdout.write(blockResponse(fileReason));
       process.exit(0);
     }
   }

package/src/hooks/SkillGuard.ts

@@ -9,6 +9,7 @@
  * Fail-open: on any error, the skill is allowed through.
  */
 
+import { blockResponse } from "./lib/agent";
 import { readStdinJSON } from "./lib/stdin";
 
 const BLOCKED_SKILLS = ["keybindings-help"];
@@ -27,13 +28,11 @@ try {
   const skill = (input.tool_input?.skill || "").toLowerCase().trim();
 
   if (BLOCKED_SKILLS.includes(skill)) {
-    console.log(
-      JSON.stringify({
-        decision: "block",
-        reason:
-          'BLOCKED: "keybindings-help" is a known false-positive triggered by position bias. ' +
-          "The user did NOT ask about keybindings. Continue with their ACTUAL request.",
-      })
+    process.stdout.write(
+      blockResponse(
+        'BLOCKED: "keybindings-help" is a known false-positive triggered by position bias. ' +
+          "The user did NOT ask about keybindings. Continue with their ACTUAL request."
+      )
     );
   }
 } catch {

package/src/hooks/StopOrchestrator.ts

@@ -7,6 +7,7 @@
  */
 
 import { checkReadmeSync } from "./handlers/readme-sync";
+import { isCursor } from "./lib/agent";
 import { logError } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 import { runStopHandlers } from "./lib/stop";
@@ -22,7 +23,13 @@ interface StopHookInput {
 try {
   const decision = checkReadmeSync();
   if (decision.decision === "block") {
-    console.log(JSON.stringify(decision));
+    if (isCursor()) {
+      // Cursor stop hook: followup_message auto-sends to the agent
+      process.stdout.write(JSON.stringify({ followup_message: decision.reason }));
+    } else {
+      // Claude Code: block decision
+      process.stdout.write(JSON.stringify(decision));
+    }
     process.exit(0);
   }
 } catch (err) {

package/src/hooks/lib/agent.ts

@@ -0,0 +1,40 @@
+/**
+ * Agent detection and output format adapters.
+ *
+ * Cursor and Claude Code use different JSON contracts for hook I/O.
+ * These helpers normalize the differences so hook handlers stay clean.
+ */
+
+export type AgentType = "claude" | "cursor";
+
+/** Detect which agent is running via environment variables */
+export function detectAgent(): AgentType {
+  if (process.env.CURSOR_VERSION) return "cursor";
+  return "claude";
+}
+
+export const isCursor = () => detectAgent() === "cursor";
+
+/**
+ * Format a "block this action" response for the current agent.
+ * Claude Code: { decision: "block", reason }
+ * Cursor:      { permission: "deny", user_message }
+ */
+export function blockResponse(reason: string): string {
+  if (isCursor()) {
+    return JSON.stringify({ permission: "deny", user_message: reason });
+  }
+  return JSON.stringify({ decision: "block", reason });
+}
+
+/**
+ * Format sessionStart context injection for the current agent.
+ * Claude Code: raw text to stdout
+ * Cursor:      { additional_context: "..." }
+ */
+export function sessionStartOutput(context: string): string {
+  if (isCursor()) {
+    return JSON.stringify({ additional_context: context });
+  }
+  return context;
+}

package/src/hooks/lib/claude-md.ts

@@ -48,19 +48,25 @@ function latestMtime(...filePaths: string[]): number {
   return latest;
 }
 
-/** Ensure CLAUDE.md is a symlink pointing to AGENTS.md */
-function ensureSymlink(): void {
-  const { outputPath, symlinkPath } = getOutputPaths();
+/** Create or verify a symlink pointing to AGENTS.md */
+function ensureOneSymlink(linkPath: string, targetPath: string): void {
   try {
-    const stat = lstatSync(symlinkPath);
-    // If it exists but isn't a symlink (e.g. old generated file), remove it
-    if (!stat.isSymbolicLink()) unlinkSync(symlinkPath);
+    const stat = lstatSync(linkPath);
+    if (!stat.isSymbolicLink()) unlinkSync(linkPath);
     else return; // already a symlink, leave it
   } catch {
     // doesn't exist — create it
   }
-  const relTarget = relative(dirname(symlinkPath), outputPath).replaceAll("\\", "/");
-  symlinkSync(relTarget, symlinkPath);
+  ensureDir(dirname(linkPath));
+  const relTarget = relative(dirname(linkPath), targetPath).replaceAll("\\", "/");
+  symlinkSync(relTarget, linkPath);
+}
+
+/** Ensure all agent symlinks point to the canonical AGENTS.md */
+function ensureSymlinks(): void {
+  const { outputPath, symlinkPath } = getOutputPaths();
+  ensureOneSymlink(symlinkPath, outputPath);
+  ensureOneSymlink(resolve(platform.codexDir(), "AGENTS.md"), outputPath);
 }
 
 /** Returns true if AGENTS.md needs to be regenerated */
@@ -150,7 +156,7 @@ export function buildClaudeMd(): string {
 /** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */
 export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
-  ensureSymlink();
+  ensureSymlinks();
   if (!needsRebuild()) return false;
   ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");

package/src/hooks/lib/paths.ts

@@ -67,6 +67,8 @@ const h = homedir();
 export const platform = {
   claudeDir: () => process.env.PAL_CLAUDE_DIR || resolve(h, ".claude"),
   opencodeDir: () => process.env.PAL_OPENCODE_DIR || resolve(h, ".config", "opencode"),
+  cursorDir: () => process.env.PAL_CURSOR_DIR || resolve(h, ".cursor"),
+  codexDir: () => process.env.PAL_CODEX_DIR || resolve(h, ".codex"),
   agentsDir: () => process.env.PAL_AGENTS_DIR || resolve(h, ".agents"),
 } as const;
 
@@ -78,5 +80,6 @@ export const assets = {
   telosTemplates: () => pkg("assets", "templates", "telos"),
   agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
   claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
+  cursorHooksTemplate: () => pkg("assets", "templates", "hooks.cursor.json"),
   palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/targets/cursor/install.ts

@@ -0,0 +1,65 @@
+/**
+ * PAL — Cursor target installer (TypeScript)
+ * Merges hooks template into existing hooks.json (never overwrites).
+ * Symlinks skills. Generates AGENTS.md.
+ */
+
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  copyPalDocs,
+  copySkills,
+  countSkills,
+  loadCursorHooksTemplate,
+  log,
+  mergeCursorHooks,
+  readJson,
+  scaffoldPalSettings,
+  writeJson,
+} from "../lib";
+
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
+const CURSOR_DIR = platform.cursorDir();
+const HOOKS_FILE = resolve(CURSOR_DIR, "hooks.json");
+
+// --- Ensure ~/.cursor/ exists ---
+mkdirSync(CURSOR_DIR, { recursive: true });
+
+// --- Merge hooks ---
+if (existsSync(HOOKS_FILE)) {
+  const backup = `${HOOKS_FILE}.bak.${Date.now()}`;
+  copyFileSync(HOOKS_FILE, backup);
+  log.info("Backed up hooks.json");
+}
+
+const template = loadCursorHooksTemplate(assets.cursorHooksTemplate(), PKG_ROOT);
+const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
+const merged = mergeCursorHooks(existing, template);
+
+writeJson(HOOKS_FILE, merged);
+log.success("Merged PAL hooks into hooks.json");
+
+// --- Symlink skills to ~/.cursor/skills/ ---
+const cursorSkillsDir = resolve(CURSOR_DIR, "skills");
+copySkills(cursorSkillsDir);
+
+// --- Copy PAL system docs ---
+const palDocsCount = copyPalDocs();
+log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
+
+// --- Scaffold PAL settings ---
+scaffoldPalSettings();
+
+// --- Generate AGENTS.md ---
+regenerateIfNeeded();
+log.success("Generated AGENTS.md");
+
+log.success("Cursor installation complete");
+console.log("");
+log.info(`Skills: ${countSkills()}`);
+log.info(`Hooks: ${HOOKS_FILE}`);
+log.info(
+  "Note: Cursor tool matchers may need tuning — verify hook behavior after first use"
+);

package/src/targets/cursor/uninstall.ts

@@ -0,0 +1,52 @@
+/**
+ * PAL — Cursor uninstaller (TypeScript)
+ * Removes only PAL-owned hooks from hooks.json. Preserves user hooks.
+ * Removes PAL skill symlinks.
+ */
+
+import { copyFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  loadCursorHooksTemplate,
+  log,
+  readJson,
+  removePalDocs,
+  removeSkills,
+  unmergeCursorHooks,
+  writeJson,
+} from "../lib";
+
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
+const CURSOR_DIR = platform.cursorDir();
+const HOOKS_FILE = resolve(CURSOR_DIR, "hooks.json");
+
+// --- Remove PAL hooks from hooks.json ---
+if (existsSync(HOOKS_FILE)) {
+  // Backup before modifying
+  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
+  log.info("Backed up hooks.json");
+
+  const template = loadCursorHooksTemplate(assets.cursorHooksTemplate(), PKG_ROOT);
+  const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
+  const cleaned = unmergeCursorHooks(existing, template);
+
+  writeJson(HOOKS_FILE, cleaned);
+  log.success("Removed PAL hooks from hooks.json");
+} else {
+  log.info("No hooks.json found, nothing to do");
+}
+
+// --- Remove PAL skill symlinks ---
+const cursorSkillsDir = resolve(CURSOR_DIR, "skills");
+const removed = removeSkills(cursorSkillsDir);
+if (removed.length > 0) {
+  log.success(`Removed ${removed.length} skill(s): ${removed.join(", ")}`);
+} else {
+  log.info("No PAL skills found");
+}
+
+// --- Remove PAL system docs ---
+removePalDocs();
+
+log.success("Cursor uninstall complete");

package/src/targets/lib.ts

@@ -136,6 +136,85 @@ export function unmergeSettings(existing: Settings, template: Settings): Setting
   return result;
 }
 
+// --- Cursor hooks.json merge/unmerge ---
+
+type CursorHookEntry = {
+  type: string;
+  command: string;
+  matcher?: string;
+  timeout?: number;
+};
+type CursorHooks = {
+  version?: number;
+  hooks?: Record<string, CursorHookEntry[]>;
+};
+
+/**
+ * Load a Cursor hooks template, replacing {{PKG_ROOT}} with the actual path.
+ */
+export function loadCursorHooksTemplate(
+  templatePath: string,
+  pkgRoot: string
+): CursorHooks {
+  const raw = readFileSync(templatePath, "utf-8");
+  const resolved = raw.replaceAll("{{PKG_ROOT}}", pkgRoot);
+  return JSON.parse(resolved) as CursorHooks;
+}
+
+/**
+ * Merge PAL hooks into an existing Cursor hooks.json.
+ * Deduplicates by command string within each event.
+ */
+export function mergeCursorHooks(
+  existing: CursorHooks,
+  template: CursorHooks
+): CursorHooks {
+  const result: CursorHooks = { ...existing, version: existing.version ?? 1 };
+
+  if (template.hooks) {
+    if (!result.hooks) result.hooks = {};
+    for (const [event, entries] of Object.entries(template.hooks)) {
+      const current = result.hooks[event] ?? [];
+      for (const entry of entries) {
+        if (!current.some((e) => e.command === entry.command)) {
+          current.push(entry);
+        }
+      }
+      result.hooks[event] = current;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove PAL hooks from an existing Cursor hooks.json.
+ * Only removes entries whose command matches the template. Preserves user hooks.
+ */
+export function unmergeCursorHooks(
+  existing: CursorHooks,
+  template: CursorHooks
+): CursorHooks {
+  const result: CursorHooks = { ...existing };
+
+  if (template.hooks && result.hooks) {
+    const palCommands = new Set<string>();
+    for (const entries of Object.values(template.hooks)) {
+      for (const entry of entries) {
+        palCommands.add(entry.command);
+      }
+    }
+
+    for (const [event, entries] of Object.entries(result.hooks)) {
+      result.hooks[event] = entries.filter((e) => !palCommands.has(e.command));
+      if (result.hooks[event].length === 0) delete result.hooks[event];
+    }
+    if (Object.keys(result.hooks).length === 0) delete result.hooks;
+  }
+
+  return result;
+}
+
 // --- TELOS scaffolding ---
 
 /** Copy template files into telos/ without overwriting existing ones */