# CLAUDE.md Project guidelines for AI agents working in this codebase. ## What This Is A proxy that bridges OpenCode (Anthropic API format) to Claude Max (Agent SDK). See `ARCHITECTURE.md` for the full module map and dependency rules. ## Commands ```bash npm test # Run all tests (bun test) npm run build # Build with tsup npm start # Start the proxy server ``` ## Code Rules ### Module Boundaries - **Do not add code to `server.ts` that belongs in a leaf module.** If it's pure logic (no HTTP, no Hono), extract it. - **`session/lineage.ts` must stay pure.** No side effects, no I/O, no imports from cache or server. - **Leaf modules (`errors.ts`, `models.ts`, `tools.ts`, `messages.ts`) must not import from `server.ts` or `session/`.** Dependencies flow downward only. - **No circular dependencies.** ### Agent-Specific Logic OpenCode-specific behavior is documented in `ARCHITECTURE.md` under "Agent-Specific Logic". When modifying these areas: - Add a `NOTE:` comment marking the code as agent-specific - Do not spread agent-specific logic into new modules - Future work will use an adapter pattern — see `DEFERRED.md` ### Testing - Every extracted module must have unit tests - Pure functions get direct unit tests (no mocks) - Integration tests go through the HTTP layer with mocked SDK - **All tests must pass before any change is considered complete** - New test files go in `src/__tests__/` - **E2E tests** are documented in [`E2E.md`](./E2E.md) — run manually before releases or after major refactors (requires Claude Max subscription) ### Style - No `as any`, `@ts-ignore`, or `@ts-expect-error` - No empty catch blocks - Match existing patterns — check neighboring code before writing - Keep `server.ts` as thin as possible — it should orchestrate, not compute ## Architecture Quick Reference ``` server.ts → HTTP routes, SSE streaming, concurrency (orchestration only) adapter.ts → AgentAdapter interface (extensibility point) adapters/ opencode.ts → OpenCode-specific: headers, CWD, tool config forgecode.ts → ForgeCode-specific: XML CWD, patch/shell tools, passthrough query.ts → buildQueryOptions (shared stream/non-stream SDK call builder) errors.ts → classifyError (pure) models.ts → mapModelToClaudeModel, resolveClaudeExecutableAsync tools.ts → BLOCKED_BUILTIN_TOOLS, CLAUDE_CODE_ONLY_TOOLS, MCP_SERVER_NAME messages.ts → normalizeContent, getLastUserMessage (pure) fileChanges.ts → PostToolUse hook: file write/edit tracking + summary formatting (pure) session/ lineage.ts → Hashing, lineage verification (PURE — no I/O) fingerprint.ts → extractClientCwd, getConversationFingerprint cache.ts → LRU caches, lookupSession, storeSession (stateful) ``` ## Stable API Contract External plugins depend on these interfaces. **Do not change without project owner approval.** | Interface | Location | Used by | |-----------|----------|---------| | `startProxyServer(config)` → `ProxyInstance` | `server.ts` | Plugins that spawn proxy instances | | `ProxyInstance.close()` | `types.ts` | Plugins for graceful shutdown | | `ProxyConfig` type | `types.ts` | Plugin configuration | | `x-opencode-session` header | `adapters/opencode.ts` | Session tracking from agent plugins | | `x-meridian-profile` header | `server.ts`, `profiles.ts` | Per-request profile selection | | `GET /health` response shape | `server.ts` | Plugin health checks | | `POST /v1/messages` request/response format | `server.ts` | All agents (Anthropic API contract) | | `GET /profiles/list` response shape | `server.ts` | Profile management UI and CLI | | `POST /profiles/active` request/response | `server.ts` | Profile switching from CLI and UI | If you need to modify any of these, open an issue first — breaking changes affect downstream plugin authors. ## Git & Workflow ### Commit format - Format: `type: brief description` - Types: feat, fix, refactor, perf, test, docs, chore - No AI attribution lines ### Development workflow — NEVER push directly to main All changes go through this process, no exceptions: 1. **Create a feature branch** from `main`: ```bash git checkout -b feat/my-feature main ``` 2. **Make changes, commit, push the branch:** ```bash git add -A && git commit -m "feat: my feature" git push origin feat/my-feature ``` 3. **Create a PR** targeting `main`: ```bash gh pr create --title "feat: my feature" --base main ``` 4. **Wait for CI** — the `test` job must pass before merging: ```bash gh pr checks <PR_NUMBER> ``` 5. **Merge the PR** (squash merge preferred): ```bash gh pr merge <PR_NUMBER> --squash --delete-branch ``` 6. **Never** run `git push origin main` directly — all code reaches `main` through merged PRs only. ## Releasing **Do NOT run `npm version`, `git push --tags`, or `npm publish` manually.** Releases are handled automatically by [Release Please](https://github.com/googleapis/release-please): 1. Merge PRs to `main` using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, etc.) 2. Release Please auto-creates/updates a release PR that batches all unreleased changes 3. Review the release PR — the changelog should only show changes since the last release 4. When ready to ship, merge the release PR: ```bash gh pr merge <RELEASE_PR_NUMBER> --merge ``` 5. Merging the release PR automatically: - Bumps `package.json` and `CHANGELOG.md` - Creates a git tag (`meridian-v*`) and GitHub Release - Runs tests, builds, and publishes to npm with provenance Multiple PRs get batched into a single release. Never publish manually. ### Troubleshooting releases - **Changelog shows entire history?** — Release Please can't find the previous release tag. Check that `meridian-v<version>` tags exist for recent releases: `git tag -l 'meridian-v*' | tail -5` - **Release PR not updating?** — It only updates on `push` to `main`. If you closed it, push any commit to main to regenerate. - **Publish failed with E403?** — The version was already published. This is safe to ignore; the release is already on npm. - **`publish_only` workflow dispatch** — Emergency escape hatch to publish the current version without Release Please. Only use when the normal flow is broken. ### Release config files - **`.release-please-manifest.json`** — tracks the current released version. Release Please updates this automatically when a release PR is merged. **Do not edit manually** unless resetting the version anchor. - **`release-please-config.json`** — defines the release type (`node`), component name, and changelog section mapping. - **`.github/workflows/release-please.yml`** — the workflow that runs on every push to `main`. It creates/updates the release PR and publishes to npm when merged.