athanor: Instructions file for Codex

AGENTS.md

Orientation for contributors and AI agents working on athanor. Read this before making changes; the invariants below are not negotiable without an explicit user decision.

What athanor is

Athanor — personal LLM alchemy on Apple Silicon. It scans the Hugging Face cache, registers MLX and llama.cpp (GGUF) models in ~/.athanor/models.json, assigns each one a stable port, supervises detached child processes, and exposes models to pi-agent. By default pi sees ingress-backed athanor-mlx / athanor-llama aggregators; direct per-model providers are available when router.enabled is false. Surfaces are an Ink TUI (athanor) and a hand-rolled CLI (athanor <cmd>).

Not a library. Not a daemon. No network listeners except the runtime children themselves (and an optional local control API, off by default).

Invariants

These invariants are mandatory. Do not change them without an explicit user decision.

1. Stable port per model. Ports are allocated on first discovery from config.portRange and persisted on the registry entry. A model's port does not change after allocation; pi-agent provider URLs must remain stable across restarts.
2. Atomic registry writes. ~/.athanor/models.json is always written via temp-file + rename in src/registry/index.ts. Never partial-write it, never keep it open across awaits.
3. Preserve non-athanor pi entries. src/sync/pi.ts rewrites only providers whose name starts with athanor-. Everything else in ~/.pi/agent/models.json (OpenAI, Anthropic, Ollama, OpenRouter, user customs) must round-trip untouched. Same for ~/.pi/agent/settings.json — only defaultProvider / defaultModel are touched, and only when a model is started as the active default.
4. Pi sync shape follows config.router.enabled. Default (router.enabled: true): up to two aggregator providers — athanor-mlx and athanor-llama — both pointing at the ingress baseUrl, each listing only models of its runtime and carrying runtime-specific compat flags (MLX sets supportsDeveloperRole: false; llama-server doesn't). Providers with zero exposed members are suppressed. When router.enabled is false: each exposed model becomes its own pi provider athanor-<runtime>-<slug> with one baseUrl per model. Never emit both shapes. The CLI verbs are expose / hide; the underlying registry field is publish: boolean (storage name, kept stable for backward-compat of on-disk models.json).
5. Runtime model id matches launch argument literally. mlx_lm.server compares the request's model field to whatever was passed as --model and falls back to a HuggingFace network lookup on mismatch. The pi model id we emit must equal the adapter's --model (MLX) or --alias (llama-server). Hub GGUF defaults to registry id (author/repo:file.gguf) unless the user set a custom piAlias different from slug. See src/adapters/model-id.ts, src/sync/pi.ts, and src/adapters/*.ts. pi's /model picker lists by id, not name.
6. Pi context metadata reflects effective served context. src/sync/pi.ts must advertise the model's effective runtime context window from merged runtime config (mergedConfigFor(entry)), not only explicit per-model formula fields and not the model's theoretical maximum. pi should see what athanor will actually serve.
7. MLX capability detection and flavor routing are separate axes. Two fields live on an MLX entry:
   • mlxCapabilities: ("vlm")[] — a detected fact about the model (does config.json advertise a vision tower?). Refreshed by ingestDiscovered and pull via detectMlxCapabilities() in src/discovery/scanner.ts. Safe to overwrite on re-scan.
   • mlxFlavor: "lm" | "vlm" — user intent about which server binary to launch. "vlm" routes to mlx_vlm.server; "lm" (or absent) routes to mlx_lm.server. Only set by athanor flavor <slug> lm|vlm (cmdFlavor in src/cli/model-commands.ts). Discovery and ingest must never touch it.