Internals — how Jazz works

This page explains the machine well enough to trust it, debug it, or extend it.

Two different people need this section:

• Evaluating Jazz? You want to know whether it survives a forty-minute autonomous run or spirals into a loop and burns $40. Read Agent loop and Context management.
• Contributing to Jazz? You want to know where your code goes. Read Code map.

Everyone should read Design decisions — the harness choices and what each one trades away. If you’re changing the harness, Evals is how you find out whether it helped.

The 10,000-foot view

flowchart TB
    subgraph surfaces["Surfaces"]
        direction LR
        S1["Terminal"]
        S2["jazz run"]
        S3["Workflows"]
    end

    RUNNER["<b>AgentRunner</b><br/>resolve agent, provider, model,<br/>toolset, conversation"]

    subgraph loop["Agent loop — up to 100 iterations"]
        direction TB
        COMPACT["1 · Compact context if &gt; 80%"]
        LLM["2 · Ask the model"]
        BRANCH{"3 · Tool calls?"}
        TOOLS["4 · Execute tools<br/>(≤10 concurrent, approval-gated)"]
        GUARD["5 · Meltdown check<br/>+ budget pressure"]
        DONE["Final answer"]
    end

    FINAL["<b>Finalize</b><br/>tokens, cost, telemetry,<br/>save transcript"]

    S1 --> RUNNER
    S2 --> RUNNER
    S3 --> RUNNER
    RUNNER --> COMPACT
    COMPACT --> LLM
    LLM --> BRANCH
    BRANCH -->|yes| TOOLS
    TOOLS --> GUARD
    GUARD --> COMPACT
    BRANCH -->|no| DONE
    DONE --> FINAL

    classDef hot fill:#f9a03f,stroke:#b3541e,color:#1a1a1a
    classDef core fill:#4f9d9d,stroke:#2f6d6d,color:#ffffff
    class LLM,TOOLS hot
    class RUNNER,FINAL core

Everything interesting happens in that loop, and the interesting parts are the guards around it — compaction, meltdown detection, and budget pressure — not the request itself.

The layers

Jazz follows Clean / Hexagonal architecture. The dependency rule is enforced: core/ imports nothing from services/.

flowchart TB
    CLI["<b>cli/</b><br/>commands · Ink TUI · presentation<br/><i>user-facing</i>"]
    CORE["<b>core/</b><br/>agent loop · tools · context · types<br/>service contracts (ports)<br/><i>zero external dependencies</i>"]
    SERVICES["<b>services/</b><br/>LLM adapters · storage · MCP<br/>logger · history · telemetry<br/><i>implements the ports</i>"]

    CLI --> CORE
    SERVICES -->|"implements"| CORE
    CLI -.->|"wires Layers"| SERVICES

    classDef core fill:#4f9d9d,stroke:#2f6d6d,color:#ffffff
    class CORE core

core/ defines an interface plus an Effect Context.Tag; services/ provides a Layer that satisfies it; cli/ merges the Layers at startup. That’s why swapping a storage backend or adding an LLM provider touches one directory.

Details and conventions: Code map.

Pages

Key numbers

Useful when reading logs or sizing a deployment. All from packages/core/src/constants/agent.ts.