Vision

Vision

stud-cli is a minimalist coding-assistant CLI built on Vercel's ai-sdk. Its animating idea: the core is a small plugin-host runtime, and every capability — providers, tools, hooks, UI, loggers, state machines, commands, session stores, context providers — is an extension.

This page is the why. Concrete boundaries and shapes live in Extensibility Boundary, High-Level Architecture, and the contracts/ and core/ directories.

---

Problem

Existing coding assistants are heavy. The well-known ones bundle a chat UI, a preferred model, an approval UX, a session format, a set of bundled tools, a context-compaction strategy, a logging scheme, and a hook model — all in the same runtime. Replacing any one piece means fighting the others.

That weight has two costs.

Cost 1 — Integration is a fork. Swapping a model provider, storing sessions somewhere else, logging through a different sink, or presenting the assistant inside another UI is rarely a matter of configuration; more often it means patching the product itself.

Cost 2 — Workflow drift. The user has been building a state-machine-driven plugin on top of another coding assistant. LLMs, given latitude, drift from established processes: they skip steps, improvise, "fix" detail that the process did not ask them to touch. When the process is business-critical — reviews with specific gates, releases with specific checks, onboarding with specific conversations — drift is a bug, not a feature. There is no first-class primitive in existing assistants to say this workflow is authoritative, the LLM is an executor.

stud-cli is the response to both.

---

Philosophy

1. Small core, many extensions

Core owns only what must be core: the message loop, the event and command buses, the interaction protocol, the session format, context assembly and compaction, the prompt and resource registries, the env provider, the host API, the extension lifecycle manager, the configuration scopes, the security modes, the MCP client, the observability primitives, and the discovery/validation pipeline. Everything else is an extension.

The Extensibility Boundary page is the authoritative list of what is core and what is extensible. The list is absolute: no page in this wiki may imply a core-only surface is extensible, or vice versa.

2. Deterministic over magical

When a workflow can be expressed as code, express it as code. When a decision can be gated by a deterministic check, gate it. The LLM is an executor; authority belongs to the code the user wrote.

Practically, this means:

• State Machines are a first-class extension category that own workflow progression. See State Machines contract. An attached SM runs a pipeline of stage executions — each with a fresh LLM transcript, narrowed allowedTools, and a deterministic completion channel. A sequential stage execution is its own session turn; a parallel fan-out group (siblings + optional join) bundles into one compound turn. Per-call tool gating lives in the stage's allowedTools and one-shot grantStageTool tokens; per-call argument-sensitive policy lives in guard hooks.
• Hooks are stage-scoped with transform / observer / guard sub-kinds. They are a mechanism for deterministic interception — never a smuggling channel for authority. See Hook Taxonomy.
• Commands are UI-agnostic and act on the main session. They do not gate the SM and the SM does not gate them. See Command Model.
• The event bus is projection only. Control flow rides the interaction protocol, the SM, and command dispatch. See Event Bus.

3. Trust is a real boundary

stud-cli loads code from three layers — bundled, global (~/.stud/), project (<cwd>/.stud/). The project layer is a trust boundary, treated that way:

• First-run project trust prompt. Entering a new project's .stud/ does not auto-execute its code. Core prompts once and records the decision in a user-global trust list. See Project Trust.
• MCP trust inherits project scope. A trusted project implicitly trusts its mcp.json. See MCP Trust.
• LLM context isolation. Env and settings.json values never enter the LLM request except via two sanctioned, user-visible paths. The session manifest never stores resolved secrets. See LLM Context Isolation.

v1 does not sandbox extensions. This is documented as a v1 choice with enumerated future models. See Extension Isolation.

4. Explicit over implicit

Every load-bearing decision is visible. If a provider, a Session Store, an SM, or an MCP server fails to load, the validation pipeline hard-fails on critical categories and warns on optional ones. The session manifest records the origin layer of every loaded extension. The /tools command reveals origin for tool name collisions.

When the user hot-switches model or provider and the target lacks a capability the session depends on (streaming, tool-calling, structured output, context size), core fails fast rather than silently regress. See Capability Negotiation.

5. One mental model at a time

The security mode (ask, yolo, allowlist) is chosen at session start and fixed for the session's lifetime. Changing it mid-session would invalidate the approval audit trail. Users who want policy-like gating use an SM. See Security Modes.

The project root is cwd only — no walk-up. Which project .stud/ is active is always visible from the terminal prompt. See Project Root.

---

What "minimal" means

stud-cli is deliberately small in surface area, not in power. "Minimal" here means:

• Core does not ship a UI. A default TUI is shipped as a reference extension.
• Core does not ship provider-specific knowledge. Providers are extensions keyed by protocol. See Providers contract.
• Core ships one Session Store (filesystem) as a bundled default. Any other store is an extension. See Session Store contract.
• Core does not ship an opinion about what goes into the system prompt. Context Providers are the sanctioned inputs to context assembly.
• Core does not provide a bulk-read-env API. Extensions resolve credentials by name through the env provider.

The point is that every capability is replaceable — not that every capability is missing by default.

---

Non-goals

stud-cli is not trying to be:

• A replacement for Claude Code. Different product with different defaults. If the user wants batteries-included agentic behavior, another tool is a better fit.
• A chat product. The CLI is usable headless and scriptable. Interactive chat is one UI shape among many.
• A policy engine for security. Security modes are a tool-call gate, not a general sandbox. Policy-like gating is the job of an SM.
• A sandbox for extensions. v1 runs extensions in-process. Isolation is a future-work item with a named future state. See Extension Isolation.
• A runtime for untrusted code from the network. A project's .stud/ is treated as user-authored, with a trust prompt. Registries, signing, and pinning are future work.
• A hub for secrets. Core exposes an env provider; it does not store, mint, or rotate secrets.

---

Audiences

This wiki serves both.

• Humans onboard through the Reading Paths. Extension authors start at Contract Pattern and the category they care about. Reviewers start at the security/ directory.
• LLMs that edit this wiki in future sessions (or generate implementation from it) follow the rules in CLAUDE.md and the authoritative Glossary.

When a human and an LLM disagree about what a term means, the Glossary is correct and both are out of date.

---

How to keep reading

• Glossary — load-bearing vocabulary before anything else.
• High-Level Architecture — one diagram of the pieces and how they connect.
• Extensibility Boundary — the absolute list of what is extensible vs. core-only.
• Reading Paths — audience-based tours.