one-code-extension 0.3.0 → 0.4.0

package/README.md

@@ -1,26 +1,21 @@
 # One Code
 
-**A familiar Claude Code experience, with your choice of model for every agent.**
+[![CI](https://github.com/IsuruMaduranga/one-code/actions/workflows/ci.yml/badge.svg)](https://github.com/IsuruMaduranga/one-code/actions/workflows/ci.yml)
 
-One Code brings familiar Claude Code workflows to a terminal coding agent that
-lets you choose the models. It includes subagents, plan mode, permissions,
-skills, and git worktrees. Reuse your existing Claude Code setup, keep a capable model
-in the main conversation, delegate routine work to a cheaper one, and switch
-providers during a session.
+**Claude Code with the model slot left open. The full workflow, open source, on any model or provider.**
 
-- **Bring your setup.** Reuse `CLAUDE.md`, skills, commands, subagents, hooks,
-  permission rules, and MCP configuration.
-- **Choose models per task.** The main session and its subagents can use
-  different models and providers: Anthropic, OpenAI, Gemini, OpenRouter, or
-  local models supported by [pi](https://github.com/earendil-works/pi).
-- **Keep control as work grows.** Plan before editing, isolate changes in git
-  worktrees, and follow parallel agents from a live progress panel.
+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.
 
-Built on pi. Free and open source under the MIT license. Works alongside
-Claude Code, with the bundled app's state kept in `~/.onecode`.
+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">
+  <img src="demo/onecode.gif" alt="One Code: permission modes, a mid-session model switch, an agentic edit approved by auto mode, a /btw side question, /doctor report, and a subagent in the live panel" width="820">
 </p>
 
 [User guide](docs/guide/README.md) ·
@@ -28,10 +23,95 @@ Claude Code, with the bundled app's state kept in `~/.onecode`.
 [Differences from Claude Code](docs/guide/differences-from-claude-code.md) ·
 [Command reference](docs/guide/reference.md)
 
-## Get started
+## ✨ 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. A directory with no `CLAUDE.md` falls back to its `AGENTS.md`, the
+  cross-tool convention Claude Code now reads too, so a repo written for another
+  agent works here with nothing to change.
+- **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.
+
+## 🤔 "But I can already point Claude Code at Ollama"
+
+You can:
 
-Requires **Node.js 22.19+**. Developed and verified on **macOS and Linux**;
-WSL is also supported. Native Windows is currently untested.
+```bash
+export ANTHROPIC_BASE_URL="http://localhost:11434"
+claude --model kimi-k2.7-code:cloud
+```
+
+Claude Code will happily talk to whoever picks up the phone. If one model
+behind Claude Code's interface is all you want, enjoy it.
+
+The catch: you swapped the brain and told the body nothing. Claude Code's
+prompts, caching, and side calls all assume a current Claude is on the other
+end, and that assumption doesn't come off with an environment variable.
+
+One Code started as the experiment that follows from that. My
+[Harness Engineering 101](https://isuruwijesiri.com/harness-engineering-101/)
+series argues the model is the brain and the harness is the body, and the good
+parts live in the body. So: rebuild the body from scratch on a model-neutral
+runtime and put any brain in it. This repository is that rebuild, and here's
+what it does that a base URL can't.
+
+- **One phone line.** You can rename the subagent model in Claude Code, but
+  every call, main agent, subagents, classifier, compaction, still dials the one
+  endpoint behind that URL. Mixing providers means running a routing gateway
+  and maintaining it. One Code gives each seat its own brain on its own
+  provider, natively. A frontier model in charge, DeepSeek V4 Flash running
+  twelve subagents. That's the setup this was built for.
+- **Subscriptions don't fit behind a base URL.** A gateway wants API keys. One
+  Code signs you in with the account you already pay for: Claude Pro and Max,
+  ChatGPT, GitHub Copilot, OpenRouter, Kimi, xAI, and Radius all have native
+  OAuth logins, and you can mix them in one session.
+- **Someone else's prompt.** Claude Code's prompt is about 8k characters,
+  because Claude 5 doesn't need hand-holding. Give it to a smaller model and
+  you get a stranger reading Claude's notes. One Code sizes the prompt to the
+  model in four tiers, down to playbooks and strict-schema search tools for
+  flash-class and local models. Weaker brains need more body.
+- **Cache misses, billed to you.** Anthropic caches at explicit `cache_control`
+  markers; most other providers cache on an exact prefix, and the two do not
+  line up. A gateway that translates between them silently maps the markers
+  wrong, so the cache sticks at the system prompt and never advances, or never
+  forms at all. Nothing errors. You just pay full price every turn. This is not
+  hypothetical: users report proxies where the cache-creation count is zero on
+  every turn and half the turns re-bill the whole context, and Claude Code's own
+  attribution header defeats caching behind a base URL unless you know the flag
+  to turn off. One Code speaks each provider's native API, keeps the prefix
+  byte-stable, and shows the live hit rate in the footer, because one careless
+  byte up top is a tenfold price increase.
+- **Anthropic-only parts.** Deferred tools, server-side web search, the
+  thinking block. A foreign endpoint drops them. One Code has a
+  provider-neutral version of each.
+- **Side jobs that ask for Haiku by name.** Your gateway had better know who
+  that is. One Code picks side models from your provider's own catalog, with
+  a capability floor.
+- **A knob, not a toolbox.** Claude Code isn't open source; the base URL is
+  the one knob. One Code is pi extensions all the way down, so anything
+  missing is one more extension.
+
+The base URL trick swaps the brain and hopes the body doesn't notice. One Code
+is the body that was built to notice.
+
+## 🚀 Get started
+
+You need **Node.js 22.19+**. One Code is developed and verified on macOS and
+Linux; WSL works too. Native Windows runs in Claude Code's shape (Git Bash
+optional, PowerShell tool) — see the [Windows guide](docs/guide/windows.md).
 
 ```bash
 npm install -g @one-ai/one-code
@@ -39,51 +119,56 @@ cd your-project
 onecode
 ```
 
-Inside One Code, run `/login` to connect a provider, then `/model` to choose a
-model. You can also supply a provider key through an environment variable such
-as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
+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 with an existing `CLAUDE.md` or `.claude/` setup to reuse it
-immediately. For a new project, `/init` drafts a `CLAUDE.md`.
+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.
 
-Not sure what is ready? `onecode doctor` (or `/doctor report` inside a session)
-reports which providers have credentials, which model each role will use, what
-of your Claude Code configuration was picked up, and which programs are missing;
-`/doctor` runs the full checkup, where the model repairs the findings.
+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.
 
-One Code is free; model access, usage charges, and rate limits depend on your
-provider. See [Providers and models](docs/guide/providers-and-models.md) for
-connection options.
+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.
 
 ### Other ways to install
 
 **Homebrew** installs Node for you:
 
 ```bash
-brew install isurumaduranga/one-ai/one-code
+brew install isurumaduranga/one-ai/onecode
+```
+
+**Windows** without Node.js? This fetches Node for you and installs the app:
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 | iex"
 ```
 
-**Already using pi?** Add the extensions to your existing installation:
+**Already on pi?** Add the extensions to your existing installation:
 
 ```bash
 pi install npm:one-code-extension
 ```
 
 The app package, [`@one-ai/one-code`](https://www.npmjs.com/package/@one-ai/one-code),
-bundles a pinned pi version and provides 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–0.85. Use `pi` in place of
-`onecode` for that installation.
+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.86; 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
-details.
+[installation guide](docs/guide/installation.md) for display settings and more.
 
-## Put different models to work
+## 🎛️ Put different models to work
 
 A main conversation and a repository-wide investigation do not need the same
-model. With One Code, you can keep your preferred model in charge while
-subagents use another provider for exploration, tests, or review.
+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
@@ -93,22 +178,22 @@ subagents use another provider for exploration, tests, or review.
    > 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 specify their own models, tools,
-and instructions. Use `/agents` to follow their progress and `/model` to
-change the main model as the task changes.
+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 gives you control over where you spend model capacity. Actual cost and
-quality depend on the models, task, and amount of delegated work.
+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
+## ♻️ Reuse the setup you already have
 
-One Code reads Claude Code configuration directly, without an import step.
+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 no `CLAUDE.md` exists in a directory. |
+| `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. |
@@ -116,62 +201,60 @@ One Code reads Claude Code configuration directly, without an import step.
 | 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 stores its own settings separately
-and treats `~/.claude` as read-only.
+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 these configuration and workflow surfaces. Features and
-skills that require Claude Code's own hosted or desktop services are not
-included.
+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)
 
-## Workflows that scale with the task
+## ⚙️ Workflows that scale with the task
 
 ### Subagents and git worktrees
 
 Give an investigation its own context window and bring the result back to the
-main conversation. Subagents run in the background, can receive 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`.
+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`.
 
-For parallel edits, give agents separate git worktrees. You can also move the
+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`.
 
 ### Ultracode workflows
 
-Include **`ultracode`** in a request for a broad audit, migration, or review.
-The model writes a JavaScript workflow to coordinate agents in parallel, with
+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
-active across turns.
+on across turns.
 
 Resume an interrupted run to reuse completed agent calls whose inputs still
-match. Save reusable scripts in `.claude/workflows/` to invoke them by name.
+match. Save reusable scripts in `.claude/workflows/` to call them by name.
 Optional output-token targets stop new and queued agents once reached;
-already-running agents can finish above the target.
+agents already running can finish above the target.
 
 ### Permissions and planning
 
-**Auto mode is the default.** A classifier evaluates actions that need review,
-while permission rules and deterministic checks enforce additional restrictions.
-`deny` rules take precedence over `allow` rules. Trust approval covers
-project-provided hooks, MCP servers, and allow rules.
+**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 dedicated plan file before
-you approve implementation. Use `/permissions` to inspect rules and `/auto-mode`
-to configure the classifier.
+Press **ctrl+q** (**alt+m** on Windows and WSL) 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 guarantees and the known gaps are spelled
-out in the guide.
+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
+## 🧰 Everyday tools
 
 | Capability | What you get |
 |---|---|
@@ -180,12 +263,12 @@ out in the guide.
 | 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 reduce prompt overhead. |
+| 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 takes precedence.
+`fewer-permission-prompts`. A project skill with the same name wins.
 
 For scripting and session management:
 
@@ -197,28 +280,31 @@ onecode --permission-mode plan   # start in plan mode
 ```
 
 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.
+[command reference](docs/guide/reference.md) for every command, shortcut, flag,
+and environment variable.
 
-## Documentation
+## 📚 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.
+sessions and context, background work, the doctor, differences from Claude Code,
+troubleshooting, and a full reference.
 
-## Compatibility notes
+## 💡 Good to know
 
-- **Providers:** end-to-end verification has focused on Anthropic, OpenAI,
-  and OpenRouter. Other providers are less exercised.
-- **Web search:** set `BRAVE_SEARCH_API_KEY` or `TAVILY_API_KEY` when using a
-  provider without native search. With neither key, the fallback is Exa's
-  rate-limited keyless endpoint; One Code labels its results.
-- **Native Windows:** hooks and background shells currently assume `/bin/sh`.
-  Use WSL until native Windows support is verified.
+- **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:** shells, hooks, and the PowerShell tool follow Claude
+  Code's behavior and pass on Windows CI runners, but a real Windows desktop
+  session hasn't been driven end to end yet. Expect rough edges around
+  drive-letter paths in permission rules; WSL remains the safest route.
 
-## Install from source
+## 🔧 Install from source
 
 This installs the local extensions into an existing pi installation:
 
@@ -231,6 +317,15 @@ pi install ./one-code
 pi list
 ```
 
-## License
+## 🧠 Learn the ideas behind it
+
+One Code is the production-scale companion to
+[Harness Engineering 101](https://isuruwijesiri.com/harness-engineering-101/),
+a sixteen-chapter series that builds these ideas up from first principles: what
+a coding harness actually does, why the good parts are model-independent, and
+how a ~300-line toy agent grows into the patterns you see here. The series
+points at this repository wherever it needs a grown-up example.
+
+## 📄 License
 
 [MIT](LICENSE). Contributions welcome.

package/docs/guide/README.md

@@ -6,7 +6,7 @@ One Code is and why it exists, see the [project README](../../README.md).
 
 ## Start here
 
-If you have never run One Code, read these in order:
+If you've never run One Code, read these in order:
 
 1. [Install One Code](installation.md). Install it and open your first
    session.
@@ -35,7 +35,8 @@ If you have never run One Code, read these in order:
 | [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 is not provided, and known issues. |
+| [Windows](windows.md) | Git Bash and the PowerShell tool, `PowerShell(...)` rules, hooks' `shell` field, paths, and what is verified on native Windows. |
+| [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. |
 

package/docs/guide/bring-your-claude-code-setup.md

@@ -1,7 +1,9 @@
 # Bring your Claude Code setup
 
+[← One Code user guide](README.md)
+
 One Code reads the same configuration files as Claude Code, so your
-existing setup works without changes. There is no import step and nothing
+existing setup works without changes. There's no import step and nothing
 to convert. Open a project that already has a `.claude/` directory, and One
 Code picks up each of the following as it is.
 
@@ -17,12 +19,12 @@ If a directory has no `CLAUDE.md`, One Code uses its `AGENTS.md` instead, so
 a repository that standardized on `AGENTS.md` works too. A `CLAUDE.md` takes
 precedence over an `AGENTS.md` in the same directory.
 
-To give One Code instructions that Claude Code should not read, add an
+To give One Code instructions that Claude Code shouldn't read, add an
 `ONECODE.md`. See [ONECODE.md](sessions-and-context.md#onecodemd).
 
 To generate a `CLAUDE.md` for a project that lacks one, run `/init`. It has
 the model survey the project (build, test, and lint commands, layout,
-existing AI-tool configuration), ask you about what the code cannot answer,
+existing AI-tool configuration), ask you about what the code can't answer,
 and write the file. It never overwrites an existing `CLAUDE.md` silently.
 
 ## Skills, commands, and agents
@@ -74,7 +76,7 @@ The keys One Code honors:
 | Key | Scopes | Notes |
 |---|---|---|
 | `permissions.allow`, `permissions.deny`, `permissions.ask` | All | Project allow rules need one-time approval. See [Permissions](permissions-modes-and-auto-mode.md#permission-rules). |
-| `permissions.defaultMode` | All | A project file cannot select `auto` or `bypassPermissions`. |
+| `permissions.defaultMode` | All | A project file can't select `auto` or `bypassPermissions`. |
 | `permissions.disableBypassPermissionsMode` | All | `"disable"` refuses bypass mode from any source. |
 | `autoMode.*` | User, managed | Never read from project files. See [Configure auto mode](permissions-modes-and-auto-mode.md#configure-auto-mode). |
 | `hooks` | All | Project hooks need one-time approval. See [Hooks](hooks.md). |
@@ -120,7 +122,7 @@ See [Where settings live](configuration.md#where-settings-live).
 
 ## What does not carry over
 
-Features that need Claude Code's own hosted or desktop services are not
+Features that need Claude Code's own hosted or desktop services aren't
 available. For the full list of tools, commands, and skills that are
 missing or different, see
 [Differences from Claude Code](differences-from-claude-code.md).

package/docs/guide/configuration.md

@@ -1,5 +1,7 @@
 # Configure One Code
 
+[← One Code user guide](README.md)
+
 Use this page to find the right settings file, learn what One Code stores
 and where, change the terminal appearance, and set up language-server
 diagnostics. Provider keys are covered in
@@ -36,7 +38,7 @@ atomically; a malformed file is reported rather than overwritten.
 | `PI_CODING_AGENT_DIR` | pi's agent directory. The bundled app sets it to `~/.onecode/agent`. |
 | `CLAUDE_CONFIG_DIR` | Where Claude Code's user configuration is read from (default `~/.claude`). |
 
-Setting one does not move the others.
+Setting one doesn't move the others.
 
 ## What is stored under ~/.onecode
 
@@ -123,7 +125,7 @@ Set the subagent default with `/subagent`, or apply a preset with
 ## Permission settings
 
 `/permissions` shows the mode and rules, `/allow` adds a rule, and
-`/auto-mode setup` configures the classifier. **ctrl+q** cycles modes. To
+`/auto-mode setup` configures the classifier. **ctrl+q** (**alt+m** on Windows and WSL) cycles modes. To
 start a session in a given mode:
 
 ```bash
@@ -142,7 +144,7 @@ be installed and on the `PATH` used to launch One Code.
 
 | Language | Server | Install |
 |---|---|---|
-| TypeScript, JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` |
+| TypeScript, JavaScript | `typescript-language-server` | `npm install -g typescript-language-server`, plus `npm install -D typescript@5` in the project (the server reads the project's TypeScript and never a global one; TypeScript 7 no longer ships the `tsserver.js` it needs) |
 | Python | `pyright-langserver` | `npm install -g pyright` |
 | Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
 | Rust | `rust-analyzer` | `rustup component add rust-analyzer` |
@@ -154,7 +156,7 @@ its files, from the nearest directory that has a project marker such as
 server that crashes is restarted twice, then disabled for the session.
 
 If the project's TypeScript installation lacks `lib/tsserver.js`
-(TypeScript 7's native compiler), the server cannot start; One Code
+(TypeScript 7's native compiler), the server can't start; One Code
 reports this. Install a TypeScript 5.x development dependency in that
 project.
 
@@ -163,7 +165,7 @@ precedence over the built-in table for the file extensions it claims.
 
 Run `/lsp` to see each server's status and diagnostic count, start
 failures, and plugin configuration problems. `/doctor report` lists the
-servers your project needs and whether they are installed.
+servers your project needs and whether they're installed.
 
 ## Environment variables
 

package/docs/guide/differences-from-claude-code.md

@@ -1,8 +1,10 @@
 # Differences from Claude Code
 
+[← One Code user guide](README.md)
+
 One Code recreates Claude Code's workflow on the pi agent harness with your
 choice of model. Most of what you know carries over. This page lists what
-is deliberately different, what is not provided, and the known limitations,
+is deliberately different, what isn't provided, and the known limitations,
 so nothing surprises you.
 
 ## What is the same
@@ -26,7 +28,7 @@ so nothing surprises you.
 |---|---|---|
 | Models | Anthropic models. | Any provider pi supports, switchable mid-session, with a different model per role. |
 | Tool names on the wire | PascalCase (`Read`, `Bash`). | snake_case (`read`, `bash`); `Agent` and `SendMessage` keep their names. Claude Code names still work in rules and hook matchers. |
-| Permission-mode key | shift+tab. | ctrl+q. pi reserves shift+tab for the reasoning-effort dial. |
+| Permission-mode key | shift+tab. | ctrl+q; alt+m on Windows and WSL. pi reserves shift+tab for the reasoning-effort dial and, on Windows, ctrl+q for queuing a follow-up. |
 | Task-list key | ctrl+t. | `/tasks show` and `/tasks hide`. pi reserves ctrl+t for thinking blocks. |
 | Deleting files in auto mode | The whole project directory is trusted. | A delete is approved only when git can recover the file; otherwise the classifier decides. |
 | Bypass mode | Protected paths stay protected. | Bypass mode bypasses everything, including protected paths. |
@@ -46,9 +48,9 @@ have no equivalent here: `Artifact`, `ReportFindings`,
 `ShareOnboardingGuide`, `PushNotification`, `RemoteTrigger`, `DesignSync`,
 `CronCreate`, `CronList`, `CronDelete`, `EndConversation`, and
 `SendFeedback`. Scheduling within a session is available through `/loop`
-and `schedule_wakeup`; scheduled cloud sessions are not.
+and `schedule_wakeup`; scheduled cloud sessions aren't.
 
-The `Agent` tool's remote isolation option is not implemented.
+The `Agent` tool's remote isolation option isn't implemented.
 
 ## Commands that are not provided
 
@@ -81,17 +83,17 @@ action but never pre-approve one. See [Hooks](hooks.md).
 
 ## Settings keys that are ignored
 
-`permissions.additionalDirectories` is not honored. The `env` block is read
+`permissions.additionalDirectories` isn't honored. The `env` block is read
 only for `CLAUDE_CODE_SUBAGENT_MODEL`, and only from user and managed
 scope. `includeCoAuthoredBy`, `apiKeyHelper`, `forceLoginMethod`,
-`cleanupPeriodDays`, and `spinnerTipsEnabled` are not read. Run
+`cleanupPeriodDays`, and `spinnerTipsEnabled` aren't read. Run
 `/doctor report` to see, per file, which keys were used, ignored, or
 refused.
 
 ## Prompt layout on Anthropic models
 
 Claude Code delivers part of its reminder stack to Opus and Sonnet as a
-system-role message after the first user message. pi's message model cannot
+system-role message after the first user message. pi's message model can't
 express that, so One Code uses the layout Claude Code uses for Haiku on
 every model. The content is the same; only the placement differs.
 
@@ -99,9 +101,18 @@ every model. The content is the same; only the placement differs.
 
 - **macOS and Linux** are developed and verified. **WSL** works the same
   way.
-- **Native Windows** is untested and unsupported. Hooks run through
-  `/bin/sh`, background shells fall back to it when `SHELL` is unset, and
-  no PowerShell tool exists. Use WSL.
+- **Native Windows** follows Claude Code's shape: Git for Windows is
+  optional, PowerShell is the primary shell tool when it is enabled (on by
+  default on Windows, `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` turns it off), and
+  your `PowerShell(...)` rules, `CLAUDE_CODE_GIT_BASH_PATH`, and per-hook
+  `shell` field work unchanged. The PowerShell tool's description is Claude
+  Code's own text. What differs: One Code has no PowerShell command parser
+  yet, so in auto mode every PowerShell command that isn't on Claude Code's
+  read-only cmdlet list goes to the classifier (Claude Code auto-approves
+  more in-project work), and the git-recoverability shortcut for in-project
+  deletes is bash-only. Verified on CI runners and through a `pwsh` on
+  macOS; a real Windows desktop has not been driven end to end yet. See
+  [Windows](windows.md).
 
 ## Provider notes
 
@@ -110,7 +121,7 @@ every model. The content is the same; only the placement differs.
 - Some models reject options that others accept. One Code sends minimal
   options to its side calls (classifier, recap, reader) for this reason. A
   provider incompatibility in a side call fails closed: a classifier that
-  cannot answer blocks the action.
+  can't answer blocks the action.
 - Prompt-cache lifetime and pricing are the provider's. The extended
   one-hour cache applies to Anthropic; other providers use their own
   values.
@@ -119,7 +130,7 @@ every model. The content is the same; only the placement differs.
 
 - A write or edit tool can reach a file that only a `Bash` deny rule
   protects, because in-project writes take the deterministic fast path in
-  auto mode and are not classified. Write `deny` rules for the write tools
+  auto mode and aren't classified. Write `deny` rules for the write tools
   as well. This is documented and accepted rather than fixed.
 - GLM-5.3 and GLM-5.3 Flash, used as the classifier, approve a request to
   back up the project to an unnamed outside location that the ruleset says
@@ -127,7 +138,7 @@ every model. The content is the same; only the placement differs.
 - Running a skill in a one-shot run (`-p '/simplify'`) delivers the skill
   but starts no model turn, so the process exits without doing anything.
   Interactive sessions are unaffected.
-- The reasoning effort set with `/effort` does not persist across
+- The reasoning effort set with `/effort` doesn't persist across
   restarts; the model chosen with `/model` does. To save a level, open
   pi's `/thinking` picker and press **ctrl+s**, or pass `--thinking`.
 - A subagent spawn that is blocked before it starts can leave its requested
@@ -145,6 +156,6 @@ every model. The content is the same; only the placement differs.
   has had limited live testing.
 - Plugin marketplaces support git and local sources only; npm and pip
   sources, version pinning, dependency resolution, and enterprise
-  blocklists are not implemented.
+  blocklists aren't implemented.
 
 Open work is tracked in the project's issue tracker on GitHub.