feat(codex): ship native basecamp plugin by yigitkonur · Pull Request #534 · basecamp/basecamp-cli

yigitkonur · 2026-07-15T06:58:04Z

what changed

add a native Codex plugin manifest, Basecamp and doctor skills, and reviewed lifecycle hooks
add basecamp setup codex, Codex doctor checks, version parity, release stamping, and repository validation
document one-command and manual Codex setup while leaving the Claude plugin path unchanged

why

this gets codex users the same one-command setup without messing with the claude path.

test plan

go test ./internal/harness ./internal/commands -run "Codex|CodexHook" -timeout 60s
go test ./internal/release -run "Codex|Plugin"
focused golangci-lint, repository Codex checker, and official plugin validator
isolated Codex marketplace install: installed/enabled 0.7.2, both skills discovered in a fresh thread, both hooks listed in /hooks, hook fixtures exercised, and Codex doctor checks passed
bin/ci completed plugin, Go, and Actions lint stages; its full macOS run retains the existing internal/cliTestHardenConfigDir failures reproduced unchanged on main

Summary by cubic

Ships a native Codex plugin with one-command setup, agent-aware diagnostics, and stable-release stamping. Hardens setup remediation and manifest checks; drops the unproven hook stack.

New Features
- Native Codex plugin bundle: .codex-plugin/plugin.json with skills and icons.
- Setup: basecamp setup codex registers basecamp/claude-plugins, refreshes 37signals if already added, installs the plugin, streams Codex output with per-step timeouts, and returns manual commands in JSON; the wizard never aborts.
- Doctor: adds an agent Diagnostics hook; surfaces “Codex Plugin” and “Codex Plugin Version” from a single Codex query with breadcrumbs; basecamp doctor --json includes Codex diagnostics.
- Release/CI: stamps both .claude-plugin/plugin.json and .codex-plugin/plugin.json for stable releases via scripts/stamp-codex-plugin-version.sh; Go tests enforce strict semver and version parity, validate manifest paths, and verify hooks.json only calls basecamp if present.
Refactors
- Removed post-commit hook, Bash AST parsing, hidden Codex hook commands, and the Python checker; bin/ci is make check again.
- Harness: added AgentInfo.Diagnostics; Claude’s version check moved into diagnostics; doctor now calls agent diagnostics generically.
- Setup/validation hardening: clear remediation when Codex isn’t installed (suggests only basecamp setup codex), split stdout/stderr so JSON parsing is robust, and resolve symlinks in manifest path checks.

^{Written for commit 369e77b. Summary will update on new commits.}

github-actions · 2026-07-15T06:58:13Z

Sensitive Change Detection (shadow mode)

This PR modifies control-plane files:

.goreleaser.yaml

Shadow mode — this check is informational only. When activated, changes to these paths will require approval from a maintainer.

Copilot

Pull request overview

This PR adds first-class support for a native Codex plugin alongside the existing Claude Code integration, including plugin payload validation, lifecycle hooks, setup automation, and doctor diagnostics so Codex users can get a one-command setup path.

Changes:

Introduces a native Codex plugin manifest, hook payload, and a repository validator (scripts/check-codex-plugin.py) enforced by bin/ci.
Adds basecamp setup codex plus Codex-related doctor checks (plugin installed/enabled + version parity) and release stamping for .codex-plugin/plugin.json.
Documents Codex setup (automatic + manual) while keeping the Claude Code path intact.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
skills/basecamp-doctor/SKILL.md	Adds a dedicated “doctor” skill describing how to run and interpret `basecamp doctor --json` safely.
scripts/stamp-codex-plugin-version.sh	Adds a release helper to stamp the CLI version into the Codex plugin manifest.
scripts/release.sh	Stamps + stages the Codex plugin manifest during stable releases and updates messaging.
scripts/check-codex-plugin.py	Adds a repository contract/shape validator for the Codex plugin payload (manifest, hooks, wiring, version parity).
RELEASING.md	Documents that stable releases update both Claude and Codex plugin metadata.
README.md	Documents `basecamp setup codex`, manual install commands, and `basecamp doctor --json` coverage.
internal/release/codex_plugin_test.go	Adds tests for stamping, repository validation, and release wiring/version parity.
internal/harness/codex.go	Adds Codex detection and doctor checks (plugin presence + version parity) to the agent harness.
internal/harness/codex_test.go	Adds unit tests covering Codex detection and the new doctor checks.
internal/commands/wizard_codex.go	Implements `basecamp setup codex` to register marketplace, install plugin, and verify state.
internal/commands/wizard_codex_test.go	Tests Codex setup command behavior (ordering, idempotency, failures, JSON output).
internal/commands/doctor.go	Adds doctor breadcrumbs for Codex plugin failures/warnings to point users at `basecamp setup codex`.
internal/commands/doctor_test.go	Tests Codex doctor integration wiring and breadcrumb behavior.
internal/commands/codex_hook.go	Adds hidden `basecamp codex-hook …` commands used by Codex lifecycle hooks.
internal/commands/codex_hook_test.go	Tests session-start context output and post-commit reference detection behavior.
internal/cli/root.go	Registers the hidden Codex hook command group in the CLI root.
install.md	Adds Codex setup docs (one-command + manual) and recommends `basecamp doctor --json` verification.
hooks/hooks.json	Adds Codex-native lifecycle hook definitions for SessionStart and PostToolUse(Bash).
bin/ci	Enforces Codex plugin payload validation via `scripts/check-codex-plugin.py`.
AGENTS.md	Updates repository structure docs to include `.codex-plugin/` and `hooks/`.
.goreleaser.yaml	Stamps both Claude + Codex plugin versions for stable releases via GoReleaser hooks.
.codex-plugin/plugin.json	Adds the native Codex plugin manifest (name/version/interface/skills/assets).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cubic-dev-ai

All reported issues were addressed across 22 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

yigitkonur · 2026-07-15T07:24:22Z

coordinated codex marketplace follow-up

The companion marketplace payload is ready at yigitkonur/claude-plugins@5607030 on branch feat/codex-marketplace.

GitHub currently denies contributor-created pull requests to basecamp/claude-plugins with CreatePullRequest permission errors, including from a separately authenticated fork owner. Basecamp crew will need to open the marketplace PR from that branch or cherry-pick 5607030 after this CLI payload merges. The CLI payload must merge first because the catalog entry tracks basecamp/basecamp-cli on main.

Copilot

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated no new comments.

cubic-dev-ai

All reported issues were addressed across 11 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

Copilot

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 1 comment.

cubic-dev-ai

All reported issues were addressed across 4 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

Copilot

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated no new comments.

The post-commit hook could never fire on Codex: it gated on structured exit_code/success/status fields in tool_response, but Codex sends Bash tool_response as a plain JSON string of shell output. Remove the hook command, its bash-AST parsing (and the mvdan.cc/sh dependency), and hooks/hooks.json rather than ship dormant code; hooks return in a follow-up PR built on a design proven against both agents' payloads. Replace scripts/check-codex-plugin.py and its meta-tests with pure Go manifest tests: parse both plugin manifests, enforce strict semver and version parity, verify referenced paths exist, and check hooks.json hook commands (tolerant of absence) — all under make test, with no python dependency and no __pycache__ pollution. bin/ci is make check again. Claude-Session: https://claude.ai/code/session_01QzoKavmhTPzErRna2KkTKS

Add AgentInfo.Diagnostics — the full doctor check suite, run with the caller's context — alongside Checks, which stays cheap and version-free to gate setup wizard behavior. Codex registers its single-query plugin+version diagnostics; Claude registers its plugin, skill-link, and relocated plugin-version checks. Doctor now iterates agents generically (Diagnostics when present, Checks otherwise) instead of special-casing agent IDs. Also replace error-string sniffing in codexQueryFailure with a typed parse sentinel. Claude-Session: https://claude.ai/code/session_01QzoKavmhTPzErRna2KkTKS

Setup now prints per-step progress lines, streams codex stderr to the terminal while capturing stdout for --json parsing, and bounds each subprocess with its own timeout (20s marketplace/install, 5s verify) instead of one 30s umbrella. Failures return a typed agentSetupError carrying a summary plus manual remediation commands. Non-interactive setup surfaces them as errors[], a new manual_commands field, and per-command breadcrumbs in the OK envelope (partial success: ok:true, plugin_installed:false, exit 0 — matching the Claude path; doctor stays the health gate). The umbrella wizard warns and continues — Codex setup never aborts basecamp setup. Consolidate the codex handler into the agentSetupHandlers literal, drop the unused Confirm field, and record the setup codex surface additions. Claude-Session: https://claude.ai/code/session_01QzoKavmhTPzErRna2KkTKS

Hooks are not shipping in this PR, so remove /hooks-trust instructions and hooks wording from README, install.md, and the AGENTS.md tree, and drop the connect-commits claim from the Codex manifest. Document the basecamp CLI as a prerequisite of both agent plugins, show manual Codex install as plain commands, and point at codex plugin marketplace upgrade 37signals as the refresh step. The basecamp-doctor skill ships to both agents via the shared skills directory, so reword it agent-neutrally and wire it into check-skill-drift. Claude-Session: https://claude.ai/code/session_01QzoKavmhTPzErRna2KkTKS

…e-codex-plugin * origin/main: Bump SDK to d15f023f and collapse todos update onto TodosService.Edit (basecamp#543) Fix agent-help hidden-flag leak; make check-surface a real drift gate (basecamp#542) Fix todos update silently clearing completion subscribers (basecamp#540) Fix TestHardenConfigDir on macOS: resolve TMPDIR symlinks in test dirs (basecamp#536) Bump golang.org/x/net to v0.56.0 for CVE-2026-46600 (basecamp#537)

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

jeremy · 2026-07-20T15:10:08Z

Love this @yigitkonur! I'll pull it in. Think we can unify hooks across plugins as well in a follow-on.

When no Codex executable exists, the manual remediation commands were all codex subcommands — impossible to run by definition. The missing-binary branch now says to install Codex and re-run setup, and emits only basecamp setup codex as the manual command, so the machine-readable remediation contract never suggests the impossible. Keep subprocess stdout and stderr separate end-to-end: structured alreadyAdded parsing sees clean stdout while text sniffing and failure messages still see both streams, so a future stderr warning cannot silently defeat JSON detection. Resolve symlinks before the manifest path containment check so a link pointing outside the repository cannot pass a lexical-only test. Claude-Session: https://claude.ai/code/session_01QzoKavmhTPzErRna2KkTKS

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

jeremy

Phase 1 rework verified at head 369e77b: fresh bin/ci green (302 e2e, surface, skill-drift ×2, provenance), zero unresolved threads, pinned-payload install through real Codex 0.144.x with all four doctor states correct.

The previously-dead marketplace path is fixed and verified live: basecamp/claude-plugins#7 switched the basecamp entry from the github source (silently skipped by Codex's parser) to the url source supported by both agents — codex plugin marketplace add now resolves 37signals and lists basecamp@37signals as available.

Production smoke (marketplace upgrade → setup codex → doctor → fresh thread) follows immediately post-merge.

One hooks/hooks.json at the plugin root serves both agents: SessionStart injects auth status as model context, and paired Bash PreToolUse/PostToolUse hooks nudge when a commit references Basecamp work. PostToolUseFailure closes the asymmetry where a commit followed by a failed push produced no nudge, since the commit is proven from repository state rather than the tool result. Restores the docs and setup guidance deferred in cb13972, and names the CLI floor: the hooks call agent-hook, so they need a basecamp new enough to have it, with basecamp upgrade as the remediation. Held until a CLI release carrying agent-hook shipped. Stable v0.8.0 is now published and Latest, and the shipped darwin binary exposes exactly the three subcommands hooks.json invokes; the snapshot-commit-nudge flow was exercised end to end against it. TestHooksFileCommandsInvokeBasecamp, dormant since #534, activates with this.

yigitkonur added 5 commits July 14, 2026 23:25

feat(codex): add native plugin bundle
f70665b

feat(codex): add setup and diagnostics
e9fb3f4

chore(codex): validate plugin releases
a9e19b5

docs(codex): document plugin setup
2c28178

fix(codex): harden plugin checks
c634319

CopilotAI review requested due to automatic review settings July 15, 2026 06:58

github-actionsBot added commands CLI command implementations tests Tests (unit and e2e) skills Agent skills docs enhancement New feature or request labels Jul 15, 2026

Copilotstarted reviewing on behalf of yigitkonur July 15, 2026 06:58 View session

CopilotAI reviewed Jul 15, 2026
View reviewed changes

Comment threadscripts/check-codex-plugin.py Outdated

cubic-dev-aiBot reviewed Jul 15, 2026
View reviewed changes

yigitkonur added 3 commits July 15, 2026 00:19

fix(codex): harden hook follow-ups
16eef7c

fix(codex): refresh existing marketplace
96138d1

fix(codex): harden release validation
7539eb0

CopilotAI review requested due to automatic review settings July 15, 2026 07:23

Copilotstarted reviewing on behalf of yigitkonur July 15, 2026 07:24 View session

CopilotAI reviewed Jul 15, 2026
View reviewed changes

Comment threadinternal/harness/codex_test.go
Comment threadscripts/check-codex-plugin.py Outdated

test(codex): isolate missing binary home
fc34b34

CopilotAI review requested due to automatic review settings July 15, 2026 07:38

Copilotstarted reviewing on behalf of yigitkonur July 15, 2026 07:39 View session

CopilotAI reviewed Jul 15, 2026
View reviewed changes

cubic-dev-aiBot reviewed Jul 15, 2026
View reviewed changes

Comment threadinternal/commands/codex_hook.go Outdated
Comment threadinternal/commands/codex_hook.go Outdated

fix(codex): parse shell commit commands
3c572af

CopilotAI review requested due to automatic review settings July 15, 2026 07:50

Copilotstarted reviewing on behalf of yigitkonur July 15, 2026 07:51 View session

CopilotAI review requested due to automatic review settings July 15, 2026 08:40

Copilotstarted reviewing on behalf of yigitkonur July 15, 2026 08:40 View session

CopilotAI reviewed Jul 15, 2026
View reviewed changes

Comment threadinternal/harness/codex.go Outdated

cubic-dev-aiBot reviewed Jul 15, 2026
View reviewed changes

Comment threadinternal/harness/codex_test.go
Comment threadinternal/commands/doctor.go Outdated
Comment threadinternal/commands/doctor.go Outdated

fix(codex): harden doctor diagnostics
63c5feb

CopilotAI review requested due to automatic review settings July 15, 2026 08:49

Copilotstarted reviewing on behalf of yigitkonur July 15, 2026 08:49 View session

CopilotAI reviewed Jul 15, 2026
View reviewed changes

jeremy added 5 commits July 20, 2026 02:01

CopilotAI review requested due to automatic review settings July 20, 2026 09:39

github-actionsBot removed the deps label Jul 20, 2026

Copilotstarted reviewing on behalf of jeremy July 20, 2026 09:40 View session

CopilotAI reviewed Jul 20, 2026
View reviewed changes

Comment threadinternal/commands/wizard_codex.go Outdated

CopilotAI review requested due to automatic review settings July 20, 2026 15:17

CopilotAI reviewed Jul 20, 2026
View reviewed changes

Comment threadscripts/stamp-codex-plugin-version.sh

Copilotstarted reviewing on behalf of jeremy July 20, 2026 15:24 View session

jeremy mentioned this pull request Jul 20, 2026
Use Codex-compatible url source for basecamp plugin basecamp/claude-plugins#7
Merged

jeremy approved these changes Jul 20, 2026
View reviewed changes

github-advanced-securityBot found potential problems Jul 20, 2026
View reviewed changes

Comment threadinternal/commands/wizard_codex.go Dismissed
Comment threadinternal/harness/codex.go Dismissed

jeremy merged commit 11eaf2c into basecamp:mainJul 20, 2026
26 checks passed

jeremy added this to the v0.8.0 milestone Jul 20, 2026

This was referenced Jul 21, 2026
Drop dead .claude-plugin component payload #548
Merged
Ship shared plugin hooks #550
Merged

Uh oh!

Conversation

yigitkonur commented Jul 15, 2026• edited by cubic-dev-ai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

what changed

why

test plan

Summary by cubic

Uh oh!

github-actionsBot commented Jul 15, 2026

Sensitive Change Detection (shadow mode)

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

cubic-dev-aiBot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yigitkonur commented Jul 15, 2026

coordinated codex marketplace follow-up

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

cubic-dev-aiBot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

cubic-dev-aiBot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

jeremy commented Jul 20, 2026

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

jeremy left a comment

yigitkonur commented Jul 15, 2026•
edited by cubic-dev-ai Bot
Loading

cubic-dev-aiBot left a comment •
edited
Loading

cubic-dev-aiBot left a comment •
edited
Loading

cubic-dev-aiBot left a comment •
edited
Loading