Repository Scope Map

April 25, 2026 ยท View on GitHub

Ownership map for source paths and documentation paths.

Top-Level Map

PathPurpose
scripts/Installed wrapper, official Codex forwarder, runtime app/router helpers, repo hygiene
index.tsOptional plugin-host runtime entry
lib/Core auth, storage, account manager, runtime proxy, app bind, UI, policies
docs/User docs + references + maintainer docs
test/Unit/integration/property tests
config/Plugin-host config examples
vendor/Vendored codex-ai-plugin + codex-ai-sdk dist shims
assets/Static project assets
dist/Generated build output (do not edit directly)

Core Runtime Ownership

AreaPrimary files
CLI wrapper and forwardingscripts/codex.js, scripts/codex-routing.js, scripts/codex-bin-resolver.js
CLI auth managerlib/codex-manager.ts
Settings hublib/codex-manager/settings-hub.ts, lib/codex-manager/settings-hub/
OAuth flow/serverlib/auth/*
Runtime rotation proxylib/runtime-rotation-proxy.ts, lib/runtime/config-toml.ts, lib/runtime-constants.ts
Runtime app bind/routerlib/runtime/app-bind.ts, scripts/codex-app-router.js, scripts/codex-app-launcher.js
Runtime observabilitylib/runtime/runtime-observability.ts, lib/codex-manager/commands/status.ts, lib/codex-manager/commands/report.ts, lib/codex-manager/commands/rotation.ts
Storage and pathslib/storage.ts, lib/storage/paths.ts, lib/runtime-paths.ts
Worktree resolutionlib/storage/paths.ts (resolveProjectStorageIdentityRoot)
Unified settingslib/unified-settings.ts, lib/dashboard-settings.ts, lib/config.ts
Account runtimelib/accounts.ts, lib/rotation.ts, lib/forecast.ts
Quota runtimelib/quota-probe.ts, lib/quota-cache.ts, lib/preemptive-quota-scheduler.ts
Resiliencelib/live-account-sync.ts, lib/session-affinity.ts, lib/refresh-guardian.ts, lib/refresh-lease.ts
Request pipelinelib/request/*, index.ts
Optional plugin-host entryindex.ts
UI systemlib/ui/*
Repo hygienescripts/repo-hygiene.js

Documentation Ownership

AreaFiles
User docsdocs/getting-started.md, docs/configuration.md, docs/troubleshooting.md, docs/features.md, docs/upgrade.md, docs/privacy.md
Reference docsdocs/reference/*
Maintainer docsdocs/development/*, docs/DOCUMENTATION.md
Style and consistencydocs/STYLE_GUIDE.md

AGENTS Scope Hierarchy

Within this repo:

  1. AGENTS.md (root scope)
  2. lib/AGENTS.md for lib/**
  3. test/AGENTS.md for test/**

Deeper AGENTS files override higher-level guidance for their subtree.

Generated or Local Artifacts (Not Source)

  • dist/
  • .tmp* directories
  • local caches/logs under runtime roots

Do not treat these as primary implementation sources.

Feature Placement Checklist

When adding a new feature:

  1. Implement runtime/module code in lib/.
  2. Add/extend tests in test/.
  3. Update user docs (docs/features.md + relevant guides).
  4. Update references if command/setting/path changed.
  5. Update architecture/config flow docs for cross-cutting behavior.
  6. Update runtime-rotation docs when forwarded Codex, shadow-home, proxy, app bind, or launcher behavior changes.
  7. Update docs/upgrade.md and any npm-script references when command flow/build steps changed.