one-code-extension 0.3.1 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # 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
@@ -13,7 +15,7 @@ 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) ·
@@ -33,7 +35,9 @@ them across, because the good part was never the logo.
 - **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.
+  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)
@@ -41,10 +45,73 @@ them across, because the good part was never the logo.
   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:
+
+```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 is untested.
+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
@@ -76,6 +143,12 @@ for connection options.
 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 on pi?** Add the extensions to your existing installation:
 
 ```bash
@@ -85,7 +158,7 @@ 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`
+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
@@ -169,7 +242,7 @@ 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.
+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.
@@ -226,8 +299,10 @@ troubleshooting, and a full reference.
 - **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.
+- **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
 
@@ -244,9 +319,12 @@ pi list
 
 ## 🧠 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.
+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
 

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).

package/docs/guide/installation.md

@@ -8,14 +8,17 @@ fits how you already work.
 | You | Install | What you get |
 |---|---|---|
 | New to this, or you want the simplest setup | `npm install -g @one-ai/one-code` | The bundled app: its own `onecode` command, a pinned version of the pi coding agent inside it, and its state kept in `~/.onecode`. It coexists with any `pi` you already have. |
+| On Windows without Node.js | `powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 \| iex"` | The bundled app, with Node.js fetched for you when the machine has none. See [Install on Windows](#install-on-windows). |
 | Already running [pi](https://github.com/earendil-works/pi) | `pi install npm:one-code-extension` | The extensions only. They run on your existing pi. One Code's own state still goes to `~/.onecode`; pi's own files stay under your pi agent directory (`~/.pi/agent`). |
 
 ## Requirements
 
 - Node.js 22.19 or later. The app refuses to start on older versions,
   because pi crashes at import time there.
-- macOS or Linux. Windows Subsystem for Linux (WSL) works the same way.
-  Native Windows is untested and unsupported.
+- macOS, Linux, or Windows. Windows Subsystem for Linux (WSL) works like
+  Linux. On native Windows, One Code takes Claude Code's shape: Git for
+  Windows is recommended but optional, and PowerShell is the primary shell
+  tool. See [Windows](windows.md) for what is verified and what isn't.
 - `git`. Optional: `rg` (ripgrep) for faster search, the GitHub CLI for the
   pull-request marker in the footer, and a language server for your
   language (see
@@ -38,6 +41,46 @@ The first run also seeds pi's settings under `~/.onecode/agent/` with the
 `onecode` theme, quiet startup, and full-screen mode. It never overrides a
 value you change later.
 
+## Install on Windows
+
+Open Windows Terminal or PowerShell and run:
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 | iex"
+```
+
+The script looks for Node.js 22.19 or later on your PATH. When there is
+none, it downloads the current Node LTS for your CPU from nodejs.org as a
+zip, checks it against nodejs.org's published checksums, unpacks it under
+`%LOCALAPPDATA%\onecode\node`, and adds that folder to your user PATH.
+Nothing is installed system-wide and no Windows installer runs. It then
+runs `npm install -g @one-ai/one-code` and makes sure the `onecode` command
+is on your PATH. Open a new terminal afterwards so it sees the PATH change.
+
+The script also tells you when `git` is missing. One Code runs without it,
+but Git for Windows gives you the branch in the footer, `/init`, worktrees,
+and a bash tool for the model next to PowerShell. Install it with
+`winget install --id Git.Git -e`, or set `ONECODE_INSTALL_GIT=1` before
+running the script to have it do that for you.
+
+If you already have Node.js 22.19 or later, the plain npm command works the
+same on Windows as anywhere else:
+
+```powershell
+npm install -g @one-ai/one-code
+```
+
+The script's knobs are environment variables, because a piped script
+cannot take parameters: `ONECODE_INSTALL_NODE=1` downloads the standalone
+Node even when one exists, `ONECODE_NODE_VERSION` pins the version it
+downloads, and `ONECODE_NO_PATH_UPDATE=1` leaves your PATH alone and prints
+what to add. Read the script before running it if you like; it is the
+`install.ps1` at the root of the repository.
+
+Windows Subsystem for Linux (WSL) is Linux: use the npm or Homebrew route
+inside the distribution. For what works on native Windows, see
+[Windows](windows.md).
+
 ## Install with Homebrew
 
 Homebrew installs Node for you, so this route has no separate Node step:
@@ -59,7 +102,7 @@ pi install npm:one-code-extension
 ```
 
 Use `pi` in place of `onecode` for every command in this guide. The
-extension is tested against pi 0.83 through 0.85 and warns at startup when
+extension is tested against pi 0.83 through 0.86 and warns at startup when
 your pi is outside that range. Full-screen mode is opt-in on your own pi;
 see [Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).
 
@@ -102,7 +145,10 @@ npm install -g @one-ai/one-code      # npm installs
 brew upgrade onecode                 # Homebrew installs
 ```
 
-Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check; `--offline` skips it too.
+A Homebrew install sees the notice a day after the npm release, because
+Homebrew refuses packages younger than that and `brew upgrade` would find
+nothing sooner. Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check;
+`--offline` skips it too.
 On your own pi, update with `pi update --extensions`.
 
 Both packages are released together with the same version number.
@@ -114,8 +160,10 @@ npm uninstall -g @one-ai/one-code    # or: brew uninstall onecode
 rm -rf ~/.onecode                    # One Code's state, including pi's under the app
 ```
 
-On your own pi, run `pi remove one-code-extension` (or remove the package
-entry from pi's settings). Removing `~/.onecode` deletes One Code's
+If the Windows script fetched Node.js for you, delete `%LOCALAPPDATA%\onecode`
+too and remove that folder from your user PATH. On your own pi, run
+`pi remove one-code-extension` (or remove the package entry from pi's
+settings). Removing `~/.onecode` deletes One Code's
 settings, approvals, plan files, and, under the bundled app, pi's sessions
 and credentials. Memory files stay in `~/.claude/projects/`, because they
 are shared with Claude Code.

package/docs/guide/permissions-modes-and-auto-mode.md

@@ -83,6 +83,18 @@ contains command substitution (`$(…)` or backticks), `eval`, `exec`, a pipe
 into an interpreter, or a base64 decode is never covered by a prefix or
 wildcard `allow` rule.
 
+### PowerShell rule patterns
+
+`PowerShell(...)` rules have the same shape and follow Claude Code's
+PowerShell matching: aliases are canonicalized on both sides
+(`PowerShell(Remove-Item:*)` catches `rm`, `del`, and `ri`), cmdlet names
+are case-insensitive, a line is split on `|`, `;`, `&&`, `||`, and newlines
+outside quotes and here-strings, an `allow` rule must cover every statement,
+and a `deny` or `ask` rule fires on any statement. A `$(…)` subexpression, a
+backtick escape, a script block, the `&`/`.` call operators,
+`Invoke-Expression`, or an encoded command keeps a wildcard `allow` from
+applying. Details in [Windows](windows.md#permission-rules).
+
 ### Add a rule during a session
 
 To add an allow rule for the current repository, run:
@@ -120,10 +132,10 @@ stops risky ones, so you're not prompted for every step.
 The current badge appears in the banner and is announced when the mode
 changes.
 
-### Cycle modes with ctrl+q
+### Cycle modes with ctrl+q (alt+m on Windows and WSL)
 
-Press **ctrl+q** to cycle through manual, accept edits, plan, and auto.
-Two modes join the cycle only under certain conditions:
+Press **ctrl+q** to cycle through manual, accept edits, plan, and auto. On
+Windows and WSL the key is **alt+m**. Two modes join the cycle only under certain conditions:
 
 - **Auto** appears only when a model that can run the classifier is
   available. With no provider connected, the cycle skips it.
@@ -134,8 +146,9 @@ flag or a settings file.
 
 Claude Code cycles modes with shift+tab. One Code can't use that key
 because pi reserves it for the reasoning-effort dial. On Windows and WSL,
-pi's own default keybindings also use ctrl+q to queue a follow-up message.
-If the two conflict there, change pi's binding in its keybindings file.
+pi's own default keybindings use ctrl+q to queue a follow-up message, so
+One Code cycles modes with alt+m there instead. The footer badge and the
+startup hints name whichever key applies on your machine.
 
 ### Choose the starting mode
 
@@ -216,7 +229,10 @@ Reads and edits are confined to the working directory by default:
   mode, and is denied in don't-ask mode.
 - Accept-edits mode approves edits only inside the working directory.
 - The harness's own session directories count as inside: the auto-memory
-  folder, the session scratchpad, persisted tool output, and the plan file.
+  folder, the session scratchpad, persisted tool output, the plan file, and
+  this project's own session transcripts (with auto mode's decision log next
+  to them), which is what `/doctor` reads. Other projects' transcripts are
+  outside, as they are for Claude Code.
 
 Paths are compared after resolving symlinks, so a symlink inside the project
 that points outside it counts as outside.
@@ -287,7 +303,7 @@ code. Only read-only tools and edits to one plan file are available.
   `plan` agent, and then write the plan.
 - You can read and edit the plan file yourself while the model works.
 
-Enter plan mode by cycling to it with **ctrl+q**, by starting with
+Enter plan mode by cycling to it with **ctrl+q** (**alt+m** on Windows and WSL), by starting with
 `--permission-mode plan`, or by asking the model to plan first (it can call
 `enter_plan_mode` itself).
 

package/docs/guide/reference.md

@@ -49,7 +49,7 @@ that explains it.
 | `/loop status`, `/loop stop` | Report or end the loop. | |
 | `/tools-deferred` | List deferred tools and whether each is loaded. | [Tools](tools.md#eager-and-deferred-tools) |
 | `/init` | Have the model write a `CLAUDE.md` for the project. | [CLAUDE.md](bring-your-claude-code-setup.md#project-instructions-claudemd) |
-| `/clear` | Start a new session (pi's `/new`). | [Sessions](sessions-and-context.md#start-over) |
+| `/clear` | Start a new session (pi's `/new`); the model is told. | [Sessions](sessions-and-context.md#start-over) |
 | `/exit` | Quit (pi's `/quit`). | |
 
 ### pi commands
@@ -85,7 +85,7 @@ These come from pi and are available in every One Code session.
 
 | Shortcut | What it does |
 |---|---|
-| **ctrl+q** | Cycle the permission mode: manual, accept edits, plan, auto. |
+| **ctrl+q** (**alt+m** on Windows and WSL) | Cycle the permission mode: manual, accept edits, plan, auto. |
 | **↓** (empty editor) | Focus the panel below the editor: background shells, then subagents, then workflows. |
 | **ctrl+x** then **ctrl+k** | Stop every running agent (in the subagent panel). |
 | **x** | Stop the selected agent, shell, or workflow (in a panel). |
@@ -175,6 +175,7 @@ The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
 | `CC_FOOTER=0` | Keep pi's footer instead of One Code's status line. |
 | `CC_TURN_DURATION=0` | Remove the post-turn timing line. |
 | `CC_RECAP=0` | Turn off the "while you were away" recap. |
+| `CC_SESSION_TITLE=0` | Turn off the automatic session title. |
 | `CC_RECAP_IDLE_MS` | Idle time before a recap, in milliseconds (default 300000). |
 | `CC_COMPACTION=0` | Use pi's compaction summary instead of Claude Code's. |
 | `CC_CLEAR_THINKING=0`, `=1` | Force the thinking-preservation request off or on for Anthropic models. Default: on for `api.anthropic.com` only. |
@@ -194,6 +195,8 @@ The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
 | `PI_CACHE_RETENTION` | pi's prompt-cache lifetime. One Code sets `long` for interactive sessions unless you set it yourself. |
 | `PI_OFFLINE=1` | Same as `--offline`. |
 | `CLAUDE_CONFIG_DIR` | Where Claude Code's user configuration is read from. |
+| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | `1` turns the `powershell` tool on (the default on Windows), `0` turns it off. Off Windows it needs a `pwsh` on PATH. See [Windows](windows.md). |
+| `CLAUDE_CODE_GIT_BASH_PATH` | The bash that drives the `bash` tool, hooks, and background shells. Also read from the `env` block of `~/.claude/settings.json`; a non-bash binary is ignored with a warning. |
 | `CLAUDE_CODE_SUBAGENT_MODEL` | Default subagent model on a Claude session. |
 | `EDITOR`, `VISUAL` | Editor used by `/memory` (and pi's **ctrl+g**). |
 | `SHELL` | Shell used for commands (default `/bin/sh`). |

package/docs/guide/sessions-and-context.md

@@ -184,6 +184,24 @@ Not restored:
 `/new`. Running background tasks are stopped and listed. The permission
 mode you chose carries over.
 
+### What the model learns about your commands
+
+As in Claude Code, a slash command you run is recorded for the model: the
+next message you send carries a short note that the command ran, wrapped in a
+caveat telling the model not to act on it. `/clear` opens the new session
+with that note, and a model switch records "Set model to …" the way Claude
+Code does. Commands that One Code cannot observe (pi's own `/compact`,
+`/settings`, `/name`) leave no note.
+
+### The session title
+
+After your first real message, One Code names the session the way Claude
+Code does: a cheap model on your provider turns the message into a short
+title (Claude Code's own naming prompt), which shows in the terminal tab as
+`One Code - <title> - <folder>` and in the session picker. A name you set
+with `/name` is never overwritten. The call's cost is included in the
+footer's total. Set `CC_SESSION_TITLE=0` to turn it off.
+
 ## Turn timing
 
 After each turn, a dim line such as `✻ Cooked for 5m 12s` reports how long

package/docs/guide/terminal-interface.md

@@ -16,7 +16,7 @@ hint line lists the keys worth knowing:
 |---|---|
 | `/hotkeys` | pi's full key list. |
 | `shift+tab` | Cycle reasoning effort. |
-| `ctrl+q` | Cycle the permission mode. |
+| `ctrl+q` (`alt+m` on Windows and WSL) | Cycle the permission mode. |
 | `ctrl+t` | Show or hide thinking blocks. |
 | `ctrl+o` | Expand a collapsed tool output. |
 | `/` | List commands. |

package/docs/guide/tools.md

@@ -53,6 +53,15 @@ notification. A background shell shows up in the shells section of the
 panel below the editor. See
 [Tasks and background work](tasks-and-background-work.md).
 
+`powershell` is Claude Code's PowerShell tool: on by default on Windows,
+where it becomes the primary shell and `bash` (Git Bash) stays alongside
+when Git for Windows is installed; off elsewhere unless
+`CLAUDE_CODE_USE_POWERSHELL_TOOL=1` and a `pwsh` is on your PATH. It has the
+same `run_in_background`, the same background panel, and its description is
+Claude Code's own, with the edition section (PowerShell 7 or Windows
+PowerShell 5.1) picked from the executable found. Permission rules use
+Claude Code's `PowerShell(...)` form. See [Windows](windows.md).
+
 Some command shapes are refused before they run, with a message that steers
 the model to a better route:
 
@@ -140,10 +149,22 @@ and the model is steered to `tool_search`.
 
 In `-p` and `--mode json` runs the process exits when the turn settles, so
 nothing can run in the background. Tools that would detach work run to
-completion instead and return the output in their result: `bash` with
-`run_in_background`, `Agent`, `monitor`, and `workflow`. Timers such as
+completion instead and return the output in their result: `bash` and
+`powershell` with `run_in_background`, `Agent`, `monitor`, and `workflow`. Timers such as
 `schedule_wakeup` and `/loop` never fire in these modes.
 
+Give a scripted run its own deadline. One Code has no idle timeout on a
+provider response, so a stream that stalls mid-reply keeps the process
+waiting indefinitely. Wrap the call in your script:
+
+```bash
+timeout 180 onecode --mode json -p "…" </dev/null
+```
+
+The `</dev/null` matters too: in `-p` mode piped standard input is read as
+part of the prompt, so a run inside a shell script that reads its own body
+from stdin would hand the rest of the script to the model.
+
 ## Claude Code tool names
 
 Claude Code's tool names are accepted in permission rules and hook
@@ -152,6 +173,7 @@ matchers, and mapped to One Code's names. Case is ignored.
 | Claude Code | One Code |
 |---|---|
 | `Bash` | `bash` |
+| `PowerShell` | `powershell` |
 | `Read`, `Write`, `Edit` | `read`, `write`, `edit` |
 | `Grep`, `Glob`, `LS` | `grep`, `find`, `ls` |
 | `NotebookEdit` | `notebook_edit` |

package/docs/guide/troubleshooting.md

@@ -46,12 +46,12 @@ on first run, so there's nothing to ask.
 
 ## Permissions
 
-**Auto mode is missing from the ctrl+q cycle.** Auto mode needs a model to
+**Auto mode is missing from the mode cycle.** Auto mode needs a model to
 run its classifier. Connect a provider.
 
-**ctrl+q does something else.** On Windows and WSL, pi's default
-keybindings also bind ctrl+q, to queue a follow-up message. Rebind one of
-them in pi's keybindings file.
+**ctrl+q queues a follow-up instead of changing the mode.** On Windows and
+WSL that is pi's own binding for ctrl+q. The mode key there is alt+m; the
+footer badge names it.
 
 **Everything prompts, even in auto mode.** Auto mode pauses after several
 blocked actions in a row and prompts you once; approving resumes it. Also
@@ -171,6 +171,16 @@ for its scrollback. Use the keys the panel's footer names (**Space** and
 `CC_FOOTER=0`, or the other toggles listed in
 [Environment variables](reference.md#environment-variables).
 
+**On Windows the model has no shell tool, or the wrong one.** With Git for
+Windows installed you get `bash` plus `powershell`; without it, `powershell`
+alone. Set `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` to hide the PowerShell tool
+or `=1` to force it on (it also works on macOS and Linux with a `pwsh` on
+PATH). A startup warning names a `CLAUDE_CODE_GIT_BASH_PATH` that was
+ignored and why. If you report a Windows problem, include the shells on your
+PATH (`where bash`, `where pwsh`, `where powershell`), the value of those two
+variables, and whether the command came through `bash` or `powershell`.
+See [Windows](windows.md).
+
 ## Getting help
 
 Report problems at the project's GitHub repository. Include the output of