From f2f8f9bdbb02e4c0f6075ff435258c31dc0c3f85 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:08:36 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 +++ README.md | 3 + SKILL.md | 190 +++++++++++++++++++++++++++++++++++++ plugin.lock.json | 45 +++++++++ 4 files changed, 250 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..7dcdb68 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "codex-cli", + "description": "Execute Codex CLI for code analysis, refactoring, and automated code changes with file references (@syntax) and structured output", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Claude Code Dev Workflows", + "email": "contact@example.com" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c696e14 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# codex-cli + +Execute Codex CLI for code analysis, refactoring, and automated code changes with file references (@syntax) and structured output diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..28de131 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,190 @@ +--- +name: codex +description: Execute Codex CLI for code analysis, refactoring, and automated code changes. Use when you need to delegate complex code tasks to Codex AI with file references (@syntax) and structured output. +--- + +# Codex CLI Integration + +## Overview + +Execute Codex CLI commands and parse structured JSON responses. Supports file references via `@` syntax, multiple models, and sandbox controls. + +## When to Use + +- Complex code analysis requiring deep understanding +- Large-scale refactoring across multiple files +- Automated code generation with safety controls + +## Usage + +**Mandatory**: Run every automated invocation through the Bash tool in the foreground with **HEREDOC syntax** to avoid shell quoting issues, keeping the `timeout` parameter fixed at `7200000` milliseconds (do not change it or use any other entry point). + +```bash +codex-wrapper - [working_dir] <<'EOF' + +EOF +``` + +**Why HEREDOC?** Tasks often contain code blocks, nested quotes, shell metacharacters (`$`, `` ` ``, `\`), and multiline text. HEREDOC (Here Document) syntax passes these safely without shell interpretation, eliminating quote-escaping nightmares. + +**Foreground only (no background/BashOutput)**: Never set `background: true`, never accept Claude's "Running in the background" mode, and avoid `BashOutput` streaming loops. Keep a single foreground Bash call per Codex task; if work might be long, split it into smaller foreground runs instead of offloading to background execution. + +**Simple tasks** (backward compatibility): +For simple single-line tasks without special characters, you can still use direct quoting: +```bash +codex-wrapper "simple task here" [working_dir] +``` + +**Resume a session with HEREDOC:** +```bash +codex-wrapper resume - [working_dir] <<'EOF' + +EOF +``` + +**Cross-platform notes:** +- **Bash/Zsh**: Use `<<'EOF'` (single quotes prevent variable expansion) +- **PowerShell 5.1+**: Use `@'` and `'@` (here-string syntax) + ```powershell + codex-wrapper - @' + task content + '@ + ``` + +## Environment Variables + +- **CODEX_TIMEOUT**: Override timeout in milliseconds (default: 7200000 = 2 hours) + - Example: `export CODEX_TIMEOUT=3600000` for 1 hour + +## Timeout Control + +- **Built-in**: Binary enforces 2-hour timeout by default +- **Override**: Set `CODEX_TIMEOUT` environment variable (in milliseconds, e.g., `CODEX_TIMEOUT=3600000` for 1 hour) +- **Behavior**: On timeout, sends SIGTERM, then SIGKILL after 5s if process doesn't exit +- **Exit code**: Returns 124 on timeout (consistent with GNU timeout) +- **Bash tool**: Always set `timeout: 7200000` parameter for double protection + +### Parameters + +- `task` (required): Task description, supports `@file` references +- `working_dir` (optional): Working directory (default: current) + +### Return Format + +Extracts `agent_message` from Codex JSON stream and appends session ID: +``` +Agent response text here... + +--- +SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14 +``` + +Error format (stderr): +``` +ERROR: Error message +``` + +Return only the final agent message and session ID—do not paste raw `BashOutput` logs or background-task chatter into the conversation. + +### Invocation Pattern + +All automated executions must use HEREDOC syntax through the Bash tool in the foreground, with `timeout` fixed at `7200000` (non-negotiable): + +``` +Bash tool parameters: +- command: codex-wrapper - [working_dir] <<'EOF' + + EOF +- timeout: 7200000 +- description: +``` + +Run every call in the foreground—never append `&` to background it—so logs and errors stay visible for timely interruption or diagnosis. + +**Important:** Use HEREDOC (`<<'EOF'`) for all but the simplest tasks. This prevents shell interpretation of quotes, variables, and special characters. + +### Examples + +**Basic code analysis:** +```bash +# Recommended: with HEREDOC (handles any special characters) +codex-wrapper - <<'EOF' +explain @src/main.ts +EOF +# timeout: 7200000 + +# Alternative: simple direct quoting (if task is simple) +codex-wrapper "explain @src/main.ts" +``` + +**Refactoring with multiline instructions:** +```bash +codex-wrapper - <<'EOF' +refactor @src/utils for performance: +- Extract duplicate code into helpers +- Use memoization for expensive calculations +- Add inline comments for non-obvious logic +EOF +# timeout: 7200000 +``` + +**Multi-file analysis:** +```bash +codex-wrapper - "/path/to/project" <<'EOF' +analyze @. and find security issues: +1. Check for SQL injection vulnerabilities +2. Identify XSS risks in templates +3. Review authentication/authorization logic +4. Flag hardcoded credentials or secrets +EOF +# timeout: 7200000 +``` + +**Resume previous session:** +```bash +# First session +codex-wrapper - <<'EOF' +add comments to @utils.js explaining the caching logic +EOF +# Output includes: SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14 + +# Continue the conversation with more context +codex-wrapper resume 019a7247-ac9d-71f3-89e2-a823dbd8fd14 - <<'EOF' +now add TypeScript type hints and handle edge cases where cache is null +EOF +# timeout: 7200000 +``` + +**Task with code snippets and special characters:** +```bash +codex-wrapper - <<'EOF' +Fix the bug in @app.js where the regex /\d+/ doesn't match "123" +The current code is: + const re = /\d+/; + if (re.test(input)) { ... } +Add proper escaping and handle $variables correctly. +EOF +``` + +### Large Task Protocol + +- For every large task, first produce a canonical task list that enumerates the Task ID, description, file/directory scope, dependencies, test commands, and the expected Codex Bash invocation. +- Tasks without dependencies should be executed concurrently via multiple foreground Bash calls (you can keep separate terminal windows) and each run must log start/end times plus any shared resource usage. +- Reuse context aggressively (such as @spec.md or prior analysis output), and after concurrent execution finishes, reconcile against the task list to report which items completed and which slipped. + +| ID | Description | Scope | Dependencies | Tests | Command | +| --- | --- | --- | --- | --- | --- | +| T1 | Review @spec.md to extract requirements | docs/, @spec.md | None | None | `codex-wrapper - <<'EOF'`
`analyze requirements @spec.md`
`EOF` | +| T2 | Implement the module and add test cases | src/module | T1 | npm test -- --runInBand | `codex-wrapper - <<'EOF'`
`implement and test @src/module`
`EOF` | + +## Notes + +- **Binary distribution**: Single Go binary, zero dependencies +- **Installation**: Download from GitHub Releases or use install.sh +- **Cross-platform compatible**: Linux (amd64/arm64), macOS (amd64/arm64) +- All automated runs must use the Bash tool with the fixed timeout to provide dual timeout protection and unified logging/exit semantics +for automation (new sessions only) +- Uses `--skip-git-repo-check` to work in any directory +- Streams progress, returns only final agent message +- Every execution returns a session ID for resuming conversations +- Requires Codex CLI installed and authenticated diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..42b6aab --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:cexll/myclaude:skills/codex/", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "d5f284fb23e6dc61d6eff721a4ca1cccc116a139", + "treeHash": "3d63771d076eb710e95dcb18fb15d491b921da8f86fd5894aeb72e2f49e424a6", + "generatedAt": "2025-11-28T10:14:58.950171Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "codex-cli", + "description": "Execute Codex CLI for code analysis, refactoring, and automated code changes with file references (@syntax) and structured output", + "version": null + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "560f140b269df9a02c42bbdbcbeacf627a82a89f0567a44e3b27acaa02d46bc3" + }, + { + "path": "SKILL.md", + "sha256": "1f3a87eed1bc997207152a79b0b9423af7dccf350c78369cdc11c6421723dafe" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "3fe9274259a8a227fb85c3184bc8d19ad8bf1305ec5a1b25e54d1425d136a9b7" + } + ], + "dirSha256": "3d63771d076eb710e95dcb18fb15d491b921da8f86fd5894aeb72e2f49e424a6" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file