AGENTS.md · lidge-jun/opencodex

Sections

1. What this project is
2. Repository layout
3. Optional subsystems stay off the core path
4. The devlog directory
5. Security working notes
6. User-consent actions
7. Commands
8. What a green pull request does not tell you
9. Minimal containers and agent sandboxes
10. Issues and pull requests (agents)
11. CI policy (maintainer decision — do not change)
12. Branch policy
13. Review guidelines

First lines (shown under the repo's MIT license)

# AGENTS.md

Guidance for AI agents (and humans) working on or reviewing this repository.

## What this project is

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.

## Repository layout

- `src/` — proxy runtime: routing, provider adapters, config, management API.
- `tests/` — Bun tests in domain directories that mirror `src/`
  (`tests/<domain>/*.test.ts`; `providers/` and `adapters/` have one more
  level for the larger vendors). The explicit map is
  `scripts/test-layout/layout.json` plus its `explicitShards` sibling maps, with regex seeds and migration state in
  `scripts/test-layout/seeds.json`; `tests/test-layout.test.ts` enforces that every file resolves to a
  domain and sits in it, and only the two layout guards live at the root.
  Shared helpers in `tests/helpers/`, fixtures in `tests/fixtures/`, broader
  scenarios in `tests/e2e-style/`. Source-oracle tests resolve the repository
  through `tests/helpers/repo-root.ts` (`repoRoot()`, `repoPath()`,
  `helperPath()`, `fixturePath()`), never `import.meta.dir + "/.."`. A new
  test file lands in its domain directory and needs an entry in both
  `layout.json` `explicit` (or its domain shard) and a `tests/fixtures/test-layout-expected*.json` shard
  (`tests/test-layout-tooling.test.ts` names the missing one); the regex
  seeds in `seeds.json` place a conventionally named file until then.
  History: `devlog/_fin/260905_test_modularization_and_windows/`.
- `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.
- `app/` — native macOS WidgetKit extension bundled into the Tauri desktop app;
  `MenuBarCore` is its snapshot model/formatting layer. Its tests are
  executables, not XCTest bundles — Command Line Tools ships neither a usable
  XCTest module nor the swift-testing runtime.
- `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.
- `go/` — retired Go native-runtime experiment; kept only where the TypeScript
  runtime still references it. New work does not go here.
- `structure/` — maintainer invariants and architecture notes; read before
  changing shared subsystems. [`structure/INDEX.md`](./structure/INDEX.md) is the
  reading order and the source-ownership table, and
  [`structure/AGENTS.md`](./structure/AGENTS.md) holds the rules for changing
  anything in there. Ownership is not advisory: changing an owned source area
  obliges the same change to update its doc, and `bun run structure:check`
  (wired into the suite by `tests/ci-workflows/structure-ssot.test.ts`) fails on a
  doc that names a path this tree no longer has, on an invariant whose test is
  gone, and on a new `src/` area nobody claimed.
- `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
  release authority.
- `desktop/` — Tauri v2 desktop shell, bootstrap UI, and compiled proxy sidecar preparation.
- `devlog/` — planning and investigation notes, tracked in this repository. See
  "The `devlog` directory" below for what may and may not go there.

Read the nearest nested `AGENTS.md` before changing files in a scoped
directory (`src/`, `gui/`, `docs-site/`, `scripts/`, `.github/`).

## Optional subsystems stay off the core path

`src/lab/` (Compatibility Lab) is opt-in. A user who configures one provider and
one model — no routing profile, no Lab — must execute no Lab code and start no
Lab timer.

Three files carry every such user's request path and must not reach `src/lab/`,
directly or transitively:

- `src/router.ts`
- `src/server/lifecycle.ts`
- `src/server/responses/core.ts`

`tests/lab/core-lab-boundary.test.ts` enforces this by walking the runtime import
graph and printing the offending chain on failure. It is not a style rule: the
original violation hid in a six-hop chain
(`assemble → quota → auth-api → native-main-admission → lifecycle → lab`) where
no single file looked wrong, and it pulled ~69 Lab modules into every install.

An optional subsystem registers into a core-owned slot at activation instead of
being imported. The existing seams are `src/server/passive-route-linker.ts`,
`src/routing/compatibility/provider-slot.ts`, and
`src/lib/optional-shutdown-hooks.ts`.

`src/server/index.ts` is deliberately exempt: a composition root is supposed to
know which optional subsystems exist. Its obligation is the gate, not the import
— activation must stay behind `labActivationRequired`, and it must stay
synchronous. Everything between `Bun.serve` and the return of `startServer` runs
in one synchronous turn, which is what guarantees a policy route can never be
evaluated before its evidence provider is registered. The synchronous
subagent-fallback chain has nowhere to await, so an `await` added before the
activation block would silently reroute subagents to a different model than the
operator configured.

That one is enforced too, in the same file: a scan reads the window between the
`Bun.serve` call and the `labActivationRequired` check and fails on any `await`
that would suspend `startServer` itself, plus on `startServer` being declared
`async`. It has to ignore comments, string bodies, and nested functions to be
usable, because the window legitimately contains three awaits inside the
`server.stop` closure and two comments that mention the word. Until it existed,
this paragraph was the only thing holding the guarantee.

Design and audit history: `devlog/_fin/260814_lab_core_decoupling/`.

## The `devlog` directory

Planning notes, triage matrices, and investigation artifacts live in `devlog/`,
tracked like any other documentation. There is no submodule and no private
mirror. It was a private submodule until the pointer churn outgrew its value:
1723 commits touched the gitlink, and `dev`, `preview`, and `main` each carried a
different pointer, so every branch move and promotion dragged a diff.

- `devlog/_plan/` — units still open, one directory per unit, decade-numbered
  docs.
- `devlog/_fin/` — closed units, moved here once a terminal outcome is recorded.
  A `_fin` unit is a record of work already visible in public git history.
- `devlog/_chase/` — external reference material for parity comparisons.
  Reference *clones* are gitignored: they are third-party source carrying their
  own licenses and have no business in this repository's history.

Nothing in the build, typecheck, or test path reads from `devlog/`, so a
contributor who ignores it entirely still passes every gate. `privacy:scan` does
read it — that is deliberate, and it is what makes a public devlog safe rather
than merely visible.

Two mechanical guards in `tests/ci-workflows/repo-hygiene.test.ts` back this up: no `160000`
gitlink may be tracked anywhere, and neither the vendored reference clones nor
the security triage excised before publication may reappear in the index. Both
were driven red once to prove they are not vacuous. The gitlink assertion exists
because a gitlink in a tree CI does not initialize breaks `actions/checkout` for
every contributor, which happened twice.

## Security working notes

**Security work is done in scratch space, never in a tracked directory.** That
includes unreleased findings, severity assessments, draft advisories, exploit
or bypass reasoning, reproduction steps for an unfixed defect, and
pre-disclosure patch plans.

Use `.tmp/` in the working tree (already gitignored) or a `mktemp -d` path.
`devlog/` is **not** an acceptable location — it is a public directory in a
public repository, so anything committed there is disclosed the moment it is
pushed, and the history is not practical to purge afterwards. A private
repository is not acceptable either: it gets cloned across machines and CI and
outlives the embargo.

**This binds maintainers exactly as it binds contributors and agents.** The rule
has been violated by maintainer-authored triage before: two units of open
security review accumulated under `devlog/_plan/` and had to be excised before
this directory could be published. Seniority is not an exemption, and "it is
only in the private half" is no longer a thing that exists.

The test to apply before writing a security note into `devlog/`: **is there
already a public diff that reveals this weakness?** If the fix has shipped, the
writeup discloses nothing new and belongs in `_fin/`. If it has not, the note is
pre-disclosure material and goes to scratch. That distinction is why closed
hardening records stay in the tree while open triage does not.

Only the published outcome reaches a repository — the fix itself, its
regression test, the release note, the advisory once it is public. Draft the
advisory in scratch space and delete the scratch directory once the advisory is
live.

This applies to `AGENTS.md`-following agents as much as to humans. If a task
asks you to write up a security finding, put the write-up in scratch space and