Guidance for AI agents (and humans) working on or reviewing this repository.
opencodex (ocx) is a universal provider proxy for OpenAI Codex and Claude Code:
one local proxy that lets Codex CLI/App/SDK and Claude Code use many LLM
providers (Claude, Gemini, Grok, DeepSeek, Ollama, and more). The runtime is
Bun-native TypeScript with no separate server compile step.
src/— proxy runtime: routing, provider adapters, config, management API.tests/— flat Bun tests (tests/*.test.ts); shared fixtures intests/helpers/, broader scenarios intests/e2e-style/.gui/— React + Vite dashboard; packaged output is served fromgui/dist.docs-site/— public docs (Astro + Starlight), deployed to GitHub Pages.structure/— maintainer invariants and architecture notes; read before changing shared subsystems.scripts/— release and maintenance tooling;scripts/release.tsis the release authority.devlog/— planning and investigation artifacts (mostly gitignored).
bun install
bun run typecheck # bun x tsc --noEmit (strict)
bun run test # full tests/ suite
bun run lint:gui # GUI eslint
bun run privacy:scan # credential/privacy scan used by CI
bun run build:gui # Vite GUI buildRun bun run typecheck and bun run test before proposing or approving any
non-trivial change. CI runs these on Linux, Windows, and macOS.
dev— integration branch. All normal pull requests targetdev.main— release branch. It only moves by maintainer-controlled promotion fromdev(releases, docs deploys). Do not open feature PRs againstmain.preview— prerelease train (x.y.z-preview.*versions).claudedesktop— ongoing in-development branch. Parts of it have already been merged intodev(e.g. 418d29b1); the remaining commits are integrated only by maintainer action. Its divergence frommain/devis expected and is not a bug. Do not merge or rebase it in a PR without maintainer direction.
MAINTAINERS.md is authoritative for review and merge
policy (approvals, CI requirements, security review, promotion). This file
summarizes; it never overrides it.
These rules apply to all code reviews on this repository, including automated reviewers (Codex, CodeRabbit).
- Language: always review in English, regardless of the PR or issue language. Be detailed and specific: name the file and line, describe the concrete failure mode, and suggest a fix. Avoid vague or purely stylistic commentary.
- Branch targeting: flag any pull request that targets
maininstead ofdev(releases and maintainer promotions are the only exceptions). - Security boundary (highest priority): changes touching authentication,
credential/token handling, OAuth flows, GitHub Actions workflows, release
automation (
scripts/release.ts,.github/workflows/release.yml), or dependency installation require explicit security review perMAINTAINERS.md. Treat token logging/serialization, secret exposure, workflow permission escalation, and mutable third-party action refs as release blockers. - Runtime constraints: the proxy is Bun-native. Flag Node-only APIs,
assumptions about a compile step, or code paths that break
bun run typecheck/bun run test. - Tests: behavior changes in
src/need a focused regression test near the existing tests for that subsystem. Shared routing, adapter, config, or server changes need the full suite green. - Docs sync: user-facing behavior changes should update
docs-site/(and keep translated locales from contradicting the English source). - Privacy:
bun run privacy:scanmust stay green; never introduce logging of request bodies, API keys, or account identifiers.
Issues live in GitHub Issues on the fork genglintong/opencodex (uses gh CLI with --repo genglintong/opencodex). See docs/agents/issue-tracker.md.
Default five-label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See docs/agents/triage-labels.md.
Single-context layout: root CONTEXT.md + docs/adr/. See docs/agents/domain.md.