Design Principles

Twelve principles that guide how we build agent-intelligence.ai — and how agents built with it should behave. Inspired by the 12-factor app and the 12-factor agents methodology.

1. 01
   [>] F01-TERMINAL — terminal-native The terminal is a first-class interface. If it runs in a terminal, it runs everywhere — CI, containers, SSH sessions, scripts. The CLI is not a wrapper around a web UI; it is the product. Every feature must be fully accessible from the command line before a web interface is considered.
2. 02
   [>] F02-ZERO2RUN — zero to running ai init → ai serve is the entire getting-started experience. Every additional step must justify its existence. No account creation, no API dashboard, no config file editing required to run a first agent. Defaults are production-grade; overrides are available but never required upfront.
3. 03
   [>] F03-FAST — fast by default Sub-200ms cold start. Static binary. No daemon required. Performance is a feature, not an optimisation pass. A Go binary with no runtime overhead means the tool gets out of the way. Slow tooling trains developers to avoid running it — fast tooling trains tight feedback loops.
4. 04
   [>] F04-PROGX — progressive exposure Simple commands work with zero flags. Depth scales with the task. ai run "summarise this" works on day one. Advanced flags — fallback chains, tool filtering, context budgets — are discoverable but never in the way. The UI should not front-load complexity onto beginners or hide power from experts.
5. 05
   [>] F05-OWN-PROMPT — own your prompts Your system prompt is yours. We don't hide it behind a framework. agent.toml is plain text. The system prompt is a field you write, read, and version-control. We provide examples and best practices, but the model sees exactly what you tell it to see — nothing injected silently by the platform.
6. 06
   [>] F06-OWN-CTX — own your context window Context is managed explicitly. No invisible token spills. What goes into the context window is what you put there. Tool results are summarised before injection when configured to do so. Token budgets are visible and enforced. The agent loop does not append blindly — it manages what the model sees deliberately.
7. 07
   [>] F07-STATELESS — stateless reducers Agents are pure functions: input state → output state. Pause, resume, and replay are first-class operations, not afterthoughts. Session state is serialisable and storable. Horizontal scaling and human-in-the-loop interrupts follow naturally from stateless design — no magic memory that breaks when you move workloads.
8. 08
   [>] F08-LOCAL1ST — local first Runs on your laptop. Cloud is an option, not a requirement. Kuzu provides an embedded graph backend that needs no external service. The full agent loop — including graph queries and tool execution — works offline. ai deploy lifts to the cloud when you're ready, not before.
9. 09
   [>] F09-PROTOCOL — protocol-native MCP and A2A are the transport layer, not an integration feature. Every agent created with ai init is simultaneously an MCP server and an A2A service endpoint from day one. Interoperability with other agents and tools is not a future add-on — it is the default deployment target.
10. 10
    [>] F10-COMPOSE — composable over monolithic Small focused agents beat one giant agent. Pipelines beat monoliths. An agent with fewer than 20 tools and a single well-defined responsibility outperforms a Swiss-army agent trying to do everything. Build the UNIX way: small programs that do one thing well, composed into pipelines via MCP and A2A.
11. 11
    [>] F11-OBSERVE — observable over magical Every inference and tool call is traceable. No black boxes. --debug shows the full context window, token counts, and tool call payloads. OpenTelemetry traces export to any backend. Errors are surfaced with enough context to self-correct, not swallowed by a retry loop. If you can't see it, you can't fix it.
12. 12
    [>] F12-ACCESS — accessible by default --plain output works in pipelines, CI, and screen readers. ANSI colour, Unicode symbols, box-drawing characters, and emoji are all stripped by --plain. The tool outputs clean, parseable text when piped. The web UI meets WCAG 2.1 AA. Accessibility is a correctness property, not a polish task.