one-code-extension 0.1.4 → 0.3.1

package/LICENSE

@@ -22,6 +22,26 @@ SOFTWARE.
 
 ---
 
+ADDITIONAL NOTICE — AUTONOMOUS EXECUTION
+
+This software runs a large language model as an autonomous agent. It reads,
+writes and deletes files, runs shell commands, and calls network services on
+your behalf, and in some modes it does so without asking you first.
+
+Its permission rules, approval classifier and safety checks are best-effort
+measures, not guarantees. A model can take a destructive or unintended action
+that no rule matched, achieve a forbidden effect by a route the rules did not
+anticipate, or be steered by content it reads. You are responsible for what you
+authorize it to do, for the environment you run it in, and for keeping backups
+and version control of anything you care about.
+
+As stated in the MIT terms above, the software is provided "as is" and the
+authors and copyright holders accept no liability for any damage, data loss,
+cost, or other harm arising from its use, including actions taken by the model
+it runs.
+
+---
+
 This package bundles or adapts work from other MIT-licensed projects:
 
 - The language-server command table in `extensions/lsp/servers.ts` follows the

package/README.md

@@ -1,208 +1,253 @@
 # One Code
 
-**The Claude Code experience — on any model you want.**
+**Claude Code with the model slot left open. The full workflow, open source, on any model or provider.**
+
+Claude Code is a good harness. It just ships bolted to one model. One Code
+unbolts it, and runs the whole workflow (subagents, git worktrees, auto mode,
+ultracode workflows, plan mode) on the model you pick. Keep Claude Code for the
+work that earns its best model. Reach for One Code whenever a cheaper or
+different model fits the job.
+
+The parts that make the harness good (the steering, the permission gate, the
+context management) live in the harness, not the model. One Code brings all of
+them across, because the good part was never the logo.
+
+<p align="center">
+  <img src="demo/onecode.gif" alt="One Code switching models and running an agentic task" width="820">
+</p>
+
+[User guide](docs/guide/README.md) ·
+[Bring your Claude Code setup](docs/guide/bring-your-claude-code-setup.md) ·
+[Differences from Claude Code](docs/guide/differences-from-claude-code.md) ·
+[Command reference](docs/guide/reference.md)
+
+## ✨ What you get
+
+- **Any model, any provider.** Anthropic, OpenAI, Gemini, OpenRouter, or a
+  local model. Bring your own and switch mid-session with `/model`. Nothing
+  stops you.
+- **Mix providers in one session.** The parent and each subagent pick their own
+  model and provider, so an ultracode workflow can fan out to a cheap tier while
+  the parent stays on a frontier model. A single-gateway setup cannot do this,
+  which is usually the reason people switch.
+- **Your Claude Code setup runs unchanged.** `CLAUDE.md`, `.claude/commands`,
+  `.claude/skills`, `.claude/agents`, `.mcp.json`, plugins, and permission rules
+  are picked up as they are. No migration, and no second config file to keep in
+  sync.
+- **Capability-tiered prompting.** A weaker model gets more guidance, not less.
+  Not out of politeness; it is how you get output you can use.
+- **A package, not a fork.** One Code is a [pi](https://github.com/earendil-works/pi)
+  package, so you extend it with your own extensions, themes, and settings.
+  Forks go stale; packages do not have to.
+- **Free and open source** under the MIT license.
+
+## 🚀 Get started
+
+You need **Node.js 22.19+**. One Code is developed and verified on macOS and
+Linux; WSL works too. Native Windows is untested.
 
-One Code gives you Claude Code's whole workflow: subagents, ultracode workflows,
-skills, MCP, plan mode, hooks, a real permission system, project memory — but
-runs it on **any provider**. Anthropic, OpenAI, Gemini, a local Ollama model, or
-a gateway like OpenRouter. The **same tool surface**, the same `.claude/` config,
-your choice of brain behind it.
+```bash
+npm install -g @one-ai/one-code
+cd your-project
+onecode
+```
+
+Inside One Code, run `/login` to connect a provider, then `/model` to pick a
+model. You can also pass a provider key through an environment variable such as
+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
+
+Open a project that already has a `CLAUDE.md` or `.claude/` setup and One Code
+reuses it right away. Starting fresh? `/init` drafts a `CLAUDE.md` for you.
 
-Free and open source (MIT). No lock-in, no subscription, no fork of anything —
-One Code is a package for the [pi coding agent](https://github.com/earendil-works/pi),
-so upstream improvements land as a version bump.
+Not sure what is wired up? Run `onecode doctor` (or `/doctor report` inside a
+session). It reports which providers have credentials, which model each role
+uses, what of your Claude Code configuration was picked up, and which programs
+are missing. `/doctor` runs the full checkup and has the model fix what it finds.
 
-## Install
+One Code is free. Model access, usage charges, and rate limits are between you
+and your provider. See [Providers and models](docs/guide/providers-and-models.md)
+for connection options.
 
-One project, two npm packages — pick the one that fits you:
+### Other ways to install
 
-| You | Install | Package |
-|---|---|---|
-| **Most people** (new to pi included) | `npm install -g @one-ai/one-code` | [`@one-ai/one-code`](https://www.npmjs.com/package/@one-ai/one-code) — the app: its own `one-code` command, a pinned pi bundled inside, state isolated in `~/.one-code`, coexists with any existing `pi` |
-| Already running pi, want it on your own install | `pi install npm:one-code-extension` | [`one-code-extension`](https://www.npmjs.com/package/one-code-extension) — just the extensions; rides your pi (tested against pi 0.83–0.84, warns outside that range) |
+**Homebrew** installs Node for you:
 
 ```bash
-npm install -g @one-ai/one-code
-cd your-project && one-code
+brew install isurumaduranga/one-ai/onecode
 ```
 
-Or via Homebrew (also installs Node for you):
+**Already on pi?** Add the extensions to your existing installation:
 
 ```bash
-brew install isurumaduranga/one-ai/one-code
-# or tap once, then it's just: brew tap isurumaduranga/one-ai && brew install one-code
+pi install npm:one-code-extension
 ```
 
-> The npm route needs **Node 22.19+**.
+The app package, [`@one-ai/one-code`](https://www.npmjs.com/package/@one-ai/one-code),
+bundles a pinned pi and gives you the `onecode` command. The extension package,
+[`one-code-extension`](https://www.npmjs.com/package/one-code-extension), runs on
+your own pi and is tested against pi 0.83 to 0.85; use `pi` in place of `onecode`
+for that install.
+
+The app opens in a full-screen terminal interface by default. See the
+[installation guide](docs/guide/installation.md) for display settings and more.
+
+## 🎛️ Put different models to work
+
+A main conversation and a repository-wide investigation do not need the same
+model. Keep your preferred model in charge and let subagents use another
+provider for exploration, tests, or review.
+
+1. Choose the main model with `/model`.
+2. Set the default for subagents and workflow agents with
+   `/subagent <provider/model-id>`.
+3. Ask for delegated work, for example:
+
+   > Use subagents to investigate the authentication code and its tests.
+   > Have them report their findings, then make the fix in the main session.
+
+Agent definitions in `.claude/agents/` can name their own model, tools, and
+instructions. Use `/agents` to follow their progress and `/model` to change the
+main model as the task changes.
+
+This is where you decide where the money goes. Actual cost and quality depend on
+the models, the task, and how much you delegate.
+
+[Subagents and workflows →](docs/guide/subagents-and-workflows.md)
+
+## ♻️ Reuse the setup you already have
+
+One Code reads Claude Code configuration directly. There is no import step.
+
+| Your configuration | How One Code uses it |
+|---|---|
+| `CLAUDE.md` | Project instructions, including nested files and `@path` imports. Falls back to `AGENTS.md` when a directory has no `CLAUDE.md`. |
+| `.claude/skills/` and `.claude/commands/` | Discoverable skills and slash commands. |
+| `.claude/agents/` | Subagent definitions with their model, tools, and instructions. |
+| `.claude/settings.json` | `allow`, `deny`, and `ask` permission rules, plus supported command hooks. |
+| `.mcp.json` | MCP servers with tools loaded on demand. |
+| Installed Claude Code plugins | Plugin agents, skills, commands, and MCP servers, namespaced by plugin. |
+
+Claude Code tool names such as `Read`, `Bash`, `Edit`, and `Task` work in
+permission rules and hook matchers. One Code keeps its own settings separately
+and treats `~/.claude` as read-only, so nothing you already have gets rewritten.
+
+Compatibility covers configuration and workflow surfaces. Features and skills
+that need Claude Code's own hosted or desktop services are not included.
+
+[Configuration details →](docs/guide/bring-your-claude-code-setup.md) ·
+[Skills, plugins, and MCP →](docs/guide/skills-plugins-and-mcp.md)
 
-> Tip: the app opens in a **full-screen TUI** (alt-screen, restores your
-> terminal on exit) by default. On your own pi that's opt-in — set
-> `"tuiMode": "fullscreen"` in `~/.pi/agent/settings.json`, or launch with
-> `pi --tui-mode fullscreen`.
+## ⚙️ Workflows that scale with the task
 
-## Two-minute quickstart — free, no card
+### Subagents and git worktrees
 
-You need one model-provider key. Two providers hand out **free frontier-adjacent
-models** today, so you can try the whole thing for nothing:
+Give an investigation its own context window and bring the result back to the
+main conversation. Subagents run in the background, take follow-up messages, and
+can fork the current conversation when they need its context. Three agent
+definitions ship with One Code: `general-purpose`, `explore`, and `plan`.
 
-- **OpenCode Zen** ([opencode.ai/zen](https://opencode.ai/zen)) — sign up, copy
-  your API key. Free model: `deepseek-v4-flash-free`.
-- **OpenRouter** ([openrouter.ai](https://openrouter.ai)) — sign up, create a
-  key (or just OAuth from inside One Code). Free models carry a `:free` suffix —
-  `nvidia/nemotron-3-ultra-550b-a55b:free` is genuinely good.
+For parallel edits, give agents their own git worktrees. You can also move the
+whole session into a worktree with `enter_worktree` and leave it with
+`exit_worktree`.
 
-Then:
+### Ultracode workflows
+
+Put **`ultracode`** in a request for a broad audit, migration, or review. The
+model writes a JavaScript workflow that coordinates agents in parallel, with
+progress visible in `/workflows`. Use `/effort ultracode` to keep this behavior
+on across turns.
+
+Resume an interrupted run to reuse completed agent calls whose inputs still
+match. Save reusable scripts in `.claude/workflows/` to call them by name.
+Optional output-token targets stop new and queued agents once reached;
+agents already running can finish above the target.
+
+### Permissions and planning
+
+**Auto mode is the default.** A classifier judges actions that need review,
+while permission rules and deterministic checks enforce the rest. `deny` rules
+beat `allow` rules. Trust approval covers project-provided hooks, MCP servers,
+and allow rules.
+
+Press **ctrl+q** to cycle through manual, accept-edits, plan, and auto modes.
+Plan mode lets the agent investigate and write a plan file before you approve
+implementation. Use `/permissions` to inspect rules and `/auto-mode` to
+configure the classifier.
+
+The permission system is an application-level control. For OS-level isolation,
+run One Code inside a container. The guide spells out the guarantees and the
+known gaps.
+
+[Permissions and modes →](docs/guide/permissions-modes-and-auto-mode.md) ·
+[Hooks →](docs/guide/hooks.md)
+
+## 🧰 Everyday tools
+
+| Capability | What you get |
+|---|---|
+| Code and files | Read, write, edit, shell commands, background processes, repository search, and notebook editing. |
+| Web | Search and fetch, with provider search or Brave, Tavily, and Exa fallbacks. |
+| Diagnostics | Language-server diagnostics after edits; install the relevant server on your `PATH`. |
+| Long sessions | Per-repository memory, a session scratchpad, and context compaction. |
+| Task tracking | A pinned progress widget, background monitors, and scheduled wake-ups. |
+| Tool discovery | Deferred tools loaded when needed to keep prompt overhead down. |
+| Reasoning and appearance | `/effort` or **shift+tab** for reasoning effort; `onecode` and `onecode-light` themes. |
+| Customization | Extend One Code with pi extensions, themes, and settings. |
+
+The bundled skills include `simplify`, `code-review`, `security-review`, and
+`fewer-permission-prompts`. A project skill with the same name wins.
+
+For scripting and session management:
 
 ```bash
-cd your-project
-one-code            # first run asks for a provider — pick one, paste the key
+onecode -p "Explain how authentication works in this repository"
+onecode -c                       # continue the previous session
+onecode --mode json              # JSON event output
+onecode --permission-mode plan   # start in plan mode
 ```
 
-Inside the session: `/login` connects more providers (OpenRouter supports
-"Sign in with OpenRouter", no key-copying needed), `/model` switches models.
-Env vars work too: `OPENCODE_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`,
-`OPENAI_API_KEY`, and friends are picked up automatically.
-
-*(On the pi-package install, the same applies with `pi` as the command.)*
-
----
-
-## Why One Code
-
-- **Bring your own model.** Not tied to one vendor. Switch mid-session with
-  `/model`, or drive a cheap local model for routine work and a frontier model
-  for the hard parts.
-- **Your Claude Code setup already works.** `CLAUDE.md`, `.claude/commands`,
-  `.claude/skills`, `.claude/agents`, `.mcp.json`, installed plugins, and
-  `settings.json` permission rules are all picked up unchanged. Nothing to port.
-- **The features that make Claude Code good live in the harness, not the model** —
-  and One Code brings all of them across.
-
----
-
-## What you get
-
-### 🤖 Subagents
-Delegate work to child agents that each get their own context window, so only
-the answer comes back — not the noise. Define them as markdown in
-`.claude/agents/`, pick their model per agent, or `fork` one that inherits your
-conversation. Run them in the background and message them while they work, or
-isolate each in its own git worktree (below). Three ship in the box:
-`general-purpose`, `explore`, and `plan`.
-
-### ⚡ Ultracode workflows
-For big jobs — a broad audit, a migration, a review worth double-checking — say
-**`ultracode`** and the model writes a short JavaScript script that fans work out
-across many agents in parallel. Runs go to the background with a live progress
-panel; every run is journaled, so re-running replays the unchanged parts for
-free. Save scripts in `.claude/workflows/` to invoke by name.
-
-### 🔒 Permissions & auto mode
-A real permission gate reads your existing `allow`/`deny`/`ask` rules from
-`.claude/settings.json` (`deny` always wins). Cycle modes with **ctrl+q** —
-manual → accept-edits → plan → **auto**. Auto mode removes routine prompts
-*without* removing the boundary: a classifier screens each action, reads pass
-freely, and risky operations (writes outside your project, credential paths,
-force pushes, `curl | bash`) get stopped unless *you* named them. A deterministic
-safety floor protects the agent's own config no matter what the model decides.
-
-### 📋 Plan mode
-Enter a read-only planning mode where the model can only write to a dedicated
-plan file. Review the finished plan in an approval dialog before a single line of
-code changes. The plan survives context compaction, and you can edit the file
-yourself while it works.
-
-### 🌿 Git worktrees
-Send the whole session into an isolated git worktree with `enter_worktree` —
-branched from your current HEAD under `.claude/worktrees/`, so every command and
-relative path runs there and your working tree stays untouched until you
-`exit_worktree`. Subagents can each take their own worktree too, so a fan-out
-that edits files runs in parallel without ever colliding.
-
-### 🧩 Skills, plugins & MCP
-Standard [Agent Skills](https://agentskills.io) from `.claude/skills/`, whole
-Claude Code **plugins** (their agents, skills, commands, and MCP servers, all
-namespaced), and any **MCP server** from `.mcp.json` — every MCP tool is loaded
-on demand so it never bloats the prompt.
-
-### 🪝 Hooks
-Claude Code command hooks run unchanged — `PreToolUse`, `PostToolUse`,
-`UserPromptSubmit`, `SessionStart`, `Stop`, and more — with the same stdin JSON,
-exit-code semantics, and output envelope. Project hooks run only after a one-time
-consent prompt.
-
-### 🧠 Memory & long sessions
-Per-repo auto-memory that persists facts across sessions, a session scratchpad,
-and Claude Code's own compaction prompt so long conversations shrink cleanly
-instead of falling off a cliff. On Anthropic, old thinking is trimmed
-automatically to keep sessions cheap.
-
-### 🛠️ The same tool surface as Claude Code
-`read`, `write`, `edit`, `bash` (with background runs), `grep`, `find`, `ls`,
-`todo_write`, `notebook_edit`, `web_search`, `web_fetch`, `lsp_diagnostics`
-(live language-server diagnostics after edits), `ask_user_question`, task
-tracking, background monitors, scheduled wake-ups — and `tool_search`, which
-keeps rarely-used schemas out of the prompt until they're needed. On Anthropic
-and recent OpenAI models this uses the provider's native deferred-tool
-mechanism, so loading a tool never invalidates your cached prompt.
-
-Every Claude Code tool has a counterpart here, so muscle memory and rules carry
-over: Claude Code's own PascalCase names — `Read`, `Bash`, `Edit`, `Task`,
-`WebFetch`, `TodoWrite`, `EnterWorktree`, and the rest — are accepted verbatim in
-your `.claude/settings.json` permission rules and hook matchers, mapped to the
-matching tool automatically.
-
-### 🎚️ Reasoning effort & 🎨 themes
-An `/effort` slider from `minimal` to `max` (and `ultracode` past the end), on
-the same dial shift+tab cycles. Two themes ship — `one-code` (dark) and
-`one-code-light` — a warm clay accent in the spirit of Claude Code's terminal.
-
----
-
-## Everything else, briefly
-
-| | |
-|---|---|
-| **Slash commands** | `/permissions`, `/auto-mode`, `/agents`, `/skills`, `/todos`, `/subagent`, `/effort`, `/workflows`, `/plugins`, `/mcp`, `/lsp`, and every plugin command (namespaced). |
-| **Ported system prompt** | Claude Code's system prompt, adapted and tiered by model capability so smaller models get more guidance. |
-| **Steering** | `<system-reminder>` nudges, read-before-write and stale-edit guards, and denial feedback that the model actually learns from. |
-| **Other modes** | `pi -p "…"` one-shot · `pi -c` continue · `pi --mode json` for scripts · `pi --permission-mode plan` · `pi --model <provider/id>`. |
+See [Tools](docs/guide/tools.md) for every tool the model can call and the
+[command reference](docs/guide/reference.md) for every command, shortcut, flag,
+and environment variable.
+
+## 📚 Documentation
+
+The [user guide](docs/guide/README.md) covers everything: installation,
+providers and models, the terminal interface, configuration, permissions and
+auto mode, hooks, subagents and workflows, skills, plugins, and MCP, tools,
+sessions and context, background work, the doctor, differences from Claude Code,
+troubleshooting, and a full reference.
 
----
+## 💡 Good to know
 
-## Install from source
+- **Providers:** end-to-end testing has focused on Anthropic, OpenAI, and
+  OpenRouter. Other providers are less exercised, so expect the occasional rough
+  edge.
+- **Web search:** set `BRAVE_SEARCH_API_KEY` or `TAVILY_API_KEY` on a provider
+  without native search. With neither key, the fallback is Exa's rate-limited
+  keyless endpoint, and One Code labels those results.
+- **Native Windows:** hooks and background shells assume `/bin/sh` for now. Use
+  WSL until native Windows is verified.
+
+## 🔧 Install from source
+
+This installs the local extensions into an existing pi installation:
 
 ```bash
 git clone https://github.com/IsuruMaduranga/one-code
-cd one-code && npm install && cd ..
-pi install ./one-code           # a path install still needs `npm install` first for deps
-pi list                        # confirm it registered
+cd one-code
+npm install
+cd ..
+pi install ./one-code
+pi list
 ```
 
-## A real boundary, not a leap of faith
-
-Like Claude Code, One Code's security model is the **permission system plus auto
-mode**, not a promise that the model will behave. Every action is gated: `deny`
-rules always win, risky operations get stopped, and auto mode's classifier keeps
-you in flow without dropping the boundary. Want an OS-level hard wall on top? Run
-pi inside a container — the permission gate and the container compose.
-
-## Good to know
-
-- **Web search** uses your provider's own search API (OpenAI, Anthropic,
-  Gemini), so it needs a provider that offers one.
-- **LSP diagnostics** need the language server on your `PATH` (e.g.
-  `npm i -g typescript-language-server typescript`).
-- Verified end-to-end on Anthropic and OpenAI models, and through **OpenRouter**
-  (which brokers many open models — DeepSeek, Llama, Qwen, and more); other
-  providers work but are less exercised.
-- **Platforms:** developed and verified on **macOS and Linux**; **WSL** works
-  the same way (it *is* Linux). Native Windows is **untested best-effort** for
-  now: pi itself requires a bash there (Git Bash — see pi's Windows docs), and
-  One Code has known gaps on native Windows (hooks and background shells assume
-  `/bin/sh`). Don't rely on it until a Windows smoke test lands in a future
-  release.
-
-## License
-
-MIT — see [LICENSE](LICENSE). Contributions welcome.
+## 🧠 Learn the ideas behind it
+
+One Code is the practical companion to the Harness Engineering 101 series, which
+builds these ideas up from first principles: what a coding harness actually does,
+and why the good parts are model-independent.
+
+## 📄 License
+
+[MIT](LICENSE). Contributions welcome.

package/agents/explore.md

@@ -1,11 +1,12 @@
 ---
 name: explore
-description: Read-only search agent for broad fan-out searches — when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It locates code; it does not review or audit it.
-tools: read, grep, find, ls
+description: Fast read-only search agent for locating code. Use it to find files by pattern (eg. "src/components/**/*.tsx"), grep for symbols or keywords (eg. "API endpoints"), or answer "where is X defined / which files reference Y". Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: "quick" for a single targeted lookup, "medium" for moderate exploration, or "very thorough" to search across multiple locations and naming conventions.
+disallowedTools: Edit, Write, NotebookEdit, Agent
 ---
 
-You are a codebase reconnaissance agent. You can read and search; you cannot
-modify anything or run commands.
+You are a codebase reconnaissance agent. You can read and search — including
+read-only shell commands (git log, ls, wc) — but you must never modify
+anything: no edits, no writes, no state-changing commands.
 
 Your job is to find things and report *where they are*, compressed. The agent that
 delegated to you is spending its context on other work, so do not return file
@@ -16,8 +17,10 @@ Method:
 - Search broadly first (multiple patterns, several naming conventions, plausible
   synonyms), then read only the excerpts that decide the question.
 - Follow the conventions you observe rather than assuming a layout.
-- If the caller asked "very thorough", check alternative locations and spellings
-  before concluding something does not exist.
+- Calibrate to the requested search breadth: "quick" means one targeted lookup,
+  "medium" moderate exploration, "very thorough" means checking alternative
+  locations, spellings, and naming conventions before concluding something does
+  not exist. With no breadth given, default to medium.
 
 Report as a short list of findings, each with `path:line` and one line of what is
 there. State explicitly if something does not appear to exist — a confident

package/agents/general-purpose.md

@@ -1,6 +1,6 @@
 ---
 name: general-purpose
-description: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when a task needs several steps and you don't need to watch the intermediate work.
+description: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries, use this agent to perform the search for you.
 ---
 
 You are a general-purpose engineering agent working on a delegated task.

package/agents/plan.md

@@ -1,11 +1,13 @@
 ---
 name: plan
-description: Software architect agent for designing implementation plans. Use when you need an implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. Read-only.
-tools: read, grep, find, ls
+description: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. Read-only.
+disallowedTools: Edit, Write, NotebookEdit, Agent
 ---
 
-You are a software architect. You can read and search the codebase; you cannot
-modify it or run commands. You produce a plan, not an implementation.
+You are a software architect. You can read and search the codebase — including
+read-only shell commands (git log, ls, wc) — but you must never modify it: no
+edits, no writes, no state-changing commands. You produce a plan, not an
+implementation.
 
 Ground the plan in what the code actually does:
 

package/docs/guide/README.md

@@ -0,0 +1,52 @@
+# One Code user guide
+
+How to use One Code day to day: installing it, connecting model providers,
+reusing your Claude Code configuration, and driving every feature. For what
+One Code is and why it exists, see the [project README](../../README.md).
+
+## Start here
+
+If you've never run One Code, read these in order:
+
+1. [Install One Code](installation.md). Install it and open your first
+   session.
+2. [Providers and models](providers-and-models.md). Connect a provider, add
+   an API key, and switch models.
+3. [Bring your Claude Code setup](bring-your-claude-code-setup.md). Reuse
+   your `CLAUDE.md`, skills, agents, commands, plugins, hooks, and
+   permission rules unchanged.
+4. [The terminal interface](terminal-interface.md). What is on screen and
+   how to move around it.
+
+## All guides
+
+| Guide | What it covers |
+|---|---|
+| [Install One Code](installation.md) | The npm app, the pi extension, Homebrew, source installs, updating, and uninstalling. |
+| [Providers and models](providers-and-models.md) | Connecting providers, storing keys, switching models, automatic model selection for side roles, prompt tiers, and web search. |
+| [Bring your Claude Code setup](bring-your-claude-code-setup.md) | Which Claude Code files are read, which settings keys are honored, and what stays separate. |
+| [The terminal interface](terminal-interface.md) | The banner, status line, working indicator, panels, dialogs, and themes. |
+| [Configure One Code](configuration.md) | Settings-file locations, the `~/.onecode` layout, every One Code settings key, full-screen mode, and language servers. |
+| [Permissions, modes, and auto mode](permissions-modes-and-auto-mode.md) | How decisions are made, rules, modes, the approval prompt, protected paths, project trust, plan mode, auto mode, and the security model. |
+| [Hooks](hooks.md) | Supported events, the input and output contract, approval, and debugging. |
+| [Subagents and workflows](subagents-and-workflows.md) | Delegating to subagents, forks, worktrees, the live panel, `ultracode` workflows, and reasoning effort. |
+| [Skills, plugins, and MCP](skills-plugins-and-mcp.md) | Skills and their states, custom commands, plugins and marketplaces, and MCP servers. |
+| [Tools](tools.md) | Every tool the model can call, what you see when it runs, and Claude Code's names for them. |
+| [Sessions and context](sessions-and-context.md) | What the model sees, memory, compaction, the cache, recaps, and resuming sessions. |
+| [Tasks and background work](tasks-and-background-work.md) | The task list, background shells, monitors, loops, and how results reach the model. |
+| [Check your setup with doctor](doctor.md) | The report, the checkup, model presets, and the `onecode doctor` command. |
+| [Differences from Claude Code](differences-from-claude-code.md) | What is different by design, what isn't provided, and known issues. |
+| [Troubleshooting](troubleshooting.md) | Symptoms, causes, and fixes. |
+| [Command and keyboard reference](reference.md) | Every command, shortcut, flag, environment variable, and file location. |
+
+## Find a setting
+
+- [Settings files and the `~/.onecode` layout](configuration.md#where-settings-live)
+- [Every One Code settings key](configuration.md#settings-reference)
+- [Provider API keys](providers-and-models.md#store-keys-as-environment-variables)
+- [Web-search providers and fallback order](providers-and-models.md#web-search-on-providers-without-a-search-api)
+- [Subagent and classifier models](subagents-and-workflows.md#choose-the-subagent-model)
+- [Default permission mode](permissions-modes-and-auto-mode.md#choose-the-starting-mode)
+- [Auto-mode configuration keys](permissions-modes-and-auto-mode.md#configure-auto-mode)
+- [Language-server setup](configuration.md#language-server-diagnostics)
+- [Environment variables](reference.md#environment-variables)