portable-agent-layer 0.16.0 → 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)
 
@@ -94,6 +94,15 @@ 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
@@ -114,6 +123,7 @@ pal cli install               # all available (default)
 | `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`) |
 
 ---
@@ -162,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/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/package.json

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

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

@@ -68,6 +68,7 @@ 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;