one-code-extension 0.3.1 → 0.4.1

package/README.md

@@ -1,50 +1,37 @@
 # One Code
 
+[![CI](https://github.com/IsuruMaduranga/one-code/actions/workflows/ci.yml/badge.svg)](https://github.com/IsuruMaduranga/one-code/actions/workflows/ci.yml)
+
 **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.
+One Code rebuilds the Claude Code workflow around the model you choose.
+Subagents, Git worktrees, auto mode, plan mode, permissions, and context
+management all live in the harness, so they come along whatever model you
+put in it. Your `CLAUDE.md`, skills, commands, agents, and permission rules
+carry over with no import step.
+
+If you already use Claude Code, nothing here needs relearning. Pick a model,
+give it a task, review its plan, and let it work. Switch models mid-session,
+or give each subagent its own model and provider: a frontier model on the
+main task, a cheaper one for exploration and tests.
 
-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.
+One Code is an independent, open-source implementation built on
+[pi](https://github.com/earendil-works/pi). It recreates the coding workflow;
+features that depend on Claude Code's hosted or desktop services are outside
+its scope.
 
 <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 terminal showing permission modes, a model switch, an approved edit, a side question, diagnostics, and a running subagent" width="820">
 </p>
 
 [User guide](docs/guide/README.md) ·
-[Bring your Claude Code setup](docs/guide/bring-your-claude-code-setup.md) ·
+[Reuse 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.
+Install **Node.js 22.19 or later**, then run:
 
 ```bash
 npm install -g @one-ai/one-code
@@ -52,186 +39,262 @@ 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
+Inside One Code, run `/login` to connect a provider, then `/model` to choose a
+model. You can also supply an API 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.
+One Code reads an existing `CLAUDE.md` and `.claude/` configuration directly.
+If a directory has no `CLAUDE.md`, it falls back to `AGENTS.md`. For a new
+project, run `/init` to draft a `CLAUDE.md`.
 
-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.
+To check your setup, run `onecode doctor` or `/doctor report` inside a session.
+The report lists provider credentials, model assignments, detected configuration,
+and missing programs. Run `/doctor` for a checkup with agent-assisted fixes.
 
-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 Code is developed on macOS and verified on macOS, Linux, and Windows.
+WSL works too. For the native Windows setup and what has been checked there,
+see the [Windows guide](docs/guide/windows.md).
 
-### Other ways to install
+One Code is free under the MIT license. Model access, usage charges, and rate
+limits depend on your provider. See
+[Providers and models](docs/guide/providers-and-models.md) for connection options.
 
-**Homebrew** installs Node for you:
+### Other installation options
+
+**Homebrew**, which installs Node.js for you:
 
 ```bash
 brew install isurumaduranga/one-ai/onecode
 ```
 
-**Already on pi?** Add the extensions to your existing installation:
+**Windows installer**, which installs Node.js and One Code:
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 | iex"
+```
+
+**Existing pi 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 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 [`@one-ai/one-code`](https://www.npmjs.com/package/@one-ai/one-code)
+app package bundles a pinned version of pi and provides the `onecode` command.
+The [`one-code-extension`](https://www.npmjs.com/package/one-code-extension)
+package uses your existing pi installation and is tested against pi versions
+0.83 through 0.86. For the extension package, use `pi` in place of `onecode`.
 
 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.
+[installation guide](docs/guide/installation.md) for display settings and more
+installation details.
+
+## ✨ Why One Code?
+
+- **Choose models by task.** Use Anthropic, OpenAI, Gemini, OpenRouter, or a
+  local model. Switch the main model mid-session with `/model`.
+- **Mix providers in one session.** Give the main agent and each subagent
+  their own model and provider, without configuring a routing gateway.
+- **Reuse your Claude Code configuration.** One Code reads project
+  instructions, skills, commands, agents, plugins, permission rules, and
+  Model Context Protocol (MCP) server configuration. There is no import step.
+- **Adapt guidance to the model.** Four capability tiers adjust prompting
+  and tool guidance, with more explicit instructions for smaller models.
+- **Extend the harness.** One Code is a
+  [pi](https://github.com/earendil-works/pi) package built from extensions.
+  Add your own extensions, themes, and settings.
+- **Inspect and change the code.** The project is open source under the
+  [MIT license](LICENSE).
+
+## 🤔 Why not use Claude Code with a URL override?
+
+You can point Claude Code at another endpoint with `ANTHROPIC_BASE_URL`.
+If that endpoint supports the API Claude Code expects, this can be enough
+to use an alternative model in a familiar interface.
+
+The override changes where requests go. It does not, by itself, adapt the
+prompts, provider features, authentication, or supporting model calls to
+the model receiving them. Your endpoint or gateway has to bridge those gaps.
+
+One Code builds that adaptation into the harness:
+
+- **Different providers for different agents.** A URL override points
+  requests at one endpoint. To route those requests across providers, you
+  need a gateway. One Code connects each agent to its own provider directly.
+  The main agent can use a frontier model while subagents use a cheaper
+  model elsewhere.
+- **Prompts matched to the model.** Changing the endpoint does not change
+  the instructions sent to the model. One Code uses four capability tiers
+  to adjust prompting and tool guidance. Smaller and local models receive
+  more explicit playbooks and structured search tools.
+- **Native caching support.** Providers use different caching mechanisms.
+  An API-compatible response alone does not establish that a gateway
+  preserves caching behavior. One Code uses native provider integrations,
+  keeps prompt prefixes stable, and shows the cache hit rate in the footer.
+- **Account sign-ins as well as API keys.** Changing a URL does not add
+  a provider's sign-in flow. One Code signs in with the accounts you
+  already have (Claude Pro and Max, ChatGPT, GitHub Copilot, OpenRouter,
+  Kimi, xAI, and Radius), and you can mix them with API-key connections in
+  the same session.
+- **Tools and supporting calls that account for the provider.** Web search,
+  deferred tools, reasoning, and background model calls need more than an
+  endpoint change. One Code provides shared tool interfaces and selects
+  supporting models from the provider's catalog, subject to capability
+  requirements.
+- **An open harness you can change.** One Code's prompts, tools, and
+  workflows are implemented as pi extensions. You can inspect them,
+  change their behavior, and add your own.
+
+Use a URL override when one compatible endpoint covers your needs. Use
+One Code when you want the Claude Code workflow with model choice built
+into the prompts, tools, authentication, and agent coordination.
+
+See [Differences from Claude Code](docs/guide/differences-from-claude-code.md)
+for the full comparison and compatibility boundaries.
+
+## 🎛️ Use different models in one session
+
+Keep your preferred model on the main task and delegate exploration, tests,
+or review to another model or provider.
 
 1. Choose the main model with `/model`.
-2. Set the default for subagents and workflow agents with
+2. Set the default model for subagents and workflow agents with
    `/subagent <provider/model-id>`.
-3. Ask for delegated work, for example:
+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.
+Agent definitions in `.claude/agents/` can specify 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.
+Cost and output quality depend on the models, the task, and how much work
+you delegate. See [Subagents and workflows](docs/guide/subagents-and-workflows.md)
+for configuration details.
 
-[Subagents and workflows →](docs/guide/subagents-and-workflows.md)
+## ♻️ Reuse your Claude Code setup
 
-## ♻️ Reuse the setup you already have
+One Code reads Claude Code configuration directly and keeps its own settings
+separately. It treats `~/.claude` as read-only, with one deliberate exception:
+per-repository memory is written to Claude Code's own memory folder, so both
+tools share it.
 
-One Code reads Claude Code configuration directly. There is no import step.
-
-| Your configuration | How One Code uses it |
+| 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/agents/` | Subagent definitions with model, tool, and instruction settings. |
 | `.claude/settings.json` | `allow`, `deny`, and `ask` permission rules, plus supported command hooks. |
-| `.mcp.json` | MCP servers with tools loaded on demand. |
+| `.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.
+permission rules and hook matchers.
+
+Compatibility covers configuration and workflows. Features and skills that
+depend on Claude Code's 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.
+See [Configuration compatibility](docs/guide/bring-your-claude-code-setup.md)
+and [Skills, plugins, and MCP](docs/guide/skills-plugins-and-mcp.md).
 
-[Configuration details →](docs/guide/bring-your-claude-code-setup.md) ·
-[Skills, plugins, and MCP →](docs/guide/skills-plugins-and-mcp.md)
+## ⚙️ Plan and delegate work
 
-## ⚙️ Workflows that scale with the task
+### Subagents and Git worktrees
 
-### Subagents and git worktrees
+Give an investigation its own context window and bring the results back to
+the main conversation. Subagents run in the background, accept follow-up
+messages, and can fork the conversation when they need its context.
 
-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`.
+One Code includes three agent definitions: `general-purpose`, `explore`,
+and `plan`.
 
-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
+For parallel edits, give agents separate Git worktrees. You can also move
+the whole session into a worktree with `enter_worktree` and leave it with
 `exit_worktree`.
 
 ### 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.
+Include **`ultracode`** in a request for a broad audit, migration, or review.
+The model writes a JavaScript workflow to coordinate agents in parallel.
+Follow progress in `/workflows`, or use `/effort ultracode` to keep this
+behavior enabled across turns.
+
+When you resume an interrupted run, completed agent calls can be reused if
+their inputs still match. Save reusable scripts in `.claude/workflows/` to
+call them by name.
 
-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.
+Optional output-token targets stop new and queued agents when the target
+is 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.
+**Auto mode is the default.** A classifier evaluates actions that need
+review, while permission rules and deterministic checks enforce the remaining
+controls. `deny` rules take precedence over `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.
+Project-provided hooks, MCP servers, and allow rules require trust approval.
 
-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.
+Press **ctrl+q**, or **alt+m** on Windows and WSL, to cycle through manual,
+accept-edits, plan, and auto modes. In plan mode, the agent investigates and
+writes a plan file before you approve implementation.
 
-[Permissions and modes →](docs/guide/permissions-modes-and-auto-mode.md) ·
-[Hooks →](docs/guide/hooks.md)
+Use `/permissions` to inspect rules and `/auto-mode` to configure the
+classifier.
+
+The permission system provides application-level controls. For operating
+system isolation, run One Code inside a container. See
+[Permissions and modes](docs/guide/permissions-modes-and-auto-mode.md) for
+guarantees and known limitations, and [Hooks](docs/guide/hooks.md) for
+hook configuration.
 
 ## 🧰 Everyday tools
 
-| Capability | What you get |
+| Capability | Included features |
 |---|---|
-| 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`. |
+| Code and files | File reading, writing, and editing; shell commands; background processes; repository search; and notebook editing. |
+| Web | Search and fetch, using 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. |
+| Tool discovery | Tools loaded on demand to reduce prompt overhead. |
+| Reasoning and appearance | `/effort` or **shift+tab** to set reasoning effort; `onecode` and `onecode-light` themes. |
+| Customization | 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.
+Bundled skills include `simplify`, `code-review`, `security-review`, and
+`fewer-permission-prompts`. A project skill with the same name takes precedence.
 
 For scripting and session management:
 
 ```bash
 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
+onecode -c                       # Continue the previous session.
+onecode --mode json              # Output JSON events.
+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.
-
-## 📚 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
-
-- **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.
+See [Tools](docs/guide/tools.md) for available tools and the
+[command reference](docs/guide/reference.md) for commands, shortcuts, flags,
+and environment variables.
+
+## 💡 Platform and provider notes
+
+- **Provider coverage:** End-to-end testing focuses on Anthropic, OpenAI,
+  and OpenRouter. Other providers have less test coverage.
+- **Web search:** For providers without native search, set
+  `BRAVE_SEARCH_API_KEY` or `TAVILY_API_KEY`. Without either key, One Code
+  falls back to Exa's rate-limited keyless endpoint and labels those results.
+- **Native Windows:** The shells, hooks, and the PowerShell tool follow
+  Claude Code's behavior. They pass on the Windows CI runner, where a real
+  model drives both shell tools, and they have been checked by hand on a
+  Windows Server 2025 machine: the interface in Windows Terminal, permission
+  prompts, plan mode, the PowerShell tool, background shells, and `/doctor`.
+  Windows 10 and 11 desktops have had less time in the field, so report what
+  you hit. WSL remains the longest-tested route.
 
 ## 🔧 Install from source
 
-This installs the local extensions into an existing pi installation:
+To install the local extensions into an existing pi installation, run:
 
 ```bash
 git clone https://github.com/IsuruMaduranga/one-code
@@ -242,12 +305,16 @@ pi install ./one-code
 pi list
 ```
 
-## 🧠 Learn the ideas behind it
+## 📚 Documentation and background
+
+The [user guide](docs/guide/README.md) covers setup, configuration, providers,
+permissions, workflows, tools, session management, and troubleshooting.
 
-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.
+For the ideas behind the project, read
+[Harness Engineering 101](https://isuruwijesiri.com/harness-engineering-101/).
+The sixteen-chapter series starts with a small coding agent and develops the
+harness patterns used in One Code, with examples from this repository.
 
 ## 📄 License
 
-[MIT](LICENSE). Contributions welcome.
+[MIT](LICENSE). Contributions are welcome.

package/docs/guide/README.md

@@ -35,6 +35,7 @@ If you've 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. |
+| [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/configuration.md

@@ -125,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
@@ -144,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` |

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

@@ -28,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. |
@@ -101,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
 

package/docs/guide/hooks.md

@@ -107,5 +107,17 @@ Set `CC_HOOKS_DEBUG=1` before launching to print each hook dispatch and its
 outcome to stderr. Decisions are also appended to
 `~/.onecode/hooks/hooks-decisions.jsonl` while the variable is set.
 
-Hooks run through `/bin/sh`. On native Windows this path doesn't exist,
-which is one reason native Windows is unsupported; use WSL.
+## Which shell runs a hook
+
+Hooks run in bash, as in Claude Code: `/bin/bash` on macOS and Linux, Git
+Bash on Windows (`CLAUDE_CODE_GIT_BASH_PATH` points at a different bash;
+a value that isn't a bash or sh binary is ignored with a warning). A hook
+can ask for PowerShell instead with Claude Code's `shell` field:
+
+```json
+{ "type": "command", "command": "Get-Content $env:TEMP\\hook.log", "shell": "powershell" }
+```
+
+On a Windows machine without Git for Windows, hooks default to PowerShell.
+Matchers accept `Bash|PowerShell` and `Bash,PowerShell` to cover both shell
+tools. See [Windows](windows.md).