A minimalist coding-assistant CLI built on Vercel's ai-sdk. Small core, nine extension categories, deterministic state-machine workflows.
Why · Three Tenets · Status · Install · Usage · Architecture · Contributing · License
Most coding CLIs hard-wire one provider, one toolset, and one workflow — integration is a fork. And the LLM is treated as the author of the workflow, which means the workflow drifts whenever the model does.
stud-cli inverts both: the core is a tiny plugin host, and State Machines are a first-class extension category with authority over turn progression. The LLM executes; code the user wrote holds authority.
| Tenet | What it means |
|---|---|
| Small core, many extensions | Core owns the message loop, event bus, session format, context assembly, registries, env provider, host API, extension lifecycle, configuration scopes, security modes, MCP client, and discovery. Everything else is an extension. See Extensibility Boundary. |
| Deterministic over magical | State Machines govern 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. Environment and settings values do not enter the LLM request by default. See LLM Context Isolation. |
0.1.0 is still pre-release, but the CLI is no longer just a placeholder. The current source tree now includes a real bootstrap slice:
stud-clican run a first-run provider setup flow and write~/.stud/settings.json.- entering a directory with
<cwd>/.stud/now triggers a real project-trust decision before project settings are read. stud-cli --versionandstud-cli --helpwork again.- the bundled default console TUI owns the session header, resumed-history replay, assistant streaming, tool-call notices, and turn errors.
- sessions persist under
~/.stud/sessions/<sessionId>/manifest.json, andstud-cli --continueresumes the latest session with prior conversation visible. --headlessconsumes stdin for a single turn; interaction prompts emit a structured headless-required error unless--yolois set.- the default runtime toolset is backed by
agentooland includes all non-task-*tools (bash,glob,grep,read,edit,write,multi-edit,diff,lsp,web-fetch,http-request,memory,sleep,web-search,tool-search, andask-user).
What is still incomplete:
- bundled-provider quality is uneven:
openai-compatible,gemini, andcli-wrapperare the practical paths today; the Anthropic adapter is still incomplete. - the full extension-discovery/runtime graph described in the wiki is not what the CLI boot path uses yet; bundled providers are statically registered for now.
- MCP, dynamic extension discovery/reload, SM runtime attach, and capability-negotiated provider/model switching are still integration gaps.
| Phase | Scope | State |
|---|---|---|
| Core types + error model | Contract meta-shape, 9 contract interfaces, 8 typed error classes | Planning |
| Lifecycle + registries + message loop | Stage pipeline, per-category registries, validation | Planning |
| Provider + Tools + UI (bundled) | First-party provider, default toolset, default console TUI | Runtime slice |
| Security + Session Store + audit | Trust prompt, allowlist / ask / yolo, filesystem store, audit trail | Planning |
| State Machines + MCP | Stage definitions, grantStageTool, MCP client |
Planning |
0.1.0 — first usable release |
Everything above + CI + packaging | Not started |
Track progress on GitHub Issues and the wiki.
npm install -g stud-clistud-cli
stud-cli --help
stud-cli --versionOn a fresh machine the CLI now prompts for:
- a provider selection
- a provider auth path
- project trust when
<cwd>/.stud/exists
The resulting global files live under ~/.stud/:
settings.jsonfor provider selection and configtrust.jsonfor project trust decisionssecrets.jsonfor locally stored secret references used by non-env auth pathsaudit.jsonlfor bootstrap-side audit recordssessions/<sessionId>/manifest.jsonfor durable session history
stud-cli is a plugin-host runtime with nine extension categories: Providers, Tools, Hooks, UI, Loggers, State Machines, Commands, Session Stores, and Context Providers. Each category is typed, versioned, and validated at load.
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
Full architecture documentation lives in the wiki. Start with whichever matches your intent:
- High-Level Architecture — the one-page overview.
- Contract Pattern — the meta-shape every extension category conforms to.
- Message Loop — the six-stage turn lifecycle.
- State Machines — the category that holds workflow authority.
- Trust Model — scopes, project trust, extension isolation posture.
- Reading Paths — audience-based tours through the wiki.
The wiki is the architecture source of truth. Before opening a PR, read CLAUDE.md and the rules in .claude/rules/. Contract changes require a contractVersion bump on the matching wiki page — see Versioning and Compatibility.
Open an issue first to discuss non-trivial changes: GitHub Issues.
Built with Claude Code. Not affiliated with or endorsed by Anthropic.