Philosophy

ScaiFlux is an agentic coding tool first. Everything else — the REPL, the slash commands, the serve-mode protocol — is the distribution wrapper around that one product idea: a coding agent that reaches into your workspace and does things, not a chat interface that describes what you could do.

That framing decides a lot of the small choices below.

It exists to:

1. Make the model do the work, not narrate it. Tools (Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, TodoWrite, …) are first-class — the agent invokes them inline during a turn rather than telling you to. Permission modes (read-only, workspace-write, prompt, plan) are the dial that controls how aggressive that gets.
2. Be hackable. Python's ubiquity and readability make the harness easy to fork, inspect, and extend without a compile step.
3. Preserve the parity harness as the acceptance gate. Every behavior change is proven against deterministic mock-service scenarios.
4. Speak one wire protocol. The inference path is OpenAI-compatible streaming chat completions — ScaiGrid's native surface — so the SSE
   • tool-call loop has one shape to maintain and works unchanged against BYO OpenAI-compat backends.
5. Keep layering strict. api ← tools / runtime ← commands / plugins ← cli. No back-references; no cycles.
6. Prefer idiomatic Python over mechanical translation. Async-first with httpx + anyio, typed with pydantic v2, CLI with typer, REPL with prompt_toolkit, rendering with rich.

ScaiFlux targets ScaiGrid (inference) and ScaiKey (identity). The v0.1.0 baseline carries a single OpenAI-compatible provider repointed at ScaiGrid.