Prepare v0.2.0 release

Add local install/update and wiki publishing scripts, public release docs, known limitations, a demo asset, and tighter Claude-facing tool guidance.

Bump plugin/package metadata to 0.2.0 and keep the installed-plugin real session test version-aware.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: xuio

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-subagents",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Launch OpenAI Codex agents, Spark agents, and parallel Codex subagents from Claude Code through a daemonless MCP server with read-only defaults and explicit full-access mode.",
   "author": {
     "name": "xuio"

CHANGELOG.md

@@ -1,10 +1,13 @@
 # Changelog
 
-## Unreleased
+## 0.2.0
 
 - Refreshed the README into a shorter onboarding page.
 - Added usage, architecture, development, and troubleshooting docs.
 - Added GitHub issue templates and a pull request template.
+- Added a local install/update script and wiki publishing script.
+- Documented known limitations and release notes.
+- Tightened Claude tool-selection guidance for sessions, steering, aggregation, and async jobs.
 
 ## 0.1.1
 

README.md

@@ -10,6 +10,8 @@ Run OpenAI Codex agents from Claude Code through a daemonless MCP plugin.
 parallel investigations, Spark checks, persistent multi-turn sessions, and explicit
 full-access Codex work when the user asks for it.
 
+![Terminal demo of Claude launching parallel Codex reviewers](docs/assets/demo.svg)
+
 ## Why Use It?
 
 - **Native Claude Code workflow:** Claude gets MCP tools and a plugin skill, so it can decide when to ask Codex without shell glue.
@@ -31,8 +33,7 @@ Requirements:
 ```sh
 git clone https://github.com/xuio/claude-code-codex-subagents.git
 cd claude-code-codex-subagents
-npm install
-npm run build
+npm run install:local
 claude --plugin-dir .
 ```
 
@@ -115,6 +116,8 @@ use DNS/network, install packages, or behave like a normal unrestricted Codex ru
 - [Architecture](docs/ARCHITECTURE.md) - process model, app-server sessions, durability, logging.
 - [Development](docs/DEVELOPMENT.md) - setup, local Claude linking, test tiers, release checklist.
 - [Troubleshooting](docs/TROUBLESHOOTING.md) - diagnostics, logs, common failure modes.
+- [Known limitations](docs/KNOWN_LIMITATIONS.md) - sharp edges and operational constraints.
+- [Release notes](docs/RELEASE.md) - current release highlights and validation.
 - [Security policy](SECURITY.md) - default sandboxing, logs, reporting.
 - [Contributing](CONTRIBUTING.md) - contribution expectations and local checks.
 
@@ -142,6 +145,13 @@ npm run test:ci
 npm run validate:plugin
 ```
 
+For local install/update:
+
+```sh
+npm run install:local
+npm run update:local
+```
+
 `test:ci` is portable and uses the fake Codex binary. It does not require live
 Claude or Codex credentials.
 
@@ -159,6 +169,8 @@ See [Development](docs/DEVELOPMENT.md) for the full test matrix.
 
 ## Project Status
 
+Current release: `v0.2.0`.
+
 This project is early, but it is already tested across:
 
 - stdio MCP protocol flows

dist/index.js

@@ -25546,8 +25546,8 @@ var usageGuide = [
   "- Prefer ask_codex_parallel when the work can be split into independent concurrent tasks, for example separate reviewers for API flow, tests, security, performance, UI, docs, or migration risk.",
   "- Prefer start_codex_session and continue_codex_session when the user wants a Codex agent to keep context across multiple prompts. Persistent sessions use Codex app-server by default and fall back to codex exec only when app-server is unavailable.",
   "- Prefer start_codex_session_async when Claude needs a session id immediately while Codex keeps working in the background.",
-  "- Use send_codex_session_prompt to add prompts to an active or idle Codex session queue without losing context.",
-  "- Use steer_codex_session to send real live steering into a running app-server turn; use interrupt_current only when the active turn should be cancelled and redirected. If a session had to fall back to codex exec, steering degrades to the next high-priority queued turn.",
+  "- Use send_codex_session_prompt for ordinary follow-ups on an active or idle Codex session. This preserves context and queues behind the active turn when needed.",
+  "- Use steer_codex_session only when the user wants to redirect the active work now. It sends real live steering into a running app-server turn; use interrupt_current only when the active turn should be cancelled and redirected. If a session had to fall back to codex exec, steering degrades to the next high-priority queued turn.",
   "- Use get_codex_session or wait_codex_session to inspect or wait for long-running Codex sessions. Session snapshots include appServer.supports and appServerFallbackReason for protocol diagnostics.",
   "- Use recover_codex_session when Claude has a persisted session_id from before a Claude/MCP restart and wants to reattach to that Codex thread before sending a follow-up.",
   "- Use codex_export_debug_bundle after repeated failures; it writes recent diagnostics, selected session/job state, status, and optional log tail into one local JSON bundle.",
@@ -25558,6 +25558,7 @@ var usageGuide = [
   "- Use codex_doctor for installation, binary, auth, and default-setting diagnostics.",
   "- Use codex_status only for diagnostics or when you need to confirm the Codex binary/version.",
   "- Use codex_usage_guide if you are unsure how to structure a Codex delegation.",
+  "- Use codex_choose_tool before delegating when the request is ambiguous between one agent, parallel agents, aggregation, a persistent session, an async job, or live steering.",
   "",
   "Default operating rules:",
   "- Keep sandbox read-only unless the user explicitly asks for a different sandbox.",
@@ -25572,6 +25573,8 @@ var usageGuide = [
   "- Do not set service_tier by default. Let Codex use its normal account/default service tier unless the user explicitly asks for a service tier.",
   "- Pass project_dir whenever Claude knows the active project directory so Codex works in the same tree as Claude Code.",
   "- Persistent sessions are durable across MCP restarts when Codex has produced a thread id. After restart, list_sessions can show recovered sessions and recover_codex_session can validate the thread.",
+  "- Async one-shot jobs from start_agent_run/start_agents_run are not durable across MCP restarts. Use persistent session tools for recoverable long-running work.",
+  "- Raw debug logs are intentionally verbose and may contain MCP traffic and prompt text. Treat logs and debug bundles as sensitive local data.",
   "- Do not use Bash, Read, or filesystem inspection to locate Codex. The MCP server resolves Codex automatically, preferring the Codex desktop app binary when installed.",
   "- Set isolated_codex_home true when a run should ignore the user's Codex MCP server config and use only this request's temporary Codex configuration.",
   '- Use mcp_config_policy "explicit" with codex_mcp_servers for intentional MCP sharing. Use "inherit_claude_project" only when the project has a Claude MCP config that should be shared with Codex.',
@@ -26090,8 +26093,8 @@ server.registerTool(
         "Use start_codex_session for a new multi-turn Codex worker and continue_codex_session for follow-ups.",
         "Use recover_codex_session after an MCP restart when Claude has a previous persisted session id.",
         "Use start_codex_session_async when Claude needs the session id immediately and will poll or wait later.",
-        "Use send_codex_session_prompt to queue additional prompts onto an active or idle Codex session.",
-        "Use steer_codex_session to send live app-server steering into a running session; interrupt_current cancels the active turn before running the steering turn.",
+        "Use send_codex_session_prompt for ordinary follow-up prompts on an active or idle Codex session.",
+        "Use steer_codex_session only for active redirection. Live steering requires app-server support; exec fallback queues a high-priority turn.",
         "Use start_agent_run/start_agents_run for slow jobs that should not hold a blocking MCP request open.",
         "Use run_agents_aggregate only when Claude needs a deterministic consensus object.",
         "Pass project_dir whenever Claude knows the active project directory.",

docs/DEVELOPMENT.md

@@ -10,6 +10,16 @@ npm run build
 The Claude plugin manifest points at `dist/index.js`, so rebuild after changing
 TypeScript source.
 
+For the normal local install/update path:
+
+```sh
+npm run install:local
+npm run update:local
+```
+
+`install:local` builds, validates plugin wiring, and symlinks Claude's local
+plugin cache to this working tree. `update:local` first runs `git pull --ff-only`.
+
 ## Local Claude Plugin Link
 
 For active development, link Claude's installed plugin cache back to this working
@@ -88,16 +98,34 @@ scenario in every round.
 3. Run `npm run test:ci`.
 4. Run relevant real-runtime or live tests for the touched area.
 5. Run `npm run check:dist`.
-6. Check for local artifacts and secrets before committing.
-7. Push and verify GitHub Actions on Node 20 and Node 22.
+6. For release candidates, run `npm run test:real-soak`.
+7. Check for local artifacts and secrets before committing.
+8. Push and verify GitHub Actions on Node 20 and Node 22.
+9. Create the GitHub release from `docs/RELEASE.md`.
+
+## Wiki Publishing
+
+Tracked wiki source lives in `docs/wiki/`.
+
+```sh
+npm run wiki:publish
+```
+
+If GitHub returns `Repository not found` for the `.wiki.git` remote, create the
+first wiki page once in the GitHub web UI, then rerun `npm run wiki:publish`.
+GitHub does not expose an initialized wiki git remote until that first page
+exists.
 
 ## Useful Scripts
 
 | Script | Purpose |
 | --- | --- |
 | `npm run build` | Type-check and bundle `dist/index.js` |
 | `npm run check:dist` | Rebuild and verify committed dist has no diff |
+| `npm run install:local` | Build, validate, and symlink the local Claude plugin install |
+| `npm run update:local` | Pull latest main, then run the local install flow |
 | `npm run dev:link` | Symlink Claude's plugin cache to this repo |
 | `npm run dev:watch` | Rebuild dist on TypeScript changes |
+| `npm run wiki:publish` | Publish `docs/wiki/*.md` to the GitHub wiki repo |
 | `npm run diagnostics` | Write a sanitized local diagnostics bundle |
 | `npm run validate:plugin` | Run Claude's plugin manifest validator |

docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,72 @@
+# Known Limitations
+
+This project is designed to be conservative by default, but several behaviors are
+intentionally sharp because the goal is deep Claude/Codex debugging and local
+power-user workflows.
+
+## Raw Debug Logging Is Sensitive
+
+The default debug profile logs raw MCP traffic, tool arguments/results, prompt
+text, progress events, and Codex stdin/stdout/stderr traffic. Treat these logs and
+debug bundles as sensitive project data.
+
+Use quieter logging for normal work:
+
+```sh
+export CODEX_SUBAGENTS_LOG_PROFILE=production
+```
+
+Disable logging entirely:
+
+```sh
+export CODEX_SUBAGENTS_LOG_LEVEL=silent
+```
+
+## Async Jobs Are Not Durable
+
+`start_agent_run` and `start_agents_run` are process-local async jobs. They keep
+Claude responsive during long one-shot work, but they do not survive MCP process
+restart.
+
+Use `start_codex_session_async` for long-running work that should be recoverable
+after Claude Code or the MCP server restarts.
+
+## Real Steering Requires App-Server
+
+`steer_codex_session` delivers live steering only when the session is running
+through Codex app-server and reports `supportsRealSteering: true`.
+
+If app-server is unavailable and the session falls back to `codex exec`, steering
+degrades to a high-priority queued follow-up turn. It cannot alter an already
+running `codex exec` process in place.
+
+## Full-Access Mode Is Deliberately Dangerous
+
+The default sandbox is read-only. Full local access requires this per-call flag:
+
+```json
+{
+  "dangerously_bypass_approvals_and_sandbox": true
+}
+```
+
+That maps to Codex's unrestricted local mode. It can write files, mutate git
+state, use DNS/network, and run package installs. Use it only when the user
+explicitly asks for that capability.
+
+## Nested Subagents Can Increase Cost And Latency
+
+Nested Codex subagents are supported, including Spark. Keep nested work scoped,
+set explicit `subagent_tasks`, and keep `subagent_runtime.max_depth` at `1` unless
+recursive delegation is deliberately needed.
+
+## Claude Tool Choice Still Benefits From Clear Prompts
+
+The plugin has a skill, tool descriptions, and `codex_choose_tool`, but Claude can
+still make better choices when the user names the intended shape:
+
+- "ask one Codex agent"
+- "run three Codex agents in parallel"
+- "start a long-running Codex session"
+- "steer the running Codex session"
+

docs/RELEASE.md

@@ -0,0 +1,47 @@
+# Release Notes
+
+## v0.2.0
+
+`v0.2.0` is the first public-ready release candidate for
+`claude-code-codex-subagents`.
+
+Highlights:
+
+- Daemonless Claude Code MCP plugin for launching OpenAI Codex agents.
+- Read-only Codex delegation by default.
+- Codex desktop app binary preferred automatically when installed.
+- Front-door tools for one agent, parallel agents, aggregation, persistent
+  sessions, async sessions, live steering, recovery, and diagnostics.
+- Codex Spark preset support.
+- Nested Codex subagent definitions and task requests.
+- App-server persistent sessions with recoverable metadata and live steering.
+- Backpressure, progress notifications, response compaction, output artifacts,
+  diagnostics bundles, and verbose logging.
+- Local install/update script for development and user installs.
+- GitHub-friendly README, docs, issue templates, PR template, and wiki source.
+
+Recommended install/update:
+
+```sh
+git clone https://github.com/xuio/claude-code-codex-subagents.git
+cd claude-code-codex-subagents
+npm run install:local
+```
+
+Recommended verification:
+
+```sh
+npm run test:ci
+npm run check:dist
+npm run test:codex-runtime
+npm run test:real-matrix
+```
+
+Live Claude/Codex validation remains opt-in because it spends tokens:
+
+```sh
+npm run test:claude-orchestration
+npm run test:claude-real-codex
+npm run test:claude-real-session
+```
+

docs/TROUBLESHOOTING.md

@@ -39,7 +39,7 @@ claude --plugin-dir .
 For installed-plugin development, run:
 
 ```sh
-npm run dev:link
+npm run install:local
 npm run dev:watch
 ```
 
@@ -149,3 +149,21 @@ npm run test:claude-real-session
 ```
 
 These spend live Claude and/or Codex tokens.
+
+## Release Or Update Looks Stale
+
+Run the local update flow:
+
+```sh
+npm run update:local
+```
+
+Then restart Claude Code. If Claude still loads an old version, run:
+
+```sh
+npm run dev:link
+npm run validate:plugin
+```
+
+`dev:link` prints the marketplace and installed cache symlinks that Claude Code
+and Claude Desktop share.

docs/USAGE.md

@@ -57,6 +57,24 @@ Diagnostics tools:
 - `codex_doctor`
 - `codex_export_debug_bundle`
 
+## Choosing The Right Tool
+
+Use this decision path when writing prompts or debugging Claude tool choice:
+
+| User intent | Best tool |
+| --- | --- |
+| One normal read-only second opinion | `ask_codex` |
+| Two or more independent workstreams | `ask_codex_parallel` |
+| Several agents plus a merged summary | `run_agents_aggregate` |
+| Same Codex agent should keep context | `start_codex_session`, then `continue_codex_session` |
+| Long first turn, user wants to keep working | `start_codex_session_async` |
+| Add a normal follow-up to a running session | `send_codex_session_prompt` |
+| Redirect the active app-server turn | `steer_codex_session` |
+| Recover a session after Claude/MCP restart | `recover_codex_session` |
+| Slow one-shot job that need not be durable | `start_agent_run` |
+
+When in doubt, ask Claude to call `codex_choose_tool` before delegating.
+
 ## Example: One Agent
 
 Ask Claude:
@@ -188,6 +206,16 @@ This maps to Codex's `--dangerously-bypass-approvals-and-sandbox` flag and allow
 DNS/network access, file writes, package installs, and git writes. Keep it scoped
 to the specific tool call that needs it.
 
+## Sharp Edges
+
+See [Known limitations](KNOWN_LIMITATIONS.md) for the current operational sharp
+edges. The most important ones:
+
+- raw debug logs are sensitive
+- async one-shot jobs are not durable across MCP restarts
+- real steering requires app-server support
+- full-access mode is intentionally dangerous
+
 ## Structured Output
 
 Use `output_contract` when Claude needs machine-readable results: