woclaw-codex 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# WoClaw Codex CLI Integration
+
+Connect OpenAI Codex CLI sessions to a WoClaw Hub for **shared context across sessions and agents**.
+
+```
+pip install aiohttp websockets   # required by hook scripts
+python3 install.py               # one-command install
+```
+
+## What It Does
+
+- **SessionStart Hook**: When Codex starts, loads shared project context from WoClaw Hub and injects it as developer context
+- **Stop Hook**: When Codex ends, saves a transcript summary back to WoClaw Hub so future sessions can pick up where you left off
+
+## Requirements
+
+- Python 3.8+
+- `aiohttp` or standard `urllib` (stdlib, no extra deps needed for REST)
+- WoClaw Hub running at `ws://vm153:8082` / `http://vm153:8083`
+
+## Quick Install
+
+```bash
+# Clone WoClaw repo (if you have it)
+cd packages/codex-woclaw
+
+# Install hooks (one command)
+python3 install.py
+```
+
+This will:
+1. Copy `session_start.py` and `stop.py` to `~/.codex/hooks/`
+2. Create `~/.codex/hooks.json` with WoClaw hook configuration
+3. Enable `codex_hooks = true` in `~/.codex/config.toml`
+
+Then start a Codex session — the hook runs automatically.
+
+## Uninstall
+
+```bash
+python3 install.py --uninstall
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WOCLAW_HUB_URL` | `http://vm153:8083` | Hub REST API URL |
+| `WOCLAW_TOKEN` | `WoClaw2026` | Hub auth token |
+| `WOCLAW_KEY` | `codex:context` | Memory key for context |
+
+## How It Works
+
+The Codex CLI hooks system (`~/.codex/hooks.json`) fires Python scripts at key lifecycle events:
+
+1. **SessionStart** → `session_start.py` reads `WOCLAW_KEY` from WoClaw Hub REST API → injects as `additionalContext`
+2. **Stop** → `stop.py` reads session transcript → writes summary to WoClaw Hub under `WOCLAW_KEY`
+
+## NPM Package
+
+Publishing as `woclaw-codex` npm package for easy distribution:
+
+```bash
+cd packages/codex-woclaw
+npm publish --access public
+# → woclaw-codex on npm
+```
+
+After npm install, users get:
+```
+npx woclaw-codex install   # installs hooks
+```

package/bin/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * woclaw-codex CLI
+ * Entry point for npm-installed package.
+ * Delegates to the Python install script.
+ */
+
+const { spawn } = require("child_process");
+const path = require("path");
+
+const action = process.argv[2] || "install";
+
+if (action === "install") {
+  console.log("Installing WoClaw Codex CLI hooks...");
+  const script = path.join(__dirname, "..", "install.py");
+  const child = spawn("python3", [script], { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code || 0));
+} else if (action === "uninstall") {
+  console.log("Uninstalling WoClaw Codex CLI hooks...");
+  const script = path.join(__dirname, "..", "install.py");
+  const child = spawn("python3", [script, "--uninstall"], { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code || 0));
+} else {
+  console.error(`Unknown action: ${action}`);
+  console.error("Usage: woclaw-codex [install|uninstall]");
+  process.exit(1);
+}

package/install.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+WoClaw Codex CLI Installer
+
+Configures Codex CLI to use WoClaw hooks for shared context across sessions.
+
+Usage:
+    python3 install.py [--uninstall]
+
+This script:
+1. Creates ~/.codex/hooks/ directory
+2. Copies hook scripts to ~/.codex/hooks/
+3. Creates ~/.codex/hooks.json with WoClaw hook configuration
+4. Enables hooks in ~/.codex/config.toml
+
+Requires: Python 3.8+
+"""
+
+import os
+import sys
+import json
+import shutil
+import argparse
+from pathlib import Path
+
+
+HOOKS_DIR = Path.home() / ".codex" / "hooks"
+HOOKS_JSON = Path.home() / ".codex" / "hooks.json"
+CONFIG_TOML = Path.home() / ".codex" / "config.toml"
+SCRIPT_DIR = Path(__file__).parent
+
+
+def ensure_hooks_dir():
+    HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"Created: {HOOKS_DIR}")
+
+
+def copy_hooks():
+    for script in ["session_start.py", "stop.py"]:
+        src = SCRIPT_DIR / script
+        dst = HOOKS_DIR / script
+        shutil.copy2(src, dst)
+        os.chmod(dst, 0o755)
+        print(f"Copied: {dst}")
+
+
+def create_hooks_json():
+    hooks_config = {
+        "hooks": {
+            "SessionStart": [
+                {
+                    "matcher": "startup|resume",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": f"python3 {HOOKS_DIR / 'session_start.py'}",
+                            "statusMessage": "Loading shared context from WoClaw"
+                        }
+                    ]
+                }
+            ],
+            "Stop": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": f"python3 {HOOKS_DIR / 'stop.py'}",
+                            "timeout": 30,
+                            "statusMessage": "Saving session to WoClaw Hub"
+                        }
+                    ]
+                }
+            ]
+        }
+    }
+    with open(HOOKS_JSON, "w") as f:
+        json.dump(hooks_config, f, indent=2)
+    print(f"Created: {HOOKS_JSON}")
+
+
+def update_config_toml():
+    """Enable hooks feature in config.toml."""
+    content = ""
+    if CONFIG_TOML.exists():
+        content = CONFIG_TOML.read_text()
+
+    if "[features]" in content and "codex_hooks" in content:
+        print(f"Hooks already enabled in {CONFIG_TOML}")
+        return
+
+    # Append or create config
+    addition = (
+        "\n[features]\n"
+        "codex_hooks = true\n"
+    )
+
+    if content.strip():
+        if not content.rstrip().endswith("\n"):
+            addition = "\n" + addition
+        content += addition
+    else:
+        content = addition
+
+    CONFIG_TOML.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_TOML.write_text(content)
+    print(f"Updated: {CONFIG_TOML} (enabled codex_hooks)")
+
+
+def uninstall():
+    """Remove WoClaw hooks from Codex configuration."""
+    # Remove hook scripts
+    for script in ["session_start.py", "stop.py"]:
+        dst = HOOKS_DIR / script
+        if dst.exists():
+            dst.unlink()
+            print(f"Removed: {dst}")
+
+    # Remove hooks.json
+    if HOOKS_JSON.exists():
+        try:
+            data = json.loads(HOOKS_JSON.read_text())
+            if "hooks" in data and (
+                "SessionStart" in data["hooks"] or "Stop" in data["hooks"]
+            ):
+                # Clear WoClaw hooks from the config
+                for key in ["SessionStart", "Stop"]:
+                    if key in data["hooks"]:
+                        data["hooks"][key] = [
+                            h for h in data["hooks"][key]
+                            if not any(
+                                "woclaw" in str(v).lower()
+                                for v in (h.get("command") or "")
+                            )
+                        ]
+                HOOKS_JSON.write_text(json.dumps(data, indent=2))
+                print(f"Updated: {HOOKS_JSON} (removed WoClaw hooks)")
+        except (json.JSONDecodeError, OSError):
+            HOOKS_JSON.unlink()
+            print(f"Removed: {HOOKS_JSON}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Install WoClaw hooks for Codex CLI")
+    parser.add_argument("--uninstall", action="store_true", help="Remove WoClaw hooks")
+    args = parser.parse_args()
+
+    if args.uninstall:
+        print("Uninstalling WoClaw Codex hooks...")
+        uninstall()
+        print("Done.")
+        return
+
+    print("Installing WoClaw Codex CLI hooks...")
+    print(f"Hub: {os.environ.get('WOCLAW_HUB_URL', 'http://vm153:8083')}")
+    print(f"Token: {'***' + os.environ.get('WOCLAW_TOKEN', 'WoClaw2026')[-4:]}")
+    print()
+
+    ensure_hooks_dir()
+    copy_hooks()
+    create_hooks_json()
+    update_config_toml()
+
+    print()
+    print("WoClaw hooks installed!")
+    print()
+    print("Next steps:")
+    print("  1. Start a new Codex session: codex")
+    print("  2. On session start, shared context will be loaded from WoClaw Hub")
+    print("  3. On session end, your work will be saved to WoClaw Hub")
+    print()
+    print("Environment variables (optional):")
+    print("  WOCLAW_HUB_URL   - Hub REST URL (default: http://vm153:8083)")
+    print("  WOCLAW_TOKEN     - Auth token (default: WoClaw2026)")
+    print("  WOCLAW_KEY       - Memory key (default: codex:context)")
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "woclaw-codex",
+  "version": "0.1.0",
+  "description": "WoClaw integration for OpenAI Codex CLI — shared context across sessions",
+  "keywords": [
+    "woclaw",
+    "codex",
+    "openai",
+    "ai-agent",
+    "shared-memory",
+    "context"
+  ],
+  "files": [
+    "*.py",
+    "install.py"
+  ],
+  "bin": {
+    "woclaw-codex": "./bin/cli.js"
+  },
+  "scripts": {
+    "install": "python3 install.py",
+    "uninstall": "python3 install.py --uninstall"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/session_start.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""
+WoClaw SessionStart Hook for OpenAI Codex CLI
+
+Reads shared project context from WoClaw Hub when a Codex session starts.
+Injects the context as additional developer context for the new session.
+
+Requires: aiohttp, websockets (or use REST for simplicity)
+
+Install:
+    python3 session_start.py --install
+
+Environment:
+    WOCLAW_HUB_URL  - Hub REST URL (default: http://vm153:8083)
+    WOCLAW_TOKEN    - Auth token (default: WoClaw2026)
+    WOCLAW_KEY      - Memory key to read (default: codex:context)
+"""
+
+import os
+import sys
+import json
+import urllib.request
+import urllib.error
+
+
+HUB_URL = os.environ.get("WOCLAW_HUB_URL", "http://vm153:8083")
+TOKEN = os.environ.get("WOCLAW_TOKEN", "WoClaw2026")
+MEMORY_KEY = os.environ.get("WOCLAW_KEY", "codex:context")
+
+
+def read_memory(key: str) -> str | None:
+    """Read a value from WoClaw Hub REST API."""
+    url = f"{HUB_URL}/memory/{key}"
+    req = urllib.request.Request(
+        url,
+        headers={"Authorization": f"Bearer {TOKEN}"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read())
+            if data.get("exists"):
+                return data.get("value")
+    except urllib.error.URLError:
+        pass
+    return None
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        hook_input = {}
+
+    source = hook_input.get("source", "startup")
+    cwd = hook_input.get("cwd", os.getcwd())
+
+    context = read_memory(MEMORY_KEY)
+
+    if context:
+        # Emit JSON output to inject as additional context
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": f"[WoClaw] Shared project context:\n{context}"
+            }
+        }
+        print(json.dumps(output))
+    else:
+        # No shared context found — just continue silently
+        pass
+
+
+if __name__ == "__main__":
+    main()

package/stop.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+WoClaw Stop Hook for OpenAI Codex CLI
+
+Writes session summary to WoClaw Hub when a Codex session ends.
+Helps preserve discoveries and decisions across sessions.
+
+Install:
+    python3 stop.py --install
+
+Environment:
+    WOCLAW_HUB_URL  - Hub REST URL (default: http://vm153:8083)
+    WOCLAW_TOKEN    - Auth token (default: WoClaw2026)
+    WOCLAW_KEY      - Memory key to write (default: codex:context)
+"""
+
+import os
+import sys
+import json
+import urllib.request
+import urllib.error
+from datetime import datetime
+
+
+HUB_URL = os.environ.get("WOCLAW_HUB_URL", "http://vm153:8083")
+TOKEN = os.environ.get("WOCLAW_TOKEN", "WoClaw2026")
+MEMORY_KEY = os.environ.get("WOCLAW_KEY", "codex:context")
+
+
+def write_memory(key: str, value: str, hostname: str) -> bool:
+    """Write a value to WoClaw Hub REST API."""
+    url = f"{HUB_URL}/memory"
+    payload = json.dumps({
+        "key": key,
+        "value": value,
+        "updatedBy": f"codex:{hostname}",
+        "tags": ["codex", "session-summary"]
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        headers={
+            "Authorization": f"Bearer {TOKEN}",
+            "Content-Type": "application/json"
+        },
+        method="POST"
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            return resp.status == 200
+    except urllib.error.URLError:
+        return False
+
+
+def read_transcript(path: str | None, max_lines: int = 80) -> str | None:
+    """Read the last lines of the session transcript."""
+    if not path:
+        return None
+    try:
+        with open(path, "r", encoding="utf-8", errors="ignore") as f:
+            lines = f.readlines()
+            return "".join(lines[-max_lines:])
+    except (OSError, IOError):
+        return None
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        hook_input = {}
+
+    session_id = hook_input.get("session_id", "unknown")
+    transcript_path = hook_input.get("transcript_path")
+    cwd = hook_input.get("cwd", os.getcwd())
+    stop_reason = hook_input.get("stopReason", "unknown")
+    hostname = os.uname().nodename
+
+    # Read transcript for context
+    transcript = read_transcript(transcript_path)
+
+    if transcript:
+        # Build a concise session summary
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+        summary = (
+            f"[{timestamp}] Codex session ended ({stop_reason})\n"
+            f"Session: {session_id}\n"
+            f"CWD: {cwd}\n"
+            f"---Last transcript excerpt---\n"
+            f"{transcript[:1000]}"
+        )
+        success = write_memory(MEMORY_KEY, summary, hostname)
+        if success:
+            print(f"[WoClaw] Session summary saved to {MEMORY_KEY}", file=sys.stderr)
+        else:
+            print(f"[WoClaw] Failed to save session summary", file=sys.stderr)
+
+    # Emit continue response (don't block anything)
+    print(json.dumps({"continue": True}))
+
+
+if __name__ == "__main__":
+    main()