{"owner":"lidge-jun","repo":"opencodex","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI agents (and humans) working on or reviewing this repository.\n\n## What this project is\n\nopencodex (`ocx`) is a universal provider proxy for OpenAI Codex and Claude Code:\none local proxy that lets Codex CLI/App/SDK and Claude Code use many LLM\nproviders (Claude, Gemini, Grok, DeepSeek, Ollama, and more). The runtime is\nBun-native TypeScript with no separate server compile step.\n\n## Repository layout\n\n- `src/` — proxy runtime: routing, provider adapters, config, management API.\n- `tests/` — flat Bun tests (`tests/*.test.ts`); shared fixtures in\n  `tests/helpers/`, broader scenarios in `tests/e2e-style/`.\n- `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.\n- `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.\n- `go/` — retired Go native-runtime experiment; kept only where the TypeScript\n  runtime still references it. New work does not go here.\n- `structure/` — maintainer invariants and architecture notes; read before\n  changing shared subsystems.\n- `scripts/` — release and maintenance tooling; `scripts/release.ts` is the\n  release authority.\n- `devlog/` — planning and investigation notes, tracked in this repository. See\n  \"The `devlog` directory\" below for what may and may not go there.\n\nRead the nearest nested `AGENTS.md` before changing files in a scoped\ndirectory (`src/`, `gui/`, `docs-site/`, `scripts/`, `.github/`).\n\n## Optional subsystems stay off the core path\n\n`src/lab/` (Compatibility Lab) is opt-in. A user who configures one provider and\none model — no routing profile, no Lab — must execute no Lab code and start no\nLab timer.\n\nThree files carry every such user's request path and must not reach `src/lab/`,\ndirectly or transitively:\n\n- `src/router.ts`\n- `src/server/lifecycle.ts`\n- `src/server/responses/core.ts`\n\n`tests/core-lab-boundary.test.ts` enforces this by walking the runtime import\ngraph and printing the offending chain on failure. It is not a style rule: the\noriginal violation hid in a six-hop chain\n(`assemble → quota → auth-api → native-main-admission → lifecycle → lab`) where\nno single file looked wrong, and it pulled ~69 Lab modules into every install.\n\nAn optional subsystem registers into a core-owned slot at activation instead of\nbeing imported. The existing seams are `src/server/passive-route-linker.ts`,\n`src/routing/compatibility/provider-slot.ts`, and\n`src/lib/optional-shutdown-hooks.ts`.\n\n`src/server/index.ts` is deliberately exempt: a composition root is supposed to\nknow which optional subsystems exist. Its obligation is the gate, not the import\n— activation must stay behind `labActivationRequired`, and it must stay\nsynchronous. Everything between `Bun.serve` and the return of `startServer` runs\nin one synchronous turn, which is what guarantees a policy route can never be\nevaluated before its evidence provider is registered. The synchronous\nsubagent-fallback chain has nowhere to await, so an `await` added before the\nactivation block would silently reroute subagents to a different model than the\noperator configured.\n\nDesign and audit history: `devlog/_plan/260814_lab_core_decoupling/`.\n\n## The `devlog` directory\n\nPlanning notes, triage matrices, and investigation artifacts live in `devlog/`,\ntracked like any other documentation. There is no submodule and no private\nmirror. It was a private submodule until the pointer churn outgrew its value:\n1723 commits touched the gitlink, and `dev`, `preview`, and `main` each carried a\ndifferent pointer, so every branch move and promotion dragged a diff.\n\n- `devlog/_plan/` — units still open, one directory per unit, decade-numbered\n  docs.\n- `devlog/_fin/` — closed units, moved here once a terminal outcome is recorded.\n  A `_fin` unit is a record of work already visible in public git history.\n- `devlog/_chase/` — external reference material for parity comparisons.\n  Reference *clones* are gitignored: they are third-party source carrying their\n  own licenses and have no business in this repository's history.\n\nNothing in the build, typecheck, or test path reads from `devlog/`, so a\ncontributor who ignores it entirely still passes every gate. `privacy:scan` does\nread it — that is deliberate, and it is what makes a public devlog safe rather\nthan merely visible.\n\nTwo mechanical guards in `tests/repo-hygiene.test.ts` back this up: no `160000`\ngitlink may be tracked anywhere, and neither the vendored reference clones nor\nthe security triage excised before publication may reappear in the index. Both\nwere driven red once to prove they are not vacuous. The gitlink assertion exists\nbecause a gitlink in a tree CI does not initialize breaks `actions/checkout` for\nevery contributor, which happened twice.\n\n## Security working notes\n\n**Security work is done in scratch space, never in a tracked directory.** That\nincludes unreleased findings, severity assessments, draft advisories, exploit\nor bypass reasoning, reproduction steps for an unfixed defect, and\npre-disclosure patch plans.\n\nUse `.tmp/` in the working tree (already gitignored) or a `mktemp -d` path.\n`devlog/` is **not** an acceptable location — it is a public directory in a\npublic repository, so anything committed there is disclosed the moment it is\npushed, and the history is not practical to purge afterwards. A private\nrepository is not acceptable either: it gets cloned across machines and CI and\noutlives the embargo.\n\n**This binds maintainers exactly as it binds contributors and agents.** The rule\nhas been violated by maintainer-authored triage before: two units of open\nsecurity review accumulated under `devlog/_plan/` and had to be excised before\nthis directory could be published. Seniority is not an exemption, and \"it is\nonly in the private half\" is no longer a thing that exists.\n\nThe test to apply before writing a security note into `devlog/`: **is there\nalready a public diff that reveals this weakness?** If the fix has shipped, the\nwriteup discloses nothing new and belongs in `_fin/`. If it has not, the note is\npre-disclosure material and goes to scratch. That distinction is why closed\nhardening records stay in the tree while open triage does not.\n\nOnly the published outcome reaches a repository — the fix itself, its\nregression test, the release note, the advisory once it is public. Draft the\nadvisory in scratch space and delete the scratch directory once the advisory is\nlive.\n\nThis applies to `AGENTS.md`-following agents as much as to humans. If a task\nasks you to write up a security finding, put the write-up in scratch space and\nsay where it is; do not add it to `devlog/`, `structure/`, or `docs-site/`.\n\n## User-consent actions\n\nSome actions write to the **user's own accounts and identity** rather than to\nthis repository, and an agent must never perform or auto-answer them. The one\nthat exists today is starring the repository on GitHub, which only comes up when\nan agent is *running* opencodex — not when it is working on this codebase.\n\nThe rule lives in [`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md), which is the file\nan installing or operating agent reads. It was moved out of here because a\ndevelopment-facing file is the wrong place to trigger on it: this file is loaded\nfor every code change, and the consent boundary applies to none of them.\n\nWhat matters for development work: the enforcement is code, not prose —\n[`src/cli/agent-driven.ts`](./src/cli/agent-driven.ts),\n[`src/cli/star-prompt.ts`](./src/cli/star-prompt.ts), and\n[`src/server/management/sidebar-routes.ts`](./src/server/management/sidebar-routes.ts),\ncovered by `tests/startup-prompt.test.ts`, `tests/agent-driven.test.ts`, and\n`tests/sidebar-routes.test.ts`. If you add another action that spends the user's\nidentity, credits, or reputation, gate it the same way rather than relying on a\nprompt an agent can answer, and document it in `AGENTS_INSTALL.md`.\n\n**Be clear about what that enforcement is and is not.** The management endpoint\nrequires a dashboard session, which stops the casual path — an agent that would\nhave POSTed there because the endpoint existed, and one holding only the admin\ntoken. It is not a technical barrier against a determined local agent: a process\nrunning as the user can mint its own session from the loopback dashboard\nbootstrap, and can skip the proxy entirely by running `gh` itself. Every local\ncredential is equally reachable by both the browser and the agent, so no check\ninside this process can tell them apart. The real boundary is the rule above, and\nit binds you regardless of which mechanism is within reach.\n\n## Commands\n\n```bash\nbun install\nbun run typecheck      # bun x tsc --noEmit (strict)\nbun run test           # full tests/ suite\nbun run lint:gui       # GUI eslint\nbun run privacy:scan   # credential/privacy scan used by CI\nbun run build:gui      # Vite GUI build\n```\n\nDuring implementation, use the smallest focused checks that directly cover the\nchanged subsystem. Do not run repository-wide `bun run typecheck` or\n`bun run test` for a scoped change unless the change affects shared runtime,\nrouting, config, server behavior, a focused result is failed or ambiguous, or\nthe user explicitly asks for full validation.\n\nBefore creating or updating a non-trivial PR as review-ready, or before\napproving such a PR, run `bun run typecheck` and `bun run test`. CI runs these\non Linux, Windows, and macOS.\n\nDo not rerun passing checks on unchanged code merely for additional confidence.\n\n## Issues and pull requests (agents)\n\nAgent-created issues and PRs must use the repository templates. The gates\nbelow enforce them, so a freeform or mismatched submission is rejected rather\nthan nudged.\n\n- **Creating an issue:** open it through the template chooser and use the\n  matching form in `.github/ISSUE_TEMPLATE/` — `bug_report.yml` (Bug report),\n  `feature_request.yml` (Feature proposal), `documentation.yml`\n  (Documentation), or `provider_compatibility.yml` (Provider or API\n  compatibility). Keep the form's section headings exactly as generated;\n  `enforce-issue-quality` validates the headings and closes untemplated or\n  mislabeled issues (`.github/ISSUE_TEMPLATE/config.yml` disables blank\n  issues, so there is no freeform fallback).\n- **Opening a pull request:** fill every section of\n  `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Verification, Checklist).\n  `enforce-target` rejects empty, thin, or malformed descriptions, and a PR\n  whose title or description mentions `gui` must include a screenshot of the\n  UI change in the description. When the PR resolves an issue, add\n  `Closes #<number>` to link it. GitHub auto-closes the linked issue only\n  when the PR merges into the default branch (`main`); PRs here target\n  `dev`, so close the issue manually once the change is on `dev`.\n\n## Branch policy\n\n- `dev` — the single integration branch and the target for every pull request.\n- `main` — release branch. It only moves by maintainer-controlled promotion\n  from `dev` (releases, docs deploys). Do not open feature PRs against `main`.\n- `preview` — prerelease train (`x.y.z-preview.*` versions).\n\nBun-native TypeScript on `dev` is the only runtime line. If native code\nreturns, the expectation is an incremental module (for example Rust via N-API)\nlanding on `dev`, not a second full-runtime branch.\n\nStacked child pull requests that target another **open** PR's head branch are\nan intentional review workflow, not an alternate integration line. The\n**`enforce-target`** check skips the wrong-base gate for those children; after\nthe parent lands or closes, retarget the child to `dev`.\n\nRebase pull requests are welcome. Bringing a stale branch onto the current head\nis ordinary maintenance — open it as a normal pull request and name the source\ncommits in the description.\n\nThe **`enforce-target`** CI check rejects pull requests whose head\nancestry sits on the **`main`** tip while far behind **`dev`**, and rejects\nempty, thin, or malformed descriptions; PRs whose title or description\nmentions `gui` must include a screenshot of the UI change in the description.\nContributor PRs (authors without repository push permission) open in draft and\nstay there until a four-box review-readiness checklist in the description is\ncomplete: local CI green, branch on the latest `dev` commit, all correct Codex\nand CodeRabbit findings fixed, and the ready-for-review confirmation. When all\nfour boxes are ticked the gate marks the PR ready and notifies the maintainers\nlisted in `MAINTAINERS.md` (excluding the author). Completion is bound to the\nexact commit the PR head pointed at: if new commits are pushed afterwards, the\ngate moves the PR back to draft, resets the checklist and the notification,\nand asks the author to test and tick the boxes again against the latest code.\nBefore a completion is accepted, the gate verifies the checklist claims it\ncan check itself: the branch must be on the latest `dev` commit or at most\n10 commits behind it, and Codex/CodeRabbit findings must be resolved. The\nlocal-CI box is an author attestation only — fork contributors cannot start\nrepository CI; a maintainer has to — so the gate never disproves it; a new\npush still resets every box. A disproved claim unticks the matching box and\nkeeps the PR a draft.\nAuthors with repository push permission skip the ancestry heuristic only. As with approval requirements in\n[`MAINTAINERS.md`](./MAINTAINERS.md), this is enforced by convention until\nbranch protection is configured.\n\n[`MAINTAINERS.md`](./MAINTAINERS.md) is authoritative for review and merge\npolicy (approvals, CI requirements, security review, promotion). This file\nsummarizes; it never overrides it.\n\n## Review guidelines\n\nThese rules apply to all code reviews on this repository, including automated\nreviewers (Codex, CodeRabbit).\n\n- **Language:** always review in English, regardless of the PR or issue\n  language. Be detailed and specific: name the file and line, describe the\n  concrete failure mode, and suggest a fix. Avoid vague or purely stylistic\n  commentary.\n- **Branch targeting:** flag any pull request that does not target `dev`\n  (releases and maintainer promotions are the only exceptions).\n- **Security boundary (highest priority):** changes touching authentication,\n  credential/token handling, OAuth flows, GitHub Actions workflows, release\n  automation (`scripts/release.ts`, `.github/workflows/release.yml`), or\n  dependency installation require explicit security review per\n  `MAINTAINERS.md`. Treat token logging/serialization, secret exposure,\n  workflow permission escalation, and mutable third-party action refs as\n  release blockers.\n- **Runtime constraints:** the proxy is Bun-native. Flag Node-only APIs,\n  assumptions about a compile step, or code paths that break `bun run\n  typecheck` / `bun run test`.\n- **Tests:** behavior changes in `src/` need a focused regression test near\n  the existing tests for that subsystem. Shared routing, adapter, config, or\n  server changes need the full suite green.\n- **Docs sync:** user-facing behavior changes should update `docs-site/` (and\n  keep translated locales from contradicting the English source).\n- **Privacy:** `bun run privacy:scan` must stay green; never introduce logging\n  of request bodies, API keys, or account identifiers.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI agents (and humans) working on or reviewing this repository.\n\n## What this project is\n\nopencodex (`ocx`) is a universal provider proxy for OpenAI Codex and Claude Code:\none local proxy that lets Codex CLI/App/SDK and Claude Code use many LLM\nproviders (Claude, Gemini, Grok, DeepSeek, Ollama, and more). The runtime is\nBun-native TypeScript with no separate server compile step.\n\n## Repository layout\n\n- `src/` — proxy runtime: routing, provider adapters, config, management API.\n- `tests/` — flat Bun tests (`tests/*.test.ts`); shared fixtures in\n  `tests/helpers/`, broader scenarios in `tests/e2e-style/`.\n- `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.\n- `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.\n- `go/` — retired Go native-runtime experiment; kept only where the TypeScript\n  runtime still references it. New work does not go here.\n- `structure/` — maintainer invariants and architecture notes; read before\n  changing shared subsystems.\n- `scripts/` — release and maintenance tooling; `scripts/release.ts` is the\n  release authority.\n- `devlog/` — planning and investigation notes, tracked in this repository. See\n  \"The `devlog` directory\" below for what may and may not go there.\n\nRead the nearest nested `AGENTS.md` before changing files in a scoped\ndirectory (`src/`, `gui/`, `docs-site/`, `scripts/`, `.github/`).\n\n## Optional subsystems stay off the core path\n\n`src/lab/` (Compatibility Lab) is opt-in. A user who configures one provider and\none model — no routing profile, no Lab — must execute no Lab code and start no\nLab timer.\n\nThree files carry every such user's request path and must not reach `src/lab/`,\ndirectly or transitively:\n\n- `src/router.ts`\n- `src/server/lifecycle.ts`\n- `src/server/responses/core.ts`\n\n`tests/core-lab-boundary.test.ts` enforces this by walking the runtime import\ngraph and printing the offending chain on failure. It is not a style rule: the\noriginal violation hid in a six-hop chain\n(`assemble → quota → auth-api → native-main-admission → lifecycle → lab`) where\nno single file looked wrong, and it pulled ~69 Lab modules into every install.\n\nAn optional subsystem registers into a core-owned slot at activation instead of\nbeing imported. The existing seams are `src/server/passive-route-linker.ts`,\n`src/routing/compatibility/provider-slot.ts`, and\n`src/lib/optional-shutdown-hooks.ts`.\n\n`src/server/index.ts` is deliberately exempt: a composition root is supposed to\nknow which optional subsystems exist. Its obligation is the gate, not the import\n— activation must stay behind `labActivationRequired`, and it must stay\nsynchronous. Everything between `Bun.serve` and the return of `startServer` runs\nin one synchronous turn, which is what guarantees a policy route can never be\nevaluated before its evidence provider is registered. The synchronous\nsubagent-fallback chain has nowhere to await, so an `await` added before the\nactivation block would silently reroute subagents to a different model than the\noperator configured.\n\nDesign and audit history: `devlog/_plan/260814_lab_core_decoupling/`.\n\n## The `devlog` directory\n\nPlanning notes, triage matrices, and investigation artifacts live in `devlog/`,\ntracked like any other documentation. There is no submodule and no private\nmirror. It was a private submodule until the pointer churn outgrew its value:\n1723 commits touched the gitlink, and `dev`, `preview`, and `main` each carried a\ndifferent pointer, so every branch move and promotion dragged a diff.\n\n- `devlog/_plan/` — units still open, one directory per unit, decade-numbered\n  docs.\n- `devlog/_fin/` — closed units, moved here once a terminal outcome is recorded.\n  A `_fin` unit is a record of work already visible in public git history.\n- `devlog/_chase/` — external reference material for parity comparisons.\n  Reference *clones* are gitignored: they are third-party source carrying their\n  own licenses and have no business in this repository's history.\n\nNothing in the build, typecheck, or test path reads from `devlog/`, so a\ncontributor who ignores it entirely still passes every gate. `privacy:scan` does\nread it — that is deliberate, and it is what makes a public devlog safe rather\nthan merely visible.\n\nTwo mechanical guards in `tests/repo-hygiene.test.ts` back this up: no `160000`\ngitlink may be tracked anywhere, and neither the vendored reference clones nor\nthe security triage excised before publication may reappear in the index. Both\nwere driven red once to prove they are not vacuous. The gitlink assertion exists\nbecause a gitlink in a tree CI does not initialize breaks `actions/checkout` for\nevery contributor, which happened twice.\n\n## Security working notes\n\n**Security work is done in scratch space, never in a tracked directory.** That\nincludes unreleased findings, severity assessments, draft advisories, exploit\nor bypass reasoning, reproduction steps for an unfixed defect, and\npre-disclosure patch plans.\n\nUse `.tmp/` in the working tree (already gitignored) or a `mktemp -d` path.\n`devlog/` is **not** an acceptable location — it is a public directory in a\npublic repository, so anything committed there is disclosed the moment it is\npushed, and the history is not practical to purge afterwards. A private\nrepository is not acceptable either: it gets cloned across machines and CI and\noutlives the embargo.\n\n**This binds maintainers exactly as it binds contributors and agents.** The rule\nhas been violated by maintainer-authored triage before: two units of open\nsecurity review accumulated under `devlog/_plan/` and had to be excised before\nthis directory could be published. Seniority is not an exemption, and \"it is\nonly in the private half\" is no longer a thing that exists.\n\nThe test to apply before writing a security note into `devlog/`: **is there\nalready a public diff that reveals this weakness?** If the fix has shipped, the\nwriteup discloses nothing new and belongs in `_fin/`. If it has not, the note is\npre-disclosure material and goes to scratch. That distinction is why closed\nhardening records stay in the tree while open triage does not.\n\nOnly the published outcome reaches a repository — the fix itself, its\nregression test, the release note, the advisory once it is public. Draft the\nadvisory in scratch space and delete the scratch directory once the advisory is\nlive.\n\nThis applies to `AGENTS.md`-following agents as much as to humans. If a task\nasks you to write up a security finding, put the write-up in scratch space and\nsay where it is; do not add it to `devlog/`, `structure/`, or `docs-site/`.\n\n## User-consent actions\n\nSome actions write to the **user's own accounts and identity** rather than to\nthis repository, and an agent must never perform or auto-answer them. The one\nthat exists today is starring the repository on GitHub, which only comes up when\nan agent is *running* opencodex — not when it is working on this codebase.\n\nThe rule lives in [`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md), which is the file\nan installing or operating agent reads. It was moved out of here because a\ndevelopment-facing file is the wrong place to trigger on it: this file is loaded\nfor every code change, and the consent boundary applies to none of them.\n\nWhat matters for development work: the enforcement is code, not prose —\n[`src/cli/agent-driven.ts`](./src/cli/agent-driven.ts),\n[`src/cli/star-prompt.ts`](./src/cli/star-prompt.ts), and\n[`src/server/management/sidebar-routes.ts`](./src/server/management/sidebar-routes.ts),\ncovered by `tests/startup-prompt.test.ts`, `tests/agent-driven.test.ts`, and\n`tests/sidebar-routes.test.ts`. If you add another action that spends the user's\nidentity, credits, or reputation, gate it the same way rather than relying on a\nprompt an agent can answer, and document it in `AGENTS_INSTALL.md`.\n\n**Be clear about what that enforcement is and is not.** The management endpoint\nrequires a dashboard session, which stops the casual path — an agent that would\nhave POSTed there because the endpoint existed, and one holding only the admin\ntoken. It is not a technical barrier against a determined local agent: a process\nrunning as the user can mint its own session from the loopback dashboard\nbootstrap, and can skip the proxy entirely by running `gh` itself. Every local\ncredential is equally reachable by both the browser and the agent, so no check\ninside this process can tell them apart. The real boundary is the rule above, and\nit binds you regardless of which mechanism is within reach.\n\n## Commands\n\n```bash\nbun install\nbun run typecheck      # bun x tsc --noEmit (strict)\nbun run test           # full tests/ suite\nbun run lint:gui       # GUI eslint\nbun run privacy:scan   # credential/privacy scan used by CI\nbun run build:gui      # Vite GUI build\n```\n\nDuring implementation, use the smallest focused checks that directly cover the\nchanged subsystem. Do not run repository-wide `bun run typecheck` or\n`bun run test` for a scoped change unless the change affects shared runtime,\nrouting, config, server behavior, a focused result is failed or ambiguous, or\nthe user explicitly asks for full validation.\n\nBefore creating or updating a non-trivial PR as review-ready, or before\napproving such a PR, run `bun run typecheck` and `bun run test`. CI runs these\non Linux, Windows, and macOS.\n\nDo not rerun passing checks on unchanged code merely for additional confidence.\n\n## Issues and pull requests (agents)\n\nAgent-created issues and PRs must use the repository templates. The gates\nbelow enforce them, so a freeform or mismatched submission is rejected rather\nthan nudged.\n\n- **Creating an issue:** open it through the template chooser and use the\n  matching form in `.github/ISSUE_TEMPLATE/` — `bug_report.yml` (Bug report),\n  `feature_request.yml` (Feature proposal), `documentation.yml`\n  (Documentation), or `provider_compatibility.yml` (Provider or API\n  compatibility). Keep the form's section headings exactly as generated;\n  `enforce-issue-quality` validates the headings and closes untemplated or\n  mislabeled issues (`.github/ISSUE_TEMPLATE/config.yml` disables blank\n  issues, so there is no freeform fallback).\n- **Opening a pull request:** fill every section of\n  `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Verification, Checklist).\n  `enforce-target` rejects empty, thin, or malformed descriptions, and a PR\n  whose title or description mentions `gui` must include a screenshot of the\n  UI change in the description. When the PR resolves an issue, add\n  `Closes #<number>` to link it. GitHub auto-closes the linked issue only\n  when the PR merges into the default branch (`main`); PRs here target\n  `dev`, so close the issue manually once the change is on `dev`.\n\n## Branch policy\n\n- `dev` — the single integration branch and the target for every pull request.\n- `main` — release branch. It only moves by maintainer-controlled promotion\n  from `dev` (releases, docs deploys). Do not open feature PRs against `main`.\n- `preview` — prerelease train (`x.y.z-preview.*` versions).\n\nBun-native TypeScript on `dev` is the only runtime line. If native code\nreturns, the expectation is an incremental module (for example Rust via N-API)\nlanding on `dev`, not a second full-runtime branch.\n\nStacked child pull requests that target another **open** PR's head branch are\nan intentional review workflow, not an alternate integration line. The\n**`enforce-target`** check skips the wrong-base gate for those children; after\nthe parent lands or closes, retarget the child to `dev`.\n\nRebase pull requests are welcome. Bringing a stale branch onto the current head\nis ordinary maintenance — open it as a normal pull request and name the source\ncommits in the description.\n\nThe **`enforce-target`** CI check rejects pull requests whose head\nancestry sits on the **`main`** tip while far behind **`dev`**, and rejects\nempty, thin, or malformed descriptions; PRs whose title or description\nmentions `gui` must include a screenshot of the UI change in the description.\nContributor PRs (authors without repository push permission) open in draft and\nstay there until a four-box review-readiness checklist in the description is\ncomplete: local CI green, branch on the latest `dev` commit, all correct Codex\nand CodeRabbit findings fixed, and the ready-for-review confirmation. When all\nfour boxes are ticked the gate marks the PR ready and notifies the maintainers\nlisted in `MAINTAINERS.md` (excluding the author). Completion is bound to the\nexact commit the PR head pointed at: if new commits are pushed afterwards, the\ngate moves the PR back to draft, resets the checklist and the notification,\nand asks the author to test and tick the boxes again against the latest code.\nBefore a completion is accepted, the gate verifies the checklist claims it\ncan check itself: the branch must be on the latest `dev` commit or at most\n10 commits behind it, and Codex/CodeRabbit findings must be resolved. The\nlocal-CI box is an author attestation only — fork contributors cannot start\nrepository CI; a maintainer has to — so the gate never disproves it; a new\npush still resets every box. A disproved claim unticks the matching box and\nkeeps the PR a draft.\nAuthors with repository push permission skip the ancestry heuristic only. As with approval requirements in\n[`MAINTAINERS.md`](./MAINTAINERS.md), this is enforced by convention until\nbranch protection is configured.\n\n[`MAINTAINERS.md`](./MAINTAINERS.md) is authoritative for review and merge\npolicy (approvals, CI requirements, security review, promotion). This file\nsummarizes; it never overrides it.\n\n## Review guidelines\n\nThese rules apply to all code reviews on this repository, including automated\nreviewers (Codex, CodeRabbit).\n\n- **Language:** always review in English, regardless of the PR or issue\n  language. Be detailed and specific: name the file and line, describe the\n  concrete failure mode, and suggest a fix. Avoid vague or purely stylistic\n  commentary.\n- **Branch targeting:** flag any pull request that does not target `dev`\n  (releases and maintainer promotions are the only exceptions).\n- **Security boundary (highest priority):** changes touching authentication,\n  credential/token handling, OAuth flows, GitHub Actions workflows, release\n  automation (`scripts/release.ts`, `.github/workflows/release.yml`), or\n  dependency installation require explicit security review per\n  `MAINTAINERS.md`. Treat token logging/serialization, secret exposure,\n  workflow permission escalation, and mutable third-party action refs as\n  release blockers.\n- **Runtime constraints:** the proxy is Bun-native. Flag Node-only APIs,\n  assumptions about a compile step, or code paths that break `bun run\n  typecheck` / `bun run test`.\n- **Tests:** behavior changes in `src/` need a focused regression test near\n  the existing tests for that subsystem. Shared routing, adapter, config, or\n  server changes need the full suite green.\n- **Docs sync:** user-facing behavior changes should update `docs-site/` (and\n  keep translated locales from contradicting the English source).\n- **Privacy:** `bun run privacy:scan` must stay green; never introduce logging\n  of request bodies, API keys, or account identifiers.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for AI agents (and humans) working on or reviewing this repository.\n\n## What this project is\n\nopencodex (`ocx`) is a universal provider proxy for OpenAI Codex and Claude Code:\none local proxy that lets Codex CLI/App/SDK and Claude Code use many LLM\nproviders (Claude, Gemini, Grok, DeepSeek, Ollama, and more). The runtime is\nBun-native TypeScript with no separate server compile step.\n\n## Repository layout\n\n- `src/` — proxy runtime: routing, provider adapters, config, management API.\n- `tests/` — flat Bun tests (`tests/*.test.ts`); shared fixtures in\n  `tests/helpers/`, broader scenarios in `tests/e2e-style/`.\n- `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.\n- `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.\n- `go/` — retired Go native-runtime experiment; kept only where the TypeScript\n  runtime still references it. New work does not go here.\n- `structure/` — maintainer invariants and architecture notes; read before\n  changing shared subsystems.\n- `scripts/` — release and maintenance tooling; `scripts/release.ts` is the\n  release authority.\n- `devlog/` — planning and investigation notes, tracked in this repository. See\n  \"The `devlog` directory\" below for what may and may not go there.\n\nRead the nearest nested `AGENTS.md` before changing files in a scoped\ndirectory (`src/`, `gui/`, `docs-site/`, `scripts/`, `.github/`).\n\n## Optional subsystems stay off the core path\n\n`src/lab/` (Compatibility Lab) is opt-in. A user who configures one provider and\none model — no routing profile, no Lab — must execute no Lab code and start no\nLab timer.\n\nThree files carry every such user's request path and must not reach `src/lab/`,\ndirectly or transitively:\n\n- `src/router.ts`\n- `src/server/lifecycle.ts`\n- `src/server/responses/core.ts`\n\n`tests/core-lab-boundary.test.ts` enforces this by walking the runtime import\ngraph and printing the offending chain on failure. It is not a style rule: the\noriginal violation hid in a six-hop chain\n(`assemble → quota → auth-api → native-main-admission → lifecycle → lab`) where\nno single file looked wrong, and it pulled ~69 Lab modules into every install.\n\nAn optional subsystem registers into a core-owned slot at activation instead of\nbeing imported. The existing seams are `src/server/passive-route-linker.ts`,\n`src/routing/compatibility/provider-slot.ts`, and\n`src/lib/optional-shutdown-hooks.ts`.\n\n`src/server/index.ts` is deliberately exempt: a composition root is supposed to\nknow which optional subsystems exist. Its obligation is the gate, not the import\n— activation must stay behind `labActivationRequired`, and it must stay\nsynchronous. Everything between `Bun.serve` and the return of `startServer` runs\nin one synchronous turn, which is what guarantees a policy route can never be\nevaluated before its evidence provider is registered. The synchronous\nsubagent-fallback chain has nowhere to await, so an `await` added before the\nactivation block would silently reroute subagents to a different model than the\noperator configured.\n\nDesign and audit history: `devlog/_plan/260814_lab_core_decoupling/`.\n\n## The `devlog` directory\n\nPlanning notes, triage matrices, and investigation artifacts live in `devlog/`,\ntracked like any other documentation. There is no submodule and no private\nmirror. It was a private submodule until the pointer churn outgrew its value:\n1723 commits touched the gitlink, and `dev`, `preview`, and `main` each carried a\ndifferent pointer, so every branch move and promotion dragged a diff.\n\n- `devlog/_plan/` — units still open, one directory per unit, decade-numbered\n  docs.\n- `devlog/_fin/` — closed units, moved here once a terminal outcome is recorded.\n  A `_fin` unit is a record of work already visible in public git history.\n- `devlog/_chase/` — external reference material for parity comparisons.\n  Reference *clones* are gitignored: they are third-party source carrying their\n  own licenses and have no business in this repository's history.\n\nNothing in the build, typecheck, or test path reads from `devlog/`, so a\ncontributor who ignores it entirely still passes every gate. `privacy:scan` does\nread it — that is deliberate, and it is what makes a public devlog safe rather\nthan merely visible.\n\nTwo mechanical guards in `tests/repo-hygiene.test.ts` back this up: no `160000`\ngitlink may be tracked anywhere, and neither the vendored reference clones nor\nthe security triage excised before publication may reappear in the index. Both\nwere driven red once to prove they are not vacuous. The gitlink assertion exists\nbecause a gitlink in a tree CI does not initialize breaks `actions/checkout` for\nevery contributor, which happened twice.\n\n## Security working notes\n\n**Security work is done in scratch space, never in a tracked directory.** That\nincludes unreleased findings, severity assessments, draft advisories, exploit\nor bypass reasoning, reproduction steps for an unfixed defect, and\npre-disclosure patch plans.\n\nUse `.tmp/` in the working tree (already gitignored) or a `mktemp -d` path.\n`devlog/` is **not** an acceptable location — it is a public directory in a\npublic repository, so anything committed there is disclosed the moment it is\npushed, and the history is not practical to purge afterwards. A private\nrepository is not acceptable either: it gets cloned across machines and CI and\noutlives the embargo.\n\n**This binds maintainers exactly as it binds contributors and agents.** The rule\nhas been violated by maintainer-authored triage before: two units of open\nsecurity review accumulated under `devlog/_plan/` and had to be excised before\nthis directory could be published. Seniority is not an exemption, and \"it is\nonly in the private half\" is no longer a thing that exists.\n\nThe test to apply before writing a security note into `devlog/`: **is there\nalready a public diff that reveals this weakness?** If the fix has shipped, the\nwriteup discloses nothing new and belongs in `_fin/`. If it has not, the note is\npre-disclosure material and goes to scratch. That distinction is why closed\nhardening records stay in the tree while open triage does not.\n\nOnly the published outcome reaches a repository — the fix itself, its\nregression test, the release note, the advisory once it is public. Draft the\nadvisory in scratch space and delete the scratch directory once the advisory is\nlive.\n\nThis applies to `AGENTS.md`-following agents as much as to humans. If a task\nasks you to write up a security finding, put the write-up in scratch space and\nsay where it is; do not add it to `devlog/`, `structure/`, or `docs-site/`.\n\n## User-consent actions\n\nSome actions write to the **user's own accounts and identity** rather than to\nthis repository, and an agent must never perform or auto-answer them. The one\nthat exists today is starring the repository on GitHub, which only comes up when\nan agent is *running* opencodex — not when it is working on this codebase.\n\nThe rule lives in [`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md), which is the file\nan installing or operating agent reads. It was moved out of here because a\ndevelopment-facing file is the wrong place to trigger on it: this file is loaded\nfor every code change, and the consent boundary applies to none of them.\n\nWhat matters for development work: the enforcement is code, not prose —\n[`src/cli/agent-driven.ts`](./src/cli/agent-driven.ts),\n[`src/cli/star-prompt.ts`](./src/cli/star-prompt.ts), and\n[`src/server/management/sidebar-routes.ts`](./src/server/management/sidebar-routes.ts),\ncovered by `tests/startup-prompt.test.ts`, `tests/agent-driven.test.ts`, and\n`tests/sidebar-routes.test.ts`. If you add another action that spends the user's\nidentity, credits, or reputation, gate it the same way rather than relying on a\nprompt an agent can answer, and document it in `AGENTS_INSTALL.md`.\n\n**Be clear about what that enforcement is and is not.** The management endpoint\nrequires a dashboard session, which stops the casual path — an agent that would\nhave POSTed there because the endpoint existed, and one holding only the admin\ntoken. It is not a technical barrier against a determined local agent: a process\nrunning as the user can mint its own session from the loopback dashboard\nbootstrap, and can skip the proxy entirely by running `gh` itself. Every local\ncredential is equally reachable by both the browser and the agent, so no check\ninside this process can tell them apart. The real boundary is the rule above, and\nit binds you regardless of which mechanism is within reach.\n\n## Commands\n\n```bash\nbun install\nbun run typecheck      # bun x tsc --noEmit (strict)\nbun run test           # full tests/ suite\nbun run lint:gui       # GUI eslint\nbun run privacy:scan   # credential/privacy scan used by CI\nbun run build:gui      # Vite GUI build\n```\n\nDuring implementation, use the smallest focused checks that directly cover the\nchanged subsystem. Do not run repository-wide `bun run typecheck` or\n`bun run test` for a scoped change unless the change affects shared runtime,\nrouting, config, server behavior, a focused result is failed or ambiguous, or\nthe user explicitly asks for full validation.\n\nBefore creating or updating a non-trivial PR as review-ready, or before\napproving such a PR, run `bun run typecheck` and `bun run test`. CI runs these\non Linux, Windows, and macOS.\n\nDo not rerun passing checks on unchanged code merely for additional confidence.\n\n## Issues and pull requests (agents)\n\nAgent-created issues and PRs must use the repository templates. The gates\nbelow enforce them, so a freeform or mismatched submission is rejected rather\nthan nudged.\n\n- **Creating an issue:** open it through the template chooser and use the\n  matching form in `.github/ISSUE_TEMPLATE/` — `bug_report.yml` (Bug report),\n  `feature_request.yml` (Feature proposal), `documentation.yml`\n  (Documentation), or `provider_compatibility.yml` (Provider or API\n  compatibility). Keep the form's section headings exactly as generated;\n  `enforce-issue-quality` validates the headings and closes untemplated or\n  mislabeled issues (`.github/ISSUE_TEMPLATE/config.yml` disables blank\n  issues, so there is no freeform fallback).\n- **Opening a pull request:** fill every section of\n  `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Verification, Checklist).\n  `enforce-target` rejects empty, thin, or malformed descriptions, and a PR\n  whose title or description mentions `gui` must include a screenshot of the\n  UI change in the description. When the PR resolves an issue, add\n  `Closes #<number>` to link it. GitHub auto-closes the linked issue only\n  when the PR merges into the default branch (`main`); PRs here target\n  `dev`, so close the issue manually once the change is on `dev`.\n\n## Branch policy\n\n- `dev` — the single integration branch and the target for every pull request.\n- `main` — release branch. It only moves by maintainer-controlled promotion\n  from `dev` (releases, docs deploys). Do not open feature PRs against `main`.\n- `preview` — prerelease train (`x.y.z-preview.*` versions).\n\nBun-native TypeScript on `dev` is the only runtime line. If native code\nreturns, the expectation is an incremental module (for example Rust via N-API)\nlanding on `dev`, not a second full-runtime branch.\n\nStacked child pull requests that target another **open** PR's head branch are\nan intentional review workflow, not an alternate integration line. The\n**`enforce-target`** check skips the wrong-base gate for those children; after\nthe parent lands or closes, retarget the child to `dev`.\n\nRebase pull requests are welcome. Bringing a stale branch onto the current head\nis ordinary maintenance — open it as a normal pull request and name the source\ncommits in the description.\n\nThe **`enforce-target`** CI check rejects pull requests whose head\nancestry sits on the **`main`** tip while far behind **`dev`**, and rejects\nempty, thin, or malformed descriptions; PRs whose title or description\nmentions `gui` must include a screenshot of the UI change in the description.\nContributor PRs (authors without repository push permission) open in draft and\nstay there until a four-box review-readiness checklist in the description is\ncomplete: local CI green, branch on the latest `dev` commit, all correct Codex\nand CodeRabbit findings fixed, and the ready-for-review confirmation. When all\nfour boxes are ticked the gate marks the PR ready and notifies the maintainers\nlisted in `MAINTAINERS.md` (excluding the author). Completion is bound to the\nexact commit the PR head pointed at: if new commits are pushed afterwards, the\ngate moves the PR back to draft, resets the checklist and the notification,\nand asks the author to test and tick the boxes again against the latest code.\nBefore a completion is accepted, the gate verifies the checklist claims it\ncan check itself: the branch must be on the latest `dev` commit or at most\n10 commits behind it, and Codex/CodeRabbit findings must be resolved. The\nlocal-CI box is an author attestation only — fork contributors cannot start\nrepository CI; a maintainer has to — so the gate never disproves it; a new\npush still resets every box. A disproved claim unticks the matching box and\nkeeps the PR a draft.\nAuthors with repository push permission skip the ancestry heuristic only. As with approval requirements in\n[`MAINTAINERS.md`](./MAINTAINERS.md), this is enforced by convention until\nbranch protection is configured.\n\n[`MAINTAINERS.md`](./MAINTAINERS.md) is authoritative for review and merge\npolicy (approvals, CI requirements, security review, promotion). This file\nsummarizes; it never overrides it.\n\n## Review guidelines\n\nThese rules apply to all code reviews on this repository, including automated\nreviewers (Codex, CodeRabbit).\n\n- **Language:** always review in English, regardless of the PR or issue\n  language. Be detailed and specific: name the file and line, describe the\n  concrete failure mode, and suggest a fix. Avoid vague or purely stylistic\n  commentary.\n- **Branch targeting:** flag any pull request that does not target `dev`\n  (releases and maintainer promotions are the only exceptions).\n- **Security boundary (highest priority):** changes touching authentication,\n  credential/token handling, OAuth flows, GitHub Actions workflows, release\n  automation (`scripts/release.ts`, `.github/workflows/release.yml`), or\n  dependency installation require explicit security review per\n  `MAINTAINERS.md`. Treat token logging/serialization, secret exposure,\n  workflow permission escalation, and mutable third-party action refs as\n  release blockers.\n- **Runtime constraints:** the proxy is Bun-native. Flag Node-only APIs,\n  assumptions about a compile step, or code paths that break `bun run\n  typecheck` / `bun run test`.\n- **Tests:** behavior changes in `src/` need a focused regression test near\n  the existing tests for that subsystem. Shared routing, adapter, config, or\n  server changes need the full suite green.\n- **Docs sync:** user-facing behavior changes should update `docs-site/` (and\n  keep translated locales from contradicting the English source).\n- **Privacy:** `bun run privacy:scan` must stay green; never introduce logging\n  of request bodies, API keys, or account identifiers.\n","category":"root","tokens":3800}]}