Home

stud-cli

A minimalist coding-assistant CLI built on Vercel's ai-sdk. Core is a small plugin-host runtime. Every capability — providers, tools, hooks, UI, loggers, state machines, commands, session stores, context providers — is an extension.

Why it exists: to make deterministic, state-machine-driven workflows first-class. The LLM is an executor; authority belongs to code the user wrote.

This wiki is the architecture source of truth. It documents concepts and boundaries. No source code lives here.

---

Three tenets

Tenet	What it means
Small core, many extensions	Core owns the message loop, the event bus, the session format, context assembly, the registries, the env provider, the host API, the extension lifecycle, the configuration scopes, the security modes, the MCP client, and the discovery pipeline. Everything else is replaceable. See Extensibility Boundary.
Deterministic over magical	State Machines are a first-class extension category with authority over turn progression. The LLM does not drive the workflow; the SM does. See State Machines and the State Machine Workflow flow.
Trust is a real boundary	Entering a new project triggers a first-run trust prompt. Env and settings values do not enter the LLM request by default. See LLM Context Isolation.

---

Quick start, by why you are here

You are…	Start here
Running stud-cli for the first time	First Run flow → Vision → Default Chat flow
New to stud-cli	Vision → High-Level Architecture → Default Chat flow
Writing an extension	Contract Pattern → your category's contract under contracts/
Designing a state-machine workflow	State Machines contract → State Machine Workflow flow → Ralph case study
Reviewing for security / trust	Trust Model → Extension Isolation → LLM Context Isolation
Operating or deploying	Project Root → Configuration Scopes → Session Resume flow
Reading the whole thing in order	Reading Paths § Path 6

Full tours by audience: Reading Paths.

---

The architecture in one diagram

flowchart LR
    User[User]:::actor
    LLM[LLM backend]:::actor
    FS[(Filesystem)]:::actor
    MCPsrv[MCP server]:::actor

    subgraph Core[stud-cli core]
        direction TB
        Kernel[Message loop<br/>Host API<br/>Interaction protocol<br/>Session format<br/>Context assembly<br/>Registries<br/>Env provider<br/>Security modes<br/>MCP client<br/>Observability<br/>Discovery + validation]
    end

    subgraph Ext[Nine extension categories]
        direction TB
        Providers[Providers]
        Tools[Tools]
        Hooks[Hooks]
        UI[UI]
        Loggers[Loggers]
        SM[State Machines]
        Cmds[Commands]
        Stores[Session Stores]
        CtxP[Context Providers]
    end

    User -- "input / output" --- UI
    UI -- "events + interaction" --- Core
    Cmds -- "dispatch" --- Core
    Providers -- "adapter" --- Core
    Providers -- "requests" --- LLM
    Tools -- "tool calls" --- Core
    Hooks -- "stage interception" --- Core
    Loggers -- "sink" --- Core
    SM -- "authority" --- Core
    Stores -- "persistence" --- Core
    Stores -- "read / write" --- FS
    CtxP -- "context fragments" --- Core
    Core -- "MCP client" --- MCPsrv

    classDef actor fill:#eef,stroke:#447,color:#112

Loading

Detail: High-Level Architecture.

---

Navigating

• The sidebar is the authoritative index.
• The Glossary is the authoritative vocabulary.
• The Extensibility Boundary is the authoritative list of what is core vs. extensible.
• CLAUDE.md governs how this wiki is maintained.

---

Not here yet

stud-cli v1 is in-process with no extension sandbox. Registries for published extensions, signing, and pinning are future work. See Extension Isolation and Extension Integrity for the full posture.