diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index dfd4ccb..d35ff3d 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -1,7 +1,7 @@ { "name": "claude-plugin-codex", "interface": { - "displayName": "Claude Plugin Codex" + "displayName": "Claude Code Advisor for Codex" }, "plugins": [ { diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..382e8e8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,92 @@ +name: Bug report +description: Report a reproducible problem with Claude Code Advisor for Codex +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Do not post security vulnerabilities or secrets here. Report vulnerabilities using SECURITY.md. Sanitise every log and attachment. + - type: checkboxes + id: checks + attributes: + label: Pre-submission checks + options: + - label: I searched existing issues for this problem. + required: true + - label: I tested the latest release and started a new Codex thread or restarted Codex. + required: true + - label: This report contains no credentials, tokens, cookies, session data, private source code or personal information. + required: true + - label: This is not a security vulnerability. + required: true + - type: input + id: plugin-version + attributes: + label: Plugin version + placeholder: 0.1.14 or commit SHA + validations: + required: true + - type: input + id: environment + attributes: + label: Environment + description: Operating system and architecture + placeholder: macOS 15.6, Apple silicon + validations: + required: true + - type: input + id: tool-versions + attributes: + label: Tool versions + description: Codex, Claude Code and Node.js versions + placeholder: Codex x.y.z, Claude Code x.y.z, Node.js x.y.z + validations: + required: true + - type: textarea + id: command + attributes: + label: Command or action + description: Provide the exact command after removing sensitive values. + render: text + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: List the smallest sequence that consistently reproduces the problem. + placeholder: | + 1. Install the plugin... + 2. Start a new Codex thread... + 3. Run... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behaviour + validations: + required: true + - type: textarea + id: actual + attributes: + label: Observed behaviour + validations: + required: true + - type: textarea + id: diagnostics + attributes: + label: Sanitised diagnostics + description: Include only the smallest relevant output. Remove secrets, private paths, private prompts, private source and personal information. + render: text + validations: + required: false + - type: textarea + id: context + attributes: + label: Additional context + description: Add other relevant, non-sensitive details or sanitised screenshots. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..8953882 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,56 @@ +name: Feature request +description: Propose a focused improvement to Claude Code Advisor for Codex +title: "[Feature]: " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Describe the user problem before the implementation. Do not include credentials, private source code or other sensitive material. + - type: checkboxes + id: checks + attributes: + label: Pre-submission checks + options: + - label: I searched existing issues and pull requests for this proposal. + required: true + - label: This proposal is within the plugin's Codex and local Claude Code integration scope. + required: true + - label: This request contains no credentials, tokens, private source code or personal information. + required: true + - type: textarea + id: problem + attributes: + label: Problem + description: What is difficult or impossible today, and who is affected? + validations: + required: true + - type: textarea + id: outcome + attributes: + label: Desired outcome + description: Describe the observable result rather than only a proposed implementation. + validations: + required: true + - type: textarea + id: approach + attributes: + label: Suggested approach + description: Optional implementation ideas and trade-offs. + validations: + required: false + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Existing commands, workarounds or simpler alternatives you tried. + validations: + required: false + - type: textarea + id: context + attributes: + label: Additional context + description: Add relevant, non-sensitive examples or links. + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..63056d0 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ +## Summary + +Describe the problem, the approach and any user-visible effect. + +## Related issue + +Link the issue or explain why one is not needed. + +## Validation + +- [ ] I ran `npm run validate`. +- [ ] I ran `npm run test:smoke`, or the change does not affect Claude CLI invocation, runtime behaviour or installation instructions. +- [ ] I ran `npm run test:e2e:codex`, or the change does not affect Codex routing, skill instructions or public installation. +- [ ] I added or updated tests for behaviour changes. + +List relevant results and explain any check that could not be run. + +## Safety and release checks + +- [ ] This change contains no credentials, tokens, cookies, private prompts, private source code, personal information or unsanitised diagnostics. +- [ ] I preserved the MIT licence and original Yanchuk attribution. +- [ ] Public copy does not imply affiliation with or endorsement by Anthropic or OpenAI. +- [ ] New dependencies, permissions and write-capable behaviour are documented and justified, or none were added. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..667e046 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,28 @@ +# Changelog + +All notable public changes to Claude Code Advisor for Codex are recorded here. + +## 0.1.14 - 2026-08-18 + +- clarify the community-maintained product name and non-affiliation statement +- add direct CLI installation, update and removal instructions +- add compatibility status and beta exit criteria +- add public privacy, terms, security, support and contribution documentation +- add issue templates, pull request guidance and launch visual assets +- publish a concise command reference for users + +## 0.1.13 - 2026-08-17 + +First release from the Bold New Media maintained fork. + +- harden structured review extraction and validation +- include complete staged and base review diffs and reject unsafe untracked-file + reviews +- improve background lifecycle monitoring, cancellation and result recovery +- isolate inherited MCP configuration for unattended work by default +- restrict local state directory and file permissions +- add sandbox-safe end-to-end Codex routing coverage +- verify deterministic tests and metadata on Node.js 20, 22 and 24 + +See the [v0.1.13 release](https://github.com/BoldNewMedia/claude-plugin-codex/releases/tag/v0.1.13) +for the published tag. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..17ed907 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,29 @@ +# Code of conduct + +## Expected behaviour + +Participate constructively and professionally. Focus criticism on evidence, +ideas and changes. Respect differences in experience, identity, background and +viewpoint. Accept correction and take responsibility for mistakes. + +## Unacceptable behaviour + +Harassment, discrimination, threats, personal attacks, sexualised attention, +doxxing, deliberate intimidation and sustained disruption are not accepted. +Do not publish another person's private information or credentials. + +## Scope + +This code applies in the repository and in public spaces when a person is +representing the project or its community. + +## Reporting and enforcement + +Report conduct concerns privately to the maintainers where possible. If no +private contact route is available, open a public issue requesting private +contact without describing the incident or identifying the people involved. + +Maintainers may remove or edit contributions and may temporarily or permanently +restrict participation when behaviour is unsafe, abusive or persistently +disruptive. Reports will be handled as confidentially as practical and assessed +without regard to a contributor's role or status. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7d554fa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing + +Contributions that improve reliability, safety, documentation and compatibility +are welcome. + +## Before starting + +- Search existing issues and pull requests. +- Open an issue before a substantial change so the scope can be agreed first. +- Keep changes focused. Separate unrelated fixes. +- Do not include credentials, tokens, private prompts, private source code or + personal information in issues, tests, fixtures or commits. +- Report security vulnerabilities using [SECURITY.md](SECURITY.md), not a + public issue. + +## Development + +Requirements: + +- Node.js 18.18 or newer +- Codex with plugin marketplace support for end-to-end testing +- a locally installed and authenticated Claude Code CLI for smoke testing + +Run the standard validation before submitting a pull request: + +```bash +npm run validate +``` + +If the change affects Claude CLI invocation, runtime behaviour or installation +instructions, also run: + +```bash +npm run test:smoke +``` + +If the change affects Codex routing, skill instructions or public installation, +also run: + +```bash +npm run test:e2e:codex +``` + +State which checks you ran and explain any check you could not run. Sanitise all +diagnostic output before sharing it. + +## Pull requests + +- Link the relevant issue where one exists. +- Explain the problem, the chosen approach and user-visible effects. +- Add or update tests for behaviour changes. +- Preserve the MIT licence and original Yanchuk attribution. +- Keep public copy clear that this is an unofficial community project, not an + Anthropic or OpenAI product. +- Avoid adding dependencies unless their benefit justifies the maintenance and + security cost. + +By contributing, you agree that your contribution is licensed under the +project's [MIT licence](LICENSE). diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..beeda22 --- /dev/null +++ b/PRIVACY.md @@ -0,0 +1,81 @@ +# Privacy policy + +Effective 18 August 2026 + +This policy applies to Claude Code Advisor for Codex, maintained by Bold New +Media. The plugin is an unofficial community project and is not affiliated with +OpenAI or Anthropic. + +## Summary + +The plugin runs locally. Bold New Media does not operate a hosted service for +the plugin, receive plugin prompts or results, collect analytics, or receive +Claude Code credentials. + +## Data the plugin handles + +When you invoke the plugin, it may handle: + +- the task prompt and options you provide +- local file content, Git diffs, file paths and repository metadata needed for + the requested review or task +- Claude Code output and command status +- local job metadata, including job identifiers, timestamps, workspace paths + and saved results + +The exact content depends on the command and permissions you approve. + +## Purpose and processing + +The plugin uses this information only to run the requested Claude Code task, +validate or display its result, and manage foreground or background job state. + +The plugin invokes the official Claude Code CLI installed and authenticated on +your machine. Content supplied to Claude Code is processed under your Anthropic +account and Anthropic's applicable terms and privacy policy. Your Codex host may +also process conversation and tool-call content under your OpenAI agreement. + +Bold New Media is not a recipient of this content through the plugin. + +## Credentials + +The plugin does not request, copy or store your Claude Code password, token or +session credentials. Authentication remains controlled by the installed Claude +Code CLI. + +## Local storage and retention + +Job metadata and results are stored locally under +`~/.codex/claude-plugin-codex` unless you set +`CLAUDE_COMPANION_STATE_ROOT`. Stored content remains until it is overwritten +or you remove it. Removing the plugin does not necessarily remove this separate +state directory. + +You control retention by choosing the state root and deleting saved state when +no plugin job is running. Treat the state directory as private because it can +contain prompts, results and local workspace paths. + +## Telemetry and tracking + +The plugin does not intentionally phone home, serve advertising, set tracking +cookies or collect usage analytics for Bold New Media. + +GitHub may collect ordinary repository traffic when you visit or download the +public repository under GitHub's own policies. + +## Your controls + +You can: + +- omit `--write` to keep supported task routes read-only +- omit `--allow-web` and `--allow-mcp` to keep those optional capabilities off +- inspect the source code and local state +- choose a separate local state root +- cancel managed jobs and remove saved local state +- uninstall the plugin at any time + +## Changes and contact + +Material changes will be recorded in the repository. For privacy or support +questions, follow [SUPPORT.md](SUPPORT.md). Do not post credentials, private +source code or personal information in a public GitHub issue. diff --git a/README.md b/README.md index ebb36d2..232af74 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,34 @@ -# claude-plugin-codex +# Claude Code Advisor for Codex + +[![CI](https://github.com/BoldNewMedia/claude-plugin-codex/actions/workflows/ci.yml/badge.svg)](https://github.com/BoldNewMedia/claude-plugin-codex/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/BoldNewMedia/claude-plugin-codex)](https://github.com/BoldNewMedia/claude-plugin-codex/releases) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +Catch hidden assumptions in Codex changes with a read-only Claude Code review, +without leaving Codex. Codex stays in charge of the task; your existing local +Claude Code installation supplies the second opinion. + +![Claude Code Advisor for Codex demo](docs/assets/claude-code-advisor-demo.png) + +This is an unofficial, community-maintained integration. It is not endorsed by +or affiliated with OpenAI or Anthropic. Maintained by [Bold New Media](https://github.com/BoldNewMedia). From v0.1.13, releases come from this maintained fork of the original [`yanchuk/claude-plugin-codex`](https://github.com/yanchuk/claude-plugin-codex) -project and retains its MIT licence and attribution. +project. The project retains its MIT licence and original attribution. ## Install -Add the public marketplace: +Add the public marketplace and install the plugin: ```bash codex plugin marketplace add BoldNewMedia/claude-plugin-codex +codex plugin add claude-code-advisor@claude-plugin-codex ``` -Then open Codex's plugin directory, find `Claude Plugin Codex`, and install -`Claude`. +Alternatively, after adding the marketplace, open Codex's plugin directory, +find **Claude Code Advisor for Codex**, and install **Claude Code Advisor**. Start a new Codex thread and verify the install: @@ -25,6 +39,21 @@ $claude setup If Codex was already running, start a new thread or restart Codex before using `$claude`. +To update the marketplace snapshot and reinstall the current plugin version: + +```bash +codex plugin marketplace upgrade claude-plugin-codex +codex plugin remove claude-code-advisor@claude-plugin-codex +codex plugin add claude-code-advisor@claude-plugin-codex +``` + +To remove the plugin and its marketplace source: + +```bash +codex plugin remove claude-code-advisor@claude-plugin-codex +codex plugin marketplace remove claude-plugin-codex +``` + ## What It Is If you already use Codex and Claude Code, this plugin brings Claude Code into @@ -43,12 +72,28 @@ This is the inverse of plugin pulls Codex into Claude Code. This one pulls local Claude Code into Codex. -## Status +## Status and compatibility -Alpha. The Codex marketplace flow has been verified with Codex CLI `0.130.0`. +Alpha. Use it on real work only with normal review and source-control controls. The stable command form is `$claude`. If your Codex UI exposes the skill as `/claude`, you can use that as an alias. +| Component | Verified status | +|---|---| +| Codex CLI | Marketplace and end-to-end routing verified with `0.130.0` | +| Claude Code CLI | Capability detection verified with `2.1.201`; an authenticated local account is required | +| Node.js | Automated tests run on 20, 22 and 24; runtime minimum is 18.18 | +| macOS | Live local workflow verified | +| Linux | Deterministic tests and metadata validation run in GitHub Actions | +| Windows | Not yet independently verified; tester reports are welcome | + +Before beta, the project needs repeatable external installation results on +macOS, Linux and Windows, with no unresolved recurring permission or background +lifecycle defects. + +See the [alpha testing guide](docs/alpha-testing.md) to join the initial +compatibility cohort. Windows and Linux reports are particularly useful. + ## Core Commands - `$claude setup` checks whether Claude Code is installed, authenticated, and @@ -65,6 +110,9 @@ The stable command form is `$claude`. If your Codex UI exposes the skill as active, stale, or finished. - `$claude status`, `$claude result`, and `$claude cancel` manage Claude jobs. +See the [command reference](docs/commands.md) for complete syntax, examples and +safety flags. + Longer jobs can run in the background: ```text @@ -249,6 +297,9 @@ so `$claude status`, `$claude result`, and `$claude cancel` can work across turns. It does not intentionally collect analytics, phone home, or send data to the repository owner. +See the full [privacy policy](PRIVACY.md) for data categories, recipients, +retention and user controls. + ## State Storage By default the companion stores state under: @@ -272,7 +323,8 @@ workspace paths, and review results. ## Terms This project is provided under the MIT License. You are responsible for how you -use Codex, Claude Code, and any data you send through those tools. +use Codex, Claude Code, and any data you send through those tools. See the full +[terms of use](TERMS.md). ## How It Works @@ -315,10 +367,11 @@ Optional end-to-end smoke test against an installed Codex plugin: npm run test:e2e:codex ``` -This requires `codex plugin marketplace add ./`, `Claude` installed from -Codex's plugin directory, and a logged-in Claude Code CLI. It starts a fresh -`codex exec` session and verifies that `$claude advise --model sonnet` routes -through the installed skill. The test uses Codex's `workspace-write` sandbox, +This requires `codex plugin marketplace add ./`, **Claude Code Advisor** +installed from Codex's plugin directory, and a logged-in Claude Code CLI. It +starts a fresh `codex exec` session and verifies that +`$claude advise --model sonnet` routes through the installed skill. The test +uses Codex's `workspace-write` sandbox, supplies a private temporary companion state root inside the checkout, and removes that state before checking the worktree. Sonnet is used only for this small routing test. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..33bcb53 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,43 @@ +# Security policy + +## Supported versions + +This project is alpha software. Security fixes are applied to the latest +release and the current `main` branch only. Older releases are not supported. + +## Reporting a vulnerability + +Do not report a vulnerability in a public issue, discussion, pull request or +log. + +Use GitHub's private vulnerability reporting form: + + + +If that form is unavailable, open a public issue containing only a request for +a private reporting channel. Do not include vulnerability details. + +Include: + +- the affected version or commit +- the operating system and relevant Codex, Claude Code and Node.js versions +- the smallest safe reproduction you can provide +- the expected and observed behaviour +- the likely impact and any suggested mitigation + +Remove credentials, tokens, cookies, personal information, private source code +and other secrets from every report and attachment. Never provide a Claude, +Anthropic, OpenAI or other account credential. + +The maintainers will assess reports on a best-effort basis. Please allow time +for a fix before public disclosure. + +## Security boundaries + +This plugin runs the locally installed `claude` CLI with the permissions of the +current user. It does not provide a security boundary around Claude Code, +Codex, the local repository or the operating system. Review prompts and +commands before running them, especially when enabling write access or MCP. + +This is an unofficial community project. It is not affiliated with, endorsed +by or supported by Anthropic or OpenAI. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..add492a --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,40 @@ +# Support + +This is an alpha, community-maintained project. Support is provided on a +best-effort basis through GitHub issues. + +## Before opening an issue + +1. Read the [README](README.md), including the requirements and status. +2. Update to the latest release. +3. Start a new Codex thread or restart Codex after installation. +4. Run `$claude setup` and check whether it identifies the problem. +5. Search existing issues for the same symptom. + +For reproducible plugin bugs, use the bug report issue form. For proposals, use +the feature request form. + +Include the plugin version, operating system, Node.js version, Codex version, +Claude Code version, the command used, expected behaviour, observed behaviour +and minimal reproduction steps. Include only sanitised diagnostic output. + +Never post credentials, tokens, cookies, session data, private prompts, private +source code, personal information or full environment dumps. Replace sensitive +values with clear placeholders before submitting anything. + +Security vulnerabilities must follow [SECURITY.md](SECURITY.md) and must not be +posted publicly. + +## Outside this project's support scope + +- Anthropic account, billing or Claude Code product support +- OpenAI account, billing or Codex product support +- general debugging of unrelated repositories +- guarantees for unreleased or unsupported third-party versions + +Use the relevant vendor's official support channel for vendor product or +account problems. + +Claude, Claude Code, Anthropic, Codex and OpenAI are names and marks of their +respective owners. This project is not affiliated with, endorsed by or +supported by Anthropic or OpenAI. diff --git a/TERMS.md b/TERMS.md new file mode 100644 index 0000000..885d258 --- /dev/null +++ b/TERMS.md @@ -0,0 +1,52 @@ +# Terms of use + +Effective 18 August 2026 + +Claude Code Advisor for Codex is an unofficial, community-maintained project. +It is not endorsed by or affiliated with OpenAI or Anthropic. + +## Licence + +The software is provided under the [MIT License](LICENSE). These terms describe +use of the project and do not replace the licence grant. + +## Your accounts and costs + +You must provide your own supported Codex and Claude Code installations and +accounts. You are responsible for account eligibility, subscriptions, usage +charges and compliance with the terms that apply to those products. + +## Your responsibility + +You control which repositories, files and prompts are made available to Codex +and Claude Code. Review generated advice and changes before relying on them. +Use source control, backups, tests and ordinary engineering review appropriate +to the risk of the work. + +Write-capable work requires explicit `--write`, but that safeguard does not +make generated changes correct or safe. + +## Acceptable use + +Do not use the project to bypass access controls, account restrictions, +provider policies or applicable law. Do not submit content you are not +authorised to process. + +## Alpha software + +The project is currently alpha software. Interfaces provided by Codex or Claude +Code can change, and compatibility can break without notice. The project may +change, suspend or remove features as it develops. + +## No warranty + +The software is supplied without warranty, as stated in the MIT License. To the +maximum extent permitted by law, the maintainers are not liable for losses +arising from use of the software, generated output, service interruption, +account action or third-party product changes. + +## Support and changes + +Support is provided on a reasonable-efforts community basis under +[SUPPORT.md](SUPPORT.md). Material changes to these terms will be recorded in +the repository. diff --git a/docs/alpha-testing.md b/docs/alpha-testing.md new file mode 100644 index 0000000..7b78bf1 --- /dev/null +++ b/docs/alpha-testing.md @@ -0,0 +1,59 @@ +# Alpha testing + +We are seeking a small group of developers who already use both Codex and +Claude Code. The goal is to verify installation, first-review success and +cross-platform reliability before beta. + +## Suitable testers + +You should have: + +- a supported local Codex installation with plugin marketplace support +- a supported, authenticated local Claude Code CLI +- Node.js 18.18 or newer +- a non-sensitive Git repository where you can run a read-only review + +Windows and Linux reports are especially useful because the live workflow has +so far been verified primarily on macOS. + +## Fifteen-minute test + +1. Install the marketplace and plugin using the [README](../README.md). +2. Start a new Codex task. +3. Run `$claude setup`. +4. In a repository with staged or tracked changes, run `$claude review` or + `$claude adversarial-review --base main`. +5. Decide whether the result found, confirmed or changed an engineering + decision. +6. Report the outcome using the GitHub bug form or the alpha feedback issue. + +Do not use confidential code for the first test. The plugin is alpha software, +and prompts and selected repository content are processed through your local +Claude Code account. + +## What to report + +- operating system and architecture +- Codex, Claude Code, Node.js and plugin versions +- setup success or failure +- first-review success or failure +- approximate minutes from installation to the first result +- whether the result was useful, a false positive or inconclusive +- the smallest sanitised error or reproduction when something failed + +Never provide credentials, session data, private source code, personal +information, full environment dumps or unsanitised paths. + +## Success criteria + +The beta decision will use the following evidence: + +- at least 10 external installations +- at least 80% setup success +- at least 70% successful first reviews +- median time to first useful result below 10 minutes +- no unresolved recurring permission or background lifecycle defect +- repeat use by at least five testers in a second week + +The project does not add phone-home analytics for this programme. Results are +collected only from information testers choose to report. diff --git a/docs/assets/claude-code-advisor-demo.png b/docs/assets/claude-code-advisor-demo.png new file mode 100644 index 0000000..e52385e Binary files /dev/null and b/docs/assets/claude-code-advisor-demo.png differ diff --git a/docs/assets/claude-code-advisor-demo.svg b/docs/assets/claude-code-advisor-demo.svg new file mode 100644 index 0000000..26ef08c --- /dev/null +++ b/docs/assets/claude-code-advisor-demo.svg @@ -0,0 +1,77 @@ + + Claude Code Advisor installation and adversarial review demo + An illustrative terminal session that adds the marketplace and plugin, checks setup, and returns one sanitised finding from an adversarial review. + + + + + + + + + + + + + + + + + + + + + + + + + + + + Claude Code Advisor + ILLUSTRATIVE SESSION + + + + 01 + % + codex plugin marketplace add BoldNewMedia/claude-plugin-codex + ✓ Marketplace added + + 02 + % + codex plugin add claude-code-advisor@claude-plugin-codex + ✓ Plugin enabled + + 03 + › + $claude setup + Claude Code found · authentication ready · read-only review available + + 04 + › + $claude adversarial-review + Challenge the rollout plan and identify hidden assumptions. + + + + + + + + FINDING + Sanitised illustrative output + + + [P1] Rollback depends on a schema that the migration removes + The plan drops the legacy column before every reader has moved. + A rollback would restore the old code without restoring its data. + Next: split the schema change into a later, separately verified release. + + + + + Local Claude Code · Codex remains the orchestrator · read-only by default + Unofficial community plugin + + diff --git a/docs/assets/launch-assets.json b/docs/assets/launch-assets.json new file mode 100644 index 0000000..521bce7 --- /dev/null +++ b/docs/assets/launch-assets.json @@ -0,0 +1,25 @@ +{ + "assets": [ + { + "file": "social-preview.png", + "source": "social-preview.svg", + "width": 1280, + "height": 640, + "purpose": "GitHub social preview and link-sharing card" + }, + { + "file": "claude-code-advisor-demo.png", + "source": "claude-code-advisor-demo.svg", + "width": 1280, + "height": 800, + "purpose": "Static install and adversarial-review walkthrough" + } + ], + "provenance": { + "method": "Deterministic SVG composition rasterised locally with ImageMagick", + "externalDownloads": false, + "aiImageGeneration": false, + "brandSource": "plugins/claude-code-advisor/assets/icon.svg", + "notes": "The demo finding is sanitised illustrative copy and is not presented as a result from this repository." + } +} diff --git a/docs/assets/social-preview.png b/docs/assets/social-preview.png new file mode 100644 index 0000000..8f6f8c1 Binary files /dev/null and b/docs/assets/social-preview.png differ diff --git a/docs/assets/social-preview.svg b/docs/assets/social-preview.svg new file mode 100644 index 0000000..b9fae49 --- /dev/null +++ b/docs/assets/social-preview.svg @@ -0,0 +1,45 @@ + + Claude Code Advisor for Codex + Social preview for an unofficial community plugin that brings local Claude Code reviews into Codex. + + + + + + + + + + + + + + + + + + + + + + + + + + Claude Code Advisor + A second opinion for Codex. + + + + + Read-only reviews · adversarial checks · local Claude Code + Codex stays in charge. Claude challenges the assumptions. + + + + + $claude adversarial-review + + Unofficial community plugin + + diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..300a9d9 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,303 @@ +# Claude Code Advisor cheat sheet + +Use these commands in a Codex chat, not in Terminal. + +Claude Code Advisor for Codex is an unofficial, community-maintained +integration. It is not endorsed by or affiliated with OpenAI or Anthropic. + +For installation, compatibility and privacy information, see the main +[README](../README.md). + +The reliable invocation is `$claude`. You can also type `@`, select **Claude Code Advisor**, and then enter a `$claude` command. Slash forms are best-effort aliases only. + +## Quick picker + +| Need | Command | +|---|---| +| Check installation and login | `$claude setup` | +| Get a second opinion | `$claude advise ` | +| Give Claude a specific prepared task | `$claude do ` | +| Hand off deeper debugging | `$claude rescue ` | +| Review the current Git changes | `$claude review` | +| Challenge assumptions or hidden risks | `$claude adversarial-review [focus]` | +| Watch a background job | `$claude monitor ` | +| Check job state | `$claude status [job-id]` | +| Retrieve a job result | `$claude result ` | +| Stop a background job | `$claude cancel ` | +| Find a safe job to continue | `$claude resume-candidate` | + +## Complete syntax + +```text +$claude setup [--json] +$claude advise [--background] [--write] [--max-turns ] [--effort ] [--allow-mcp] [--allow-web] [--no-background-fallback] [prompt] +$claude do [--background] [--write] [--model ] [--max-turns ] [--effort ] [--allow-mcp] [--allow-web] [prompt] +$claude rescue [--background] [--write] [--resume] [--model ] [--max-turns ] [--effort ] [--allow-mcp] [--allow-web] [--no-background-fallback] [prompt] +$claude review [--base ] [--max-turns ] [--effort ] [--json] +$claude adversarial-review [--base ] [--max-turns ] [--effort ] [focus] [--json] +$claude monitor [job-id] [--interval-ms ] [--max-checks ] [--stale-after-ms ] [--json] +$claude status [job-id] [--watch] [--json] +$claude result [job-id] [--json] +$claude cancel [job-id] [--json] +$claude resume-candidate [--json] +``` + +Codex normally manages `--effort`, monitoring intervals and JSON output. Use the simpler forms elsewhere in this sheet unless you have a specific reason to override them. + +## Invocation + +Explicitly select the plugin and run a command: + +```text +@Claude Code Advisor $claude advise Check this architecture for hidden failure modes. +``` + +Once the plugin is available, the skill command alone is sufficient: + +```text +$claude advise Check this architecture for hidden failure modes. +``` + +## Commands + +### `setup` + +Checks Node.js, Claude Code version, authentication and required capabilities. + +```text +$claude setup +``` + +### `advise` + +Use for architecture questions, trade-offs, second opinions and evidence checks. + +```text +$claude advise [--background] [--write] [--max-turns ] +``` + +Examples: + +```text +$claude advise Should this queue use at-least-once or exactly-once delivery? +$claude advise --background Review this migration plan for data-loss risks. +``` + +`advise` can use web tools. It is read-only unless `--write` is explicit. + +### `do` + +Use for a specific, prepared coding, exploration, scout, verifier, review or synthesis task. + +```text +$claude do [--background] [--write] [--model sonnet|opus] [--max-turns ] +``` + +Examples: + +```text +$claude do --background --model opus Inspect the authentication flow, cite exact files and report only. +$claude do --background --write --model opus Implement the approved fix within src/auth and run npm test. +``` + +Use Sonnet only for a tightly bounded junior-agent task. A prepared Sonnet prompt must state: + +```text +Role: +Word cap: <400-600 words unless coding output requires otherwise> +Targets: +What Must Be True: +- +Known Constraints: +- +Mechanical Verification: +- +Stop Conditions: +- +``` + +Use Opus for ambiguous debugging, broad refactors, architecture, authentication, money, migrations, personal information, provider reliability and other high-judgement work. + +### `rescue` + +Use for substantial debugging, a stalled task or deeper implementation help. + +```text +$claude rescue [--background] [--write] [--resume] [--model sonnet|opus] [--max-turns ] +``` + +Examples: + +```text +$claude rescue --background --model opus Diagnose the flaky integration test and report the root cause. +$claude rescue --background --write --model opus Fix the confirmed race condition and run the relevant tests. +$claude rescue --resume --background Continue the selected Claude job from its saved state. +``` + +`rescue` is read-only unless `--write` is explicit. + +### `review` + +Runs a short, structured, read-only review of local Git state. + +```text +$claude review [--base ] +``` + +Examples: + +```text +$claude review +$claude review --base main +``` + +Untracked files are not present in a Git diff. Stage intended new files before relying on structured review. + +### `adversarial-review` + +Challenges a plan or diff and looks for hidden assumptions, failure modes and regressions. It is always read-only. + +```text +$claude adversarial-review [--base ] [focus] +``` + +Examples: + +```text +$claude adversarial-review --base main +$claude adversarial-review --base main Focus on authentication bypass and data loss. +``` + +### `monitor` + +Polls logs and agent state for a managed background job. + +```text +$claude monitor [job-id] +``` + +Example: + +```text +$claude monitor claude-job-123 +``` + +The normal monitor interval is 30 seconds. It reports active, stale or finished state and the latest meaningful output. + +### `status` + +Shows the state of one job or the current workspace's managed jobs. + +```text +$claude status [job-id] +``` + +Examples: + +```text +$claude status +$claude status claude-job-123 +``` + +### `result` + +Returns the saved result for a managed job. + +```text +$claude result +``` + +### `cancel` + +Stops a managed background job. Saved output may still be recoverable with `result`. + +```text +$claude cancel +``` + +### `resume-candidate` + +Finds a safe candidate when you ask to continue but do not have a job ID. + +```text +$claude resume-candidate +``` + +Do not resume automatically if more than one candidate requires explicit selection. + +## Background-job workflow + +```text +$claude advise --background Review this rollout plan for failure modes. +$claude monitor +$claude status +$claude result +``` + +To stop instead: + +```text +$claude cancel +``` + +Use background mode for substantial prompts, large context or work likely to take more than one short answer. + +## Common flags + +| Flag | Meaning | +|---|---| +| `--background` | Run as a managed background job and return a job ID. | +| `--write` | Explicitly allow Claude to change files. Omit it for read-only work. | +| `--model opus` | Use Opus for complex or high-judgement work. | +| `--model sonnet` | Use Sonnet only for a prepared, bounded junior-agent task. | +| `--max-turns ` | Override the default Claude turn budget. | +| `--base ` | Compare a review against a Git reference such as `main`. | +| `--resume` | Continue a selected saved Claude job. | +| `--allow-web` | Permit web tools for a prepared `do` or `rescue` task. Use only when external sources are required. | +| `--allow-mcp` | Permit project MCP servers. Use only after explicit approval. | + +Advanced companion flags normally managed by Codex include `--effort `, `--no-background-fallback`, `--interval-ms `, `--max-checks `, `--stale-after-ms `, `--watch` and `--json`. + +## Safety rules + +- `review` and `adversarial-review` are read-only. +- `advise`, `do` and `rescue` require explicit `--write` before Claude can modify files. +- Project MCP servers are isolated by default. Background mode refuses workspaces containing `.mcp.json` unless `--allow-mcp` is explicitly approved. +- Prepared local `do` and `rescue` tasks use local read tools by default. Add `--allow-web` only when the task genuinely needs external sources. +- Do not default ordinary advice or review work to Sonnet. Use the configured Claude model unless a specific model is justified. + +## Slash aliases + +These may work when the Codex UI passes slash-style text through to the skill, but `$claude` is the portable form. + +| Alias | Reliable equivalent | +|---|---| +| `/claude setup` or `/claude:setup` | `$claude setup` | +| `/claude:advise ` | `$claude advise ` | +| `/claude:do ` | `$claude do ` | +| `/claude:rescue ` | `$claude rescue ` | +| `/claude:review [--base ]` | `$claude review [--base ]` | +| `/claude:adversarial-review [focus]` | `$claude adversarial-review [focus]` | +| `/claude:monitor [job-id]` | `$claude monitor [job-id]` | +| `/claude:status [job-id]` | `$claude status [job-id]` | +| `/claude:result ` | `$claude result ` | +| `/claude:cancel ` | `$claude cancel ` | + +## Recommended defaults + +```text +# Normal second pass +$claude review --base main + +# Challenge a high-risk change +$claude adversarial-review --base main Focus on security, migrations and rollback. + +# Substantive second opinion +$claude advise --background Check this plan against the evidence and identify unsupported assumptions. + +# Deep read-only debugging +$claude rescue --background --model opus Diagnose the failure, cite evidence and do not modify files. + +# Approved implementation +$claude do --background --write --model opus Implement the approved change within the stated paths and run the named verification commands. +``` diff --git a/package.json b/package.json index 7bd4b4a..4543aa8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-plugin-codex", - "version": "0.1.13", + "version": "0.1.14", "description": "Bring local Claude Code into Codex for reviews, prepared tasks, advice, and rescue work.", "type": "module", "private": true, diff --git a/plugins/claude-code-advisor/.codex-plugin/plugin.json b/plugins/claude-code-advisor/.codex-plugin/plugin.json index 4ce95f6..bc51177 100644 --- a/plugins/claude-code-advisor/.codex-plugin/plugin.json +++ b/plugins/claude-code-advisor/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "claude-code-advisor", - "version": "0.1.13", + "version": "0.1.14", "description": "Bring local Claude Code into Codex for reviews, prepared tasks, advice, and rescue work.", "author": { "name": "Yanchuk and contributors" @@ -19,9 +19,9 @@ ], "skills": "./skills/", "interface": { - "displayName": "Claude", - "shortDescription": "Ask local Claude Code from Codex.", - "longDescription": "Use local Claude Code from Codex for read-only reviews, adversarial checks, quick advice, prepared tasks, and explicit rescue work while Codex stays in charge.", + "displayName": "Claude Code Advisor", + "shortDescription": "Run local Claude Code reviews from Codex.", + "longDescription": "Community-maintained integration for using local Claude Code from Codex for read-only reviews, adversarial checks, quick advice, prepared tasks, and explicit rescue work while Codex stays in charge.", "developerName": "Bold New Media", "category": "Coding", "capabilities": [ @@ -29,8 +29,8 @@ "Write" ], "websiteURL": "https://github.com/BoldNewMedia/claude-plugin-codex", - "privacyPolicyURL": "https://github.com/BoldNewMedia/claude-plugin-codex#privacy", - "termsOfServiceURL": "https://github.com/BoldNewMedia/claude-plugin-codex#terms", + "privacyPolicyURL": "https://github.com/BoldNewMedia/claude-plugin-codex/blob/main/PRIVACY.md", + "termsOfServiceURL": "https://github.com/BoldNewMedia/claude-plugin-codex/blob/main/TERMS.md", "defaultPrompt": [ "Check Claude Code setup.", "Review or adversarially review this diff with Claude Code.", diff --git a/tests/validate-plugin.mjs b/tests/validate-plugin.mjs index 994e018..5fb5408 100644 --- a/tests/validate-plugin.mjs +++ b/tests/validate-plugin.mjs @@ -11,7 +11,7 @@ const e2e = fs.readFileSync("tests/e2e-codex-skill.mjs", "utf8"); assert.equal(manifest.name, "claude-code-advisor"); assert.equal(manifest.version, packageJson.version); assert.equal(manifest.skills, "./skills/"); -assert.equal(manifest.interface?.displayName, "Claude"); +assert.equal(manifest.interface?.displayName, "Claude Code Advisor"); assert.deepEqual(manifest.interface?.capabilities, ["Read", "Write"]); assert.ok(manifest.interface?.defaultPrompt?.length <= 3); assert.ok(manifest.interface.defaultPrompt.every((prompt) => prompt.length <= 128)); @@ -19,13 +19,33 @@ assert.equal(manifest.homepage, "https://github.com/BoldNewMedia/claude-plugin-c assert.equal(manifest.repository, "https://github.com/BoldNewMedia/claude-plugin-codex"); assert.equal(manifest.interface?.developerName, "Bold New Media"); assert.equal(manifest.interface?.websiteURL, "https://github.com/BoldNewMedia/claude-plugin-codex"); -assert.equal(manifest.interface?.privacyPolicyURL, "https://github.com/BoldNewMedia/claude-plugin-codex#privacy"); -assert.equal(manifest.interface?.termsOfServiceURL, "https://github.com/BoldNewMedia/claude-plugin-codex#terms"); +assert.equal(manifest.interface?.privacyPolicyURL, "https://github.com/BoldNewMedia/claude-plugin-codex/blob/main/PRIVACY.md"); +assert.equal(manifest.interface?.termsOfServiceURL, "https://github.com/BoldNewMedia/claude-plugin-codex/blob/main/TERMS.md"); assert.match(readme, /codex plugin marketplace add BoldNewMedia\/claude-plugin-codex/); +assert.match(readme, /codex plugin add claude-code-advisor@claude-plugin-codex/); assert.match(readme, /maintained fork/); assert.doesNotMatch(readme, /codex plugin marketplace add yanchuk\/claude-plugin-codex/); +assert.equal(marketplace.interface?.displayName, "Claude Code Advisor for Codex"); assert.ok(fs.existsSync("plugins/claude-code-advisor/assets/icon.svg")); assert.ok(fs.existsSync("plugins/claude-code-advisor/assets/logo.svg")); +for (const publicPath of [ + "CHANGELOG.md", + "CODE_OF_CONDUCT.md", + "CONTRIBUTING.md", + "PRIVACY.md", + "SECURITY.md", + "SUPPORT.md", + "TERMS.md", + "docs/alpha-testing.md", + "docs/commands.md", + "docs/assets/social-preview.png", + "docs/assets/claude-code-advisor-demo.png", + ".github/ISSUE_TEMPLATE/bug_report.yml", + ".github/ISSUE_TEMPLATE/feature_request.yml", + ".github/pull_request_template.md", +]) { + assert.ok(fs.existsSync(publicPath), `missing public-release file: ${publicPath}`); +} assert.equal(fs.readlinkSync("CLAUDE.md"), "AGENTS.md"); assert.ok(marketplace.plugins.some((plugin) => plugin.name === "claude-code-advisor")); assert.equal(packageJson.scripts["test:e2e:codex"], "node tests/e2e-codex-skill.mjs");