fix(claude): embed SDK cli.js via /embed entry point for compiled binaries

[Wirasm]

Summary

Fixes a P0 bug in v0.3.1 where every compiled binary fails to spawn Claude with Module not found "/Users/runner/work/Archon/Archon/node_modules/.bun/@anthropic-ai+claude-agent-sdk@0.2.89+.../cli.js".

Root cause

The Claude Agent SDK, when pathToClaudeCodeExecutable is not set, falls back to:

const dir = path.dirname(fileURLToPath(import.meta.url));
pathToClaudeCodeExecutable = path.join(dir, "cli.js");

In a bun build --compile binary, import.meta.url of a bundled module is frozen at build time to the absolute path where that module lived on the build host. In CI that's /Users/runner/work/Archon/Archon/node_modules/.bun/... — a path that only exists on the GitHub Actions runner. Every shipped binary carried the CI path, and every workflow run hit spawn ENOENT on the three-retry loop before failing.

Fix

The SDK ships a dedicated @anthropic-ai/claude-agent-sdk/embed entry point built for exactly this case. It uses import cli.js with { type: 'file' } so Bun's bundler embeds cli.js into the compiled binary's $bunfs virtual filesystem, then extractFromBunfs() copies it to a real temp path at runtime (child processes cannot read the parent's $bunfs). We import that entry point and pass the result as pathToClaudeCodeExecutable.

Safe in dev (bun link) too — the embed module resolves to the real on-disk cli.js.

Verification

Built a local binary via scripts/build-binaries.sh on this branch and ran:

./dist/test-archon-darwin-arm64 workflow run assist --no-worktree "say hello and nothing else"

Result: Claude subprocess spawned successfully, returned "Hello", workflow completed in 3.9s. Same test against v0.3.1 fails with Module not found after three retries.

Why this escaped every prior release

• Dev (bun link) never exercises this path — normal node resolution finds cli.js.
• Local binary builds bake your own laptop's node_modules path, which exists locally, so the binary "works" for the person who built it.
• v0.3.0's homebrew formula had stale SHAs so no one ever installed v0.3.0 via brew successfully.
• v0.3.1 is the first release where /test-release brew could actually run — and it surfaced this instantly.

Related

• Codex SDK has a related but distinct issue (createRequire(import.meta.url).resolve('@openai/codex/package.json') plus unembeddable native platform binaries). That's out of scope for this fix — filing separately.
• A CI smoke test that runs workflow run assist against the built binary inside the release workflow would have caught this. Worth adding as a follow-up.

Test plan

• bun run type-check clean
• Local binary built via scripts/build-binaries.sh spawns Claude and completes assist workflow
• After merge: cut v0.3.2, run /test-release brew 0.3.2 end-to-end before announcing

Summary by CodeRabbit

• Chores
  • Updated Claude SDK configuration to improve subprocess handling reliability.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 986ee06a-8378-49c9-98b5-e303e558b0a3

📥 Commits

Reviewing files that changed from the base of the PR and between 85bfe4c and d008311.

📒 Files selected for processing (1)

• packages/core/src/clients/claude.ts

---

📝 Walkthrough

Walkthrough

The change imports the embedded Claude Agent SDK CLI binary path and passes it to the Claude SDK initialization. This configures the SDK to use the extracted embedded cli.js executable rather than relying on module-relative path resolution.

Changes

Cohort / File(s)	Summary
Claude SDK Configuration packages/core/src/clients/claude.ts	Imports @anthropic-ai/claude-agent-sdk/embed and passes the embedded CLI path to Claude SDK options via pathToClaudeCodeExecutable parameter to override default executable resolution.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A bunny hops through code so bright,
CLI paths now set just right!
No more searching far and wide,
The embedded agent's here to guide! 🌟

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: embedding the SDK cli.js via the /embed entry point to fix compiled binary subprocess spawning.
Description check	✅ Passed	The description is comprehensive and addresses most template sections with detailed root cause analysis, fix explanation, and verification steps, though some template sections like UX Journey, Architecture Diagram, and formal metadata labels are not included.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/claude-sdk-embed-cli-path

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Wirasm]

PR Review Summary

Critical Issues (0)

None.

Important Issues (0)

None.

Suggestions (1)

Agent	Suggestion	Location
docs-impact	Missing CHANGELOG entry under [Unreleased] ### Fixed for the P0 compiled-binary spawn fix (destined for v0.3.2)	CHANGELOG.md

Strengths

• code-reviewer: Type-safe (embed.d.ts exports declare const cliPath: string; matches Options.pathToClaudeCodeExecutable). Correct placement in Options. No guideline violations. Verdict: PASS.
• comment-analyzer: All 6 factual claims in the 8-line block verified against actual SDK source (embed.js uses import ... with { type: 'file' }; extractFromBunfs() matches $bunfs and copies to tmpdir()/claude-agent-sdk-{hash}/cli.js; dev early-returns when path lacks $bunfs). Strong "why over what" comment. One cosmetic nit: the SDK fallback pattern appears in two sites (query() and ClaudeSession.initialize), not just "its own module" — not misleading, just slightly understated.

Verdict

READY TO MERGE — add CHANGELOG entry before cutting v0.3.2.

Recommended Actions

1. Add CHANGELOG [Unreleased] ### Fixed entry referencing fix(claude): embed SDK cli.js via /embed entry point for compiled binaries #990
2. Merge and cut v0.3.2
3. Run /test-release brew 0.3.2 end-to-end as noted in PR test plan