claude-code-config: Instructions file for Codex

AGENTS GUIDE (Mixedbread mgrep)

Orientation for coding agents working in this repo. Keep this handy; follow commands and conventions before editing.

Project Snapshot

• Runtime: Node.js 18+ (CI uses 20/24)
• Language: TypeScript 5.x, ESM ("type": "module", module: "NodeNext")
• Package manager: pnpm (lockfile present)
• Lint/format: Biome (biome.json), import organize on save
• Tests: bats (Bash Automated Testing System)
• Dist: tsc outputs to dist/; CLI entry dist/index.js

How to Build/Test Fast

• Install deps: pnpm install
• Build: pnpm build
• Dev run CLI: pnpm dev (compiles then runs dist/index.js)
• Type check only: pnpm typecheck
• Lint/format fix: pnpm format
• Lint/format check (CI): pnpm format:check
• Lint only: pnpm lint
• Run all tests (default short): pnpm test
• Run all including long-running: pnpm test --filter-tags long-running
• Run a single bats test by name: bats test/test.bats --filter "pattern"
• Run a single bats test by tag: bats test/test.bats --filter-tags tagname
• CI pipeline order: format:check → test (long-running) → typecheck → build

Repo Conventions

• ESM everywhere: use .js extension in imports, even for TS files (import { foo } from "./lib/foo.js").
• Paths: prefer node:path utilities; avoid string concat for paths.
• Logging: src/lib/logger.ts wires console to Winston; avoid new loggers unless necessary.
• Git helpers live in src/lib/git.ts; prefer them over custom git shells.
• Commands live under src/commands/; installers under src/install/; shared utils under src/lib/.
• CLI wired in src/index.ts via Commander; add commands there when introducing new functionality.

TypeScript Style

• strict mode on; noUnused*, noImplicitReturns, noFallthrough enforced.
• Prefer explicit return types on exported functions.
• Avoid any; use unknown or generics. Narrow early.
• Use interfaces for public contracts; types acceptable for internal utility shapes.
• Keep enums minimal; favor literal unions when possible.
• Always await promises; handle rejections. Return typed results, not Promise<void> unless appropriate.
• Use const over let where possible; avoid var entirely.
• Keep functions small; extract helpers in src/lib when shared.