Merge pull request #16 from hovhannest/codex-adapter

Add codex adapter

Author: codejunkie99

README.md

@@ -2,7 +2,7 @@
 
 **Keep one portable memory-and-skills layer across coding-agent harnesses, so switching tools doesn't reset how your agent works.**
 
-A portable `.agent/` folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, Pi Coding Agent, or a DIY Python loop — and keeps its knowledge when you switch.
+A portable `.agent/` folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Hermes, Pi Coding Agent, Codex, or a DIY Python loop — and keeps its knowledge when you switch.
 
 <p align="center">
   <img src="docs/demo.gif" alt="agentic-stack demo" width="880"/>
@@ -28,7 +28,7 @@ brew install agentic-stack
 # drop the brain into any project — the onboarding wizard runs automatically
 cd your-project
 agentic-stack claude-code
-# or: cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python | antigravity
+# or: cursor | windsurf | opencode | openclaw | hermes | pi | codex | standalone-python | antigravity
 ```
 
 ### Windows (PowerShell)
@@ -52,7 +52,7 @@ brew update && brew upgrade agentic-stack
 git clone https://github.com/codejunkie99/agentic-stack.git
 cd agentic-stack && ./install.sh claude-code         # mac / linux / git-bash
 # or on Windows PowerShell: .\install.ps1 claude-code
-# adapters: claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python | antigravity
+# adapters: claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | codex | standalone-python | antigravity
 ```
 
 ## Onboarding wizard
@@ -122,7 +122,7 @@ See [`docs/architecture.md`](docs/architecture.md) for the full lifecycle.
 Every guide shows the folder structure. This repo gives you the folder
 structure **plus the files that actually go inside**: a working portable
 brain with five seed skills, four memory layers, enforced permissions, a
-nightly staging cycle, host-agent review tools, and adapters for eight
+nightly staging cycle, host-agent review tools, and adapters for multiple
 harnesses.
 
 - **Memory** — `working/`, `episodic/`, `semantic/`, `personal/`. Each
@@ -197,6 +197,7 @@ adapters/                       # one small shim per harness
 ├── openclaw/      (AGENTS.md + system-prompt include; auto-registers per-project agent)
 ├── hermes/        (AGENTS.md)
 ├── pi/            (AGENTS.md + .pi/skills symlink)
+├── codex/         (AGENTS.md)
 ├── standalone-python/  (DIY conductor entrypoint)
 └── antigravity/   (ANTIGRAVITY.md)
 
@@ -225,6 +226,7 @@ verify_codex_fixes.py           # v0.8.0 regression checks (33 checks)
 | **OpenClaw** | `AGENTS.md` (auto-injected) + per-project `openclaw agents add --workspace` | varies by fork |
 | **Hermes Agent** | `AGENTS.md` (agentskills.io compatible) | partial (own memory) |
 | **Pi Coding Agent** | `AGENTS.md` + `.pi/skills/` + `.pi/extensions/` | yes (`tool_result` event) |
+| **Codex** | `AGENTS.md` + `.agents/skills/` | no (manual reflect calls) |
 | **Standalone Python** | `run.py` (any LLM) | yes (full control) |
 | **Antigravity** | `ANTIGRAVITY.md` | yes (system context) |
 

adapters/codex/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md — Codex adapter for agentic-stack
+
+Codex reads `AGENTS.md` before doing any work. This file points it at
+the portable brain in `.agent/`.
+
+> **Python invocation**: examples below use `python3`. On stock Windows
+> only `python` is on PATH; use whichever resolves on your system.
+
+## Startup (read in order)
+1. `.agent/AGENTS.md` — the map
+2. `.agent/memory/personal/PREFERENCES.md` — user conventions
+3. `.agent/memory/semantic/LESSONS.md` — distilled lessons
+4. `.agent/protocols/permissions.md` — hard rules
+
+## Skills
+Codex scans `.agents/skills/` for repository-scoped skills (per
+[OpenAI Codex docs](https://developers.openai.com/codex/skills)). The
+install script symlinks or syncs `.agents/skills` from `.agent/skills`
+so the portable brain remains the one source of truth. Load a full
+`SKILL.md` only when its triggers match the task (progressive
+disclosure). Edit skills in `.agent/skills/` — `.agents/skills/` is a
+mirror and re-running the installer will sync it back.
+
+## Recall before non-trivial tasks
+For deploy / ship / migration / schema / timestamp / date / failing test /
+debug / refactor, FIRST run:
+
+```bash
+python3 .agent/tools/recall.py "<description>"
+```
+
+Surface results in a `Consulted lessons before acting:` block and follow
+them.
+
+## Memory discipline
+- Update `.agent/memory/working/WORKSPACE.md` as you work.
+- After significant actions, run
+  `python3 .agent/tools/memory_reflect.py <skill> <action> <outcome>`.
+- Never delete memory entries; archive only.
+- Quick state: `python3 .agent/tools/show.py`.
+- Teach a rule in one shot:
+  `python3 .agent/tools/learn.py "<rule>" --rationale "<why>"`.
+
+## Hard rules
+- No force push to `main`, `production`, `staging`.
+- No modification of `.agent/protocols/permissions.md`.

adapters/codex/README.md

@@ -0,0 +1,44 @@
+# Codex adapter
+
+## Install
+```bash
+./install.sh codex
+```
+
+Or on Windows PowerShell:
+```powershell
+.\install.ps1 codex C:\path\to\your-project
+```
+
+## What it wires up
+- `AGENTS.md` — Codex reads this natively as project instructions. If
+  `AGENTS.md` already exists (for example from the pi, hermes, or
+  opencode adapters), the installer leaves it in place.
+- `.agents/skills/` → `.agent/skills/` — Codex scans `.agents/skills/`
+  for repository skills. The installer creates a symlink when possible
+  and falls back to copying / merging when symlinks are unavailable.
+
+## Verify
+Run Codex in the project and ask:
+
+```bash
+codex --ask-for-approval never "Summarize the current instructions."
+```
+
+It should mention `.agent/AGENTS.md` and the portable memory files.
+
+Then ask:
+
+```bash
+codex --ask-for-approval never "What's in my lessons file?"
+```
+
+It should read `.agent/memory/semantic/LESSONS.md`.
+
+## Notes
+- This adapter does **not** install Codex hooks. Codex hooks are still
+  experimental, and the official docs note they are currently disabled
+  on Windows. The adapter therefore relies on manual `recall.py` and
+  `memory_reflect.py` calls, like the Cursor and Windsurf paths.
+- If `.agents/skills/` is a copied directory rather than a symlink,
+  re-run the installer after editing `.agent/skills/` to sync updates.

docs/architecture.md

@@ -33,7 +33,8 @@ Three modules, one principle: the harness is dumb, the knowledge is in files.
 ## Why the separation matters
 
 You can swap the harness for any of the adapters (Claude Code, Cursor,
-Windsurf, OpenCode, OpenClaw, Hermes, standalone Python) and lose
-nothing. The brain is portable; only the glue changes.
+Windsurf, OpenCode, OpenClaw, Hermes, Pi, Codex, standalone Python,
+Antigravity) and lose nothing. The brain is portable; only the glue
+changes.
 
 See `diagram.svg` for a visual.

docs/getting-started.md

@@ -16,7 +16,8 @@ cp /path/to/agentic-stack/install.sh ./
 
 ```bash
 ./install.sh claude-code        # or cursor, windsurf, opencode,
-                                # openclaw, hermes, standalone-python
+                                # openclaw, hermes, pi, codex,
+                                # standalone-python, antigravity
 ```
 
 Each adapter has its own `README.md` under `adapters/<name>/`.

docs/per-harness/codex.md

@@ -0,0 +1,58 @@
+# Codex setup
+
+[Codex](https://developers.openai.com/codex/) reads `AGENTS.md` natively
+and scans `.agents/skills/` for repository-scoped skills. Our adapter
+layers the portable `.agent/` brain on top so you keep one knowledge
+base even if you later swap harnesses.
+
+## What the adapter installs
+- `AGENTS.md` at project root. Skipped if one already exists, since
+  codex, pi, hermes, and opencode can all share the same file.
+- `.agents/skills/` symlinked to `.agent/skills/` when possible. Falls
+  back to copying / merging on platforms without symlink support.
+
+## Install
+```bash
+npm install -g @openai/codex
+./install.sh codex
+codex
+```
+
+On Windows PowerShell:
+```powershell
+npm install -g @openai/codex
+.\install.ps1 codex C:\path\to\your-project
+codex
+```
+
+## How it works
+- Codex loads `AGENTS.md` before starting work. The adapter file points
+  it at `.agent/AGENTS.md`, `PREFERENCES.md`, `LESSONS.md`, and
+  `permissions.md`.
+- Codex scans `.agents/skills/` from the current working directory up to
+  the repository root. The adapter mirrors `.agent/skills/` there so the
+  portable skills are visible without duplication.
+- The adapter intentionally does **not** install Codex hooks. The docs
+  mark hooks experimental, and Windows support is currently disabled, so
+  manual `recall.py` and `memory_reflect.py` calls remain the stable
+  cross-platform path.
+
+## Verify
+```bash
+codex --ask-for-approval never "Summarize the current instructions."
+codex --ask-for-approval never "What's in my lessons file?"
+```
+
+Expected:
+- the first command mentions `.agent/AGENTS.md`
+- the second reads `.agent/memory/semantic/LESSONS.md`
+
+## Troubleshooting
+- If Codex does not pick up `AGENTS.md`, restart it from the repository
+  root and run the `Summarize the current instructions` check again.
+- If skills are missing, inspect `.agents/skills/`. On filesystems
+  without symlink support, the installer copies / merges the directory
+  instead; re-run the installer after updating `.agent/skills/`.
+- On Windows, the native sandbox is the default and works fine for this
+  adapter. If your workflow needs Linux-native tooling, run Codex inside
+  WSL2 instead.

install.ps1

@@ -1,6 +1,6 @@
 # install.ps1 — Windows PowerShell installer (parallel to install.sh)
 # Usage:  .\install.ps1 <adapter-name> [target-dir] [-Yes] [-Reconfigure] [-Force]
-#   adapter-name: claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python | antigravity
+#   adapter-name: claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | codex | standalone-python | antigravity
 #   target-dir:   where your project lives (default: current dir)
 #   -Yes          accept all wizard defaults (safe for CI)
 #   -Reconfigure  re-run the wizard on an existing project
@@ -24,7 +24,7 @@ $Here = Split-Path -Parent $MyInvocation.MyCommand.Path
 
 $ValidAdapters = @(
     'claude-code', 'cursor', 'windsurf',
-    'opencode', 'openclaw', 'hermes', 'pi',
+    'opencode', 'openclaw', 'hermes', 'pi', 'codex',
     'standalone-python', 'antigravity'
 )
 if ($Adapter -notin $ValidAdapters) {
@@ -190,6 +190,73 @@ switch ($Adapter) {
         Copy-Item (Join-Path $Here '.agent/harness/hooks/pi_post_tool.py') (Join-Path $hooksDir 'pi_post_tool.py') -Force
         Write-Host "  + .agent/harness/hooks/pi_post_tool.py (synced for upgrades)"
     }
+    'codex' {
+        # Mirror install.sh: openclaw-style merge-or-alert on existing AGENTS.md.
+        $agentsMd = Join-Path $TargetDir 'AGENTS.md'
+        if (Test-Path $agentsMd -PathType Leaf) {
+            $existing = Get-Content -Path $agentsMd -Raw -ErrorAction SilentlyContinue
+            if ($existing -match '\.agent/') {
+                Write-Host "  ~ AGENTS.md already references .agent/ — leaving alone"
+            } else {
+                Write-Host "  ! AGENTS.md exists but does not reference .agent/; not overwriting."
+                Write-Host "    merge this block into your AGENTS.md to wire the brain:"
+                Write-Host "    ---8<---"
+                Get-Content -Path (Join-Path $Src 'AGENTS.md') | ForEach-Object { Write-Host "    $_" }
+                Write-Host "    --->8---"
+            }
+        } else {
+            Copy-Item (Join-Path $Src 'AGENTS.md') $agentsMd -Force
+            Write-Host "  + AGENTS.md"
+        }
+
+        # Codex scans .agents/skills/ — keep the portable brain authoritative.
+        $agentsDir = Join-Path $TargetDir '.agents'
+        New-Item -ItemType Directory -Path $agentsDir -Force | Out-Null
+        $skillsSrc = Join-Path $TargetAgent 'skills'
+        $skillsDst = Join-Path $agentsDir 'skills'
+
+        # Detect symlink/junction BEFORE Remove-Item: on PowerShell 5.1
+        # `Remove-Item -Recurse` on a symlink can delete the target's
+        # contents. Use IsLink detection + .NET Delete (or repoint).
+        $skillsDstItem = Get-Item -LiteralPath $skillsDst -Force -ErrorAction SilentlyContinue
+        $isLink = $false
+        if ($skillsDstItem) {
+            $isLink = ($skillsDstItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -eq [System.IO.FileAttributes]::ReparsePoint
+        }
+
+        if ($skillsDstItem -and $isLink) {
+            # Existing link: delete the link only (NOT its target), then re-create.
+            try {
+                [System.IO.Directory]::Delete($skillsDst, $false)
+            } catch {
+                [System.IO.File]::Delete($skillsDst)
+            }
+            try {
+                New-Item -ItemType SymbolicLink -Path $skillsDst -Target $skillsSrc -ErrorAction Stop | Out-Null
+                Write-Host "  + .agents/skills -> $skillsSrc (relinked)"
+            } catch {
+                Copy-Item -Path $skillsSrc -Destination $skillsDst -Recurse
+                Write-Host "  + .agents/skills (copy; symlink not supported here)"
+            }
+        } elseif ($skillsDstItem) {
+            Remove-Item -LiteralPath $skillsDst -Recurse -Force
+            try {
+                New-Item -ItemType SymbolicLink -Path $skillsDst -Target $skillsSrc -ErrorAction Stop | Out-Null
+                Write-Host "  + .agents/skills -> $skillsSrc (replaced stale copy)"
+            } catch {
+                Copy-Item -Path $skillsSrc -Destination $skillsDst -Recurse
+                Write-Host "  ~ replaced .agents/skills with current .agent/skills (no symlink)"
+            }
+        } else {
+            try {
+                New-Item -ItemType SymbolicLink -Path $skillsDst -Target $skillsSrc -ErrorAction Stop | Out-Null
+                Write-Host "  + .agents/skills -> $skillsSrc"
+            } catch {
+                Copy-Item -Path $skillsSrc -Destination $skillsDst -Recurse
+                Write-Host "  + .agents/skills (copy; symlink not supported here)"
+            }
+        }
+    }
     'standalone-python' {
         Copy-Item (Join-Path $Src 'run.py') (Join-Path $TargetDir 'run.py') -Force
     }

install.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # install.sh — copy an adapter into the consuming project, then run the onboarding wizard
 # Usage: ./install.sh <adapter-name> [target-dir] [--yes] [--reconfigure]
-#   adapter-name:  claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | standalone-python | antigravity
+#   adapter-name:  claude-code | cursor | windsurf | opencode | openclaw | hermes | pi | codex | standalone-python | antigravity
 #   target-dir:    where your project lives (default: current dir)
 #   --yes          accept all wizard defaults without prompting (safe for CI)
 #   --reconfigure  re-run the wizard even if PREFERENCES.md is already filled
@@ -13,7 +13,7 @@ HERE="$(cd "$(dirname "$0")" && pwd)"
 
 if [[ -z "$ADAPTER" ]]; then
   echo "usage: $0 <adapter-name> [target-dir]" >&2
-  echo "adapters: claude-code cursor windsurf opencode openclaw hermes pi standalone-python antigravity" >&2
+  echo "adapters: claude-code cursor windsurf opencode openclaw hermes pi codex standalone-python antigravity" >&2
   exit 2
 fi
 
@@ -171,6 +171,55 @@ case "$ADAPTER" in
     cp "$HERE/.agent/harness/hooks/pi_post_tool.py" "$TARGET/.agent/harness/hooks/pi_post_tool.py"
     echo "  + .agent/harness/hooks/pi_post_tool.py (synced for upgrades)"
     ;;
+  codex)
+    # codex reads AGENTS.md (like pi, hermes, opencode). Many other tools
+    # also write AGENTS.md (aider, amp, cline, existing codex setups), so
+    # we follow the openclaw pattern: merge-or-alert, never blind overwrite,
+    # never blind skip.
+    if [[ -f "$TARGET/AGENTS.md" ]]; then
+      if grep -q '\.agent/' "$TARGET/AGENTS.md" 2>/dev/null; then
+        echo "  ~ AGENTS.md already references .agent/ — leaving alone"
+      else
+        echo "  ! AGENTS.md exists but does not reference .agent/; not overwriting."
+        echo "    merge this block into your AGENTS.md to wire the brain:"
+        echo "    ---8<---"
+        sed 's/^/    /' "$SRC/AGENTS.md"
+        echo "    --->8---"
+      fi
+    else
+      cp "$SRC/AGENTS.md" "$TARGET/AGENTS.md"
+      echo "  + AGENTS.md"
+    fi
+
+    # Codex scans .agents/skills/ (plural) for repo-scoped skills — per
+    # OpenAI docs https://developers.openai.com/codex/skills. Keep the
+    # portable brain authoritative: .agents/skills mirrors .agent/skills.
+    mkdir -p "$TARGET/.agents"
+    SKILLS_SRC="$(cd "$TARGET/.agent/skills" && pwd)"
+    SKILLS_DEST="$TARGET/.agents/skills"
+    if [[ -L "$SKILLS_DEST" ]]; then
+      # Existing symlink: repoint at current .agent/skills (cheap, safe)
+      ln -sfn "$SKILLS_SRC" "$SKILLS_DEST"
+      echo "  + .agents/skills -> $SKILLS_SRC"
+    elif [[ -d "$SKILLS_DEST" ]]; then
+      # Real directory from a prior copy-fallback install: sync with
+      # delete-orphans so removed/renamed skills don't linger. Use rsync
+      # if available, otherwise rm+cp as a safe-but-blunt replacement.
+      if command -v rsync >/dev/null 2>&1; then
+        rsync -a --delete "$SKILLS_SRC/" "$SKILLS_DEST/"
+        echo "  ~ synced .agent/skills → .agents/skills (rsync --delete)"
+      else
+        rm -rf "$SKILLS_DEST"
+        cp -R "$SKILLS_SRC" "$SKILLS_DEST"
+        echo "  ~ replaced .agents/skills with current .agent/skills (no rsync)"
+      fi
+    elif ln -sfn "$SKILLS_SRC" "$SKILLS_DEST" 2>/dev/null; then
+      echo "  + .agents/skills -> $SKILLS_SRC"
+    else
+      cp -R "$SKILLS_SRC" "$SKILLS_DEST"
+      echo "  + .agents/skills (copy; symlink not supported here)"
+    fi
+    ;;
   standalone-python)
     cp "$SRC/run.py" "$TARGET/run.py"
     ;;