# src KNOWLEDGE BASE
## OVERVIEW
`src/` is runtime root: CLI, agent loop, provider streams, tools, sessions, prompt assembly, output rendering, and optional Mission Control TUI.
## STRUCTURE
```text
src/
├── lib.rs # crate entry boundary; small public API
├── bin/magi-code.rs # thin binary shim
├── cli/ # parsing, validation, mode/subcommand routing
├── agent/ # turn loop, prompt build, replay, tool lifecycle, cancellation
├── providers/ # provider transports and stream parsing
├── tools/ # schemas, dispatch, cwd/root safety, display metadata
├── sessions/ context/ # JSONL lifecycle, replay, cache keys, token budgets
├── config/ # settings/auth paths and schema
├── output/ rendering/ # events, redaction, CLI renderers, markdown/code/diff projection
├── tui/ # Mission Control display/input/controller/state/render
├── skills/ subagents/ # discovery and bounded child-agent execution
├── commands/ hooks/ shell/ # slash commands, hook runtime, shell helpers
├── mcp/ # MCP client, OAuth, JSON-RPC, tool routing
├── instructions/ # runtime instruction discovery/assembly
└── herdr.rs # herd/coordination reporting helpers
```
## WHERE TO LOOK
| Entry/mode routing | `lib.rs`, `bin/`, `cli/` | CLI decides mode; semantics stay below. |
| Parent agent setup | `agent/runner.rs` | Construction gate for prompt/tool/profile-ready agents. |
| Turn execution | `agent/mod.rs`, `agent/tool_lifecycle.rs` | Provider stream → tool call → result → continuation. |
| Provider request shape | `providers/` | Keep auth/header/body quirks provider-local. |
| Tool safety/dispatch | `tools/`, `shell/` | Cwd bounds, schemas, processes, search, file tools. |
| Session/replay/cache | `sessions/`, `context/`, `persistence.rs` | JSONL, sidecars, replay, atomic writes. |
| Config/auth/models | `config/`, `login.rs`, `model_catalog.rs`, `thinking.rs` | MC_HOME and provider capabilities. |
| Prompt inputs | `instructions/`, `skills/`, `subagents/`, `../prompts/` | Discovery/filtering before provider payload. |
| User-visible output | `output/`, `rendering/`, `tool_display.rs` | Events, redaction, transcript renderers. |
| Mission Control | `tui/` | Display/input state only; runtime owns execution truth. |
| MCP servers | `mcp/` | Stdio/HTTP, OAuth PKCE, JSON-RPC, qualified routing. |
## CONVENTIONS
- Runtime stays blocking/synchronous unless ADR changes architecture.
- `cli/` stays glue: parse, select mode, call runtime; no provider/tool/session policy here.
- Keep provider details inside `providers/`; expose normalized events/errors upward.
- Keep durable writes behind persistence/config/session write paths; preserve locking and atomic semantics.
- Use typed structs across internal seams; keep loose JSON near provider/tool protocol edges.
- TUI owns display/input state only. Shared runtime owns execution truth.
- Prompt-visible changes need deterministic ordering and redaction review.
## ANTI-PATTERNS
- Do not bypass `agent/runner.rs` with ad hoc provider-driving loops.
- Do not move provider/tool/session semantics into `cli/`.
- Do not make async runtime changes without architecture decision update.
- Keep cwd/root-sensitive behavior in owning modules with focused safety coverage.
- Keep TUI persistence boundaries explicit when those seams change.