Architecture

Nyzhi is a Rust workspace with six crates. Each crate has a single responsibility; dependencies flow downward from the binary to leaf crates with no cycles.

Crate Dependency Graph

The following diagram shows how the crates depend on each other. The CLI (nyz) sits at the top and depends on the TUI, core, and provider crates. Both TUI and provider depend on auth and config.

                    ┌──────────────┐
                    │  nyzhi (cli) │
                    │   bin: nyz   │
                    └──────┬───────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
   ┌───────────┐    ┌───────────┐    ┌─────────────┐
   │ nyzhi-tui │    │ nyzhi-core│    │nyzhi-provider│
   └─────┬─────┘    └─────┬─────┘    └──────┬──────┘
         │                │                  │
         │         ┌──────┴──────┐           │
         │         │             │           │
         ▼         ▼             ▼           ▼
   ┌───────────┐  ┌─────────────┐     ┌───────────┐
   │ nyzhi-auth│  │nyzhi-provider│     │ nyzhi-auth│
   └─────┬─────┘  └──────┬──────┘     └─────┬─────┘
         │               │                   │
         ▼               ▼                   ▼
   ┌─────────────────────────────────────────────┐
   │              nyzhi-config                    │
   └─────────────────────────────────────────────┘

Crate Summary

nyzhi-core Module Map

The core crate contains 39 modules covering all agent logic. This section groups them by responsibility.

Agent Loop

The agent loop drives each turn: streaming from the LLM, executing tools, and handling approval and retries.

Conversation and Sessions

Workspace and Context

Tools

The tool system implements a registry with deferred loading and role-based filtering. See Tools for the full catalog.

Features

Data Flow

Interactive Mode (TUI)

The following diagram shows how user input flows through the system in interactive mode.

User Input
    │
    ▼
nyzhi (cli) ── parse CLI args ── load config ── detect workspace
    │
    ▼
nyzhi-tui::App::run()
    │
    ├─ Build ToolRegistry (50+ tools + MCP tools)
    ├─ Create Provider (resolve credentials via nyzhi-auth)
    ├─ Start MCP servers (nyzhi-core::mcp)
    │
    ▼
Event Loop
    │
    ├─ User types message
    │   │
    │   ▼
    │   nyzhi-core::agent::run_turn()
    │       │
    │       ├─ Build system prompt (workspace, rules, tools, skills)
    │       ├─ Check context window, auto-compact if needed
    │       ├─ Provider::chat_stream() ── HTTP/SSE to LLM API
    │       │   │
    │       │   ├─ ThinkingDelta events ── displayed in TUI
    │       │   ├─ TextDelta events ── displayed in TUI
    │       │   └─ ToolCall events ── execute tools
    │       │       │
    │       │       ├─ ReadOnly tools: execute in parallel
    │       │       ├─ NeedsApproval tools: prompt user
    │       │       └─ Results fed back for next LLM turn
    │       │
    │       ├─ Retry on 429/5xx (exponential backoff)
    │       ├─ Run hooks (after_edit, after_turn)
    │       └─ Log analytics (token counts, cost)
    │
    ├─ Auto-save session
    └─ Render updated UI

Non-Interactive Mode (nyz run)

The same flow applies, but the TUI event loop is skipped. Output streams directly to stdout. Trust mode defaults apply for tool approval. See Configuration for [agent.trust].

Tool Registry Design

The tool registry uses a deferred loading pattern to keep the initial prompt size small.

1. Core tools are registered normally. Their full schemas are sent to the LLM in every request.
2. Deferred tools are registered but only indexed (name and description). They are not included in the ChatRequest tool definitions.
3. When the LLM needs a deferred tool, it calls tool_search to discover it by name or description.
4. On first use, the deferred tool is expanded — its full schema is included in subsequent requests.

This keeps the prompt under budget while making 50+ tools available. See Tools for the full list.

Permission Model

Each tool declares a permission level:

Agent Turn Lifecycle

A single agent turn (run_turn) follows this sequence:

1. Push user message onto the conversation thread.
2. Build tool definitions (filtered by role if applicable).
3. For up to max_steps iterations:
   • Inject unread teammate messages (if in a team).
   • Micro-compact the thread if any individual message is oversized.
   • If context usage exceeds auto_compact_threshold (default 85%), run full auto-compaction: summarize history, keep recent messages.
   • Build the chat request with thinking config.
   • Stream response via the provider’s chat_stream().
   • On retryable error (429, 5xx): exponential backoff, try rate-limit account rotation.
   • Execute tool calls: read-only in parallel, others sequentially.
   • For NeedsApproval tools: emit an approval request, wait for user response.
   • Offload large tool results to context files.
   • Accumulate token usage, emit usage event.
4. If the LLM stops calling tools (no tool_use in response), the turn is complete.
5. Run after-turn hooks.
6. Emit turn complete event.