# letscode

> letscode is a minimal, OpenAI-compatible coding agent for the terminal, written in Python. Point it at any endpoint that speaks the OpenAI Chat Completions wire format (OpenAI, Ollama, Fireworks, OpenRouter, DeepSeek, Z.AI, Gemini, vLLM, llama.cpp's `llama-server`, …) and get a streaming agent loop with the four tools that cover most coding sessions — `read`, `write`, `edit`, `bash` — plus skills (agentskills.io format), slash commands, tree-shaped sessions, and a pluggy-based plugin system that extends every layer. A built-in model catalog maps each model to a provider, so `letscode --model deepseek-chat` routes to DeepSeek off `DEEPSEEK_API_KEY` with no per-session base-URL juggling. It is an application, not a framework; the plugin contract is a documented, semver-versioned stable surface.

Key facts for tools: `pip install letscode` (or `uv tool install letscode`); Python ≥ 3.12; API keys come from the environment only, never from config files. Three run modes — interactive (streaming TUI), one-shot (`letscode "prompt"`), and print (`-p`, pipe-friendly). A second machine-facing mode, `letscode --mode rpc`, streams the agent's `Event` Pydantic models as newline-delimited JSON over stdio for IDE/host integration; the wire schema **is** those models via `model_dump(mode="json")`, so a client dispatches on each event's `type` and MUST ignore unknown types/fields. Plugins are ordinary Python packages that declare a `[project.entry-points.letscode]` module of `@hookimpl`s; they may only import from the documented stable surface (`letscode.agent.tools`, `.messages`, `.events`, `.state`, `.subagent`, `.execution_env`, `.hookspecs`, `letscode.llm.types`, `letscode.plugins.registries`, `letscode.commands.dispatch`, `letscode.frontends.protocol`, `letscode.skills.loader`). The complete single-file reference for coding agents is [llms-full.txt](llms-full.txt).

## Docs

- [Getting started](getting-started.md): install (uv / pipx / source), first run, interactive vs. one-shot vs. print mode, switching providers
- [Overview](index.md): what letscode is and isn't; the three layers (LLM client → agent loop → terminal frontend); the deliberate non-goals
- [Configuration](user-guide/configuration.md): the precedence chain (CLI flag > env var > project config > user config > default); `~/.letscode/config.toml`; the env vars; why API keys are env-only
- [Slash commands](user-guide/slash-commands.md): every `/command` in core — help/quit/reset, `/model` (interactive picker), sessions (`/tree` `/fork` `/clone` `/new` `/resume` `/name`), output (`/copy` `/export` `/share`), steering (`/steer` `/follow-up` `/queue`), `/compact`, `/reload`, `/skill:<name>`
- [Skills](user-guide/skills.md): the agentskills.io `SKILL.md` format, the eight discovery paths, and the two invocation routes (`/skill:<name>` and the auto-wrapped `skill_<name>` tool)
- [Sessions](user-guide/sessions.md): JSONL persistence under `~/.letscode/sessions/<cwd-hash>/`, `-c` continuation + resume recap, labels/auto-naming, the tree format, custom messages, compaction
- [Input surfaces](user-guide/prompts.md): `@path` file-inline, `!cmd` / `!!cmd` shell-splice, and `~/.letscode/prompts/*.md` templates invoked as `/<name> arg`
- [MCP servers](user-guide/mcp.md): configure Model Context Protocol servers as tool sources via the `letscode-mcp` plugin
- [Agent loop](architecture/agent-loop.md): the `async def agent_loop(...) -> AsyncIterator[Event]`; per-turn event sequence; parallel vs. sequential tools; cancellation; provider/tool error handling
- [Events](architecture/events.md): the `Event` and nested `StreamEvent` discriminated unions; the per-turn sequence; `RetryEvent`; additive-only versioning
- [RPC mode](architecture/rpc-mode.md): `letscode --mode rpc` — NDJSON over stdio; the Event models are the wire; no translation layer
- [Extension model](architecture/extension-model.md): the five extension types, the ten lifecycle hooks, the stable-import contract, the semver rule
- [Plugin authoring](plugins/authoring.md): write a plugin in 30 minutes — tools, commands, skills, frontends, lifecycle hooks, `ExecutionEnv`, dispatching subagents with `subagent_env`
- [Reference plugin: letscode-memory](plugins/memory.md): cross-session memory as a worked end-to-end example of the extension model
- [MCP plugin: letscode-mcp](plugins/mcp.md): discover MCP servers from TOML, register their tools as native letscode tools

## Optional

- [Changelog](about/changelog.md): per-version notes on what shipped, written for the user
- [Roadmap](about/roadmap.md): shipped milestones (v0.1 → v0.7), what's next (0.7.x hardening, v0.8 `ctx.ui` + `/login`), and the deliberate non-goals
- [Lessons learned](about/lessons-learned.md): what the project got right and wrong, and what a real-terminal test-drive taught that a green test suite did not
- [Related projects](about/related-projects.md): how letscode relates to Claude Code, pi.dev, and the OpenAI-compatible agent landscape