one-code-extension 0.1.3 → 0.3.0

package/docs/guide/providers-and-models.md

@@ -0,0 +1,194 @@
+# Providers and models
+
+One Code talks to each model provider natively, so you choose the provider
+and the model, and you can change either one during a session. This page
+covers connecting a provider, storing a key, switching models, how One Code
+picks models for its side roles, and web search on providers without a
+search API.
+
+## Connect your first provider
+
+You need one provider API key to start. On the first run there is no
+provider yet, so the banner shows `model none` and points you at `/login`.
+Start One Code and run `/login` to pick a provider and paste a key, or sign
+in through the browser where the provider supports it:
+
+```bash
+cd your-project
+onecode
+# then, inside One Code:
+/login
+```
+
+Alternatively, set the provider's key as an environment variable before
+launching. One Code picks it up and no `/login` is needed.
+
+Two providers hand out free models you can try at no cost:
+
+- **OpenCode Zen** ([opencode.ai/zen](https://opencode.ai/zen)): sign up and
+  copy your API key. A free model is `deepseek-v4-flash-free`.
+- **OpenRouter** ([openrouter.ai](https://openrouter.ai)): sign up and create
+  a key, or sign in from inside One Code with no key copying. Free models
+  carry a `:free` suffix, such as `nvidia/nemotron-3-ultra-550b-a55b:free`.
+
+Credentials are stored by pi in its agent directory (`~/.onecode/agent/`
+under the bundled app). `/logout` removes them.
+
+## Store keys as environment variables
+
+pi reads provider keys from the environment, so you can set them once:
+
+| Provider | Environment variable |
+|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Google | `GEMINI_API_KEY` |
+| OpenCode Zen | `OPENCODE_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+
+Other providers pi supports follow the same pattern; see pi's provider
+documentation for the full list.
+
+## Switch models
+
+Run `/model` to see the models available from your connected providers and
+pick one, or pass `--model provider/model-id` at launch. **ctrl+p** cycles
+through models. The switch takes effect on your next message, so you can
+start a task on one model and finish it on another.
+
+Every interactive `/model` choice is saved as pi's default, so the next
+session starts on the same model. A `--model` flag wins for that session
+without changing the saved default.
+
+Changing the model re-caches the conversation, so the next request costs
+more than usual.
+
+## Run a cheap model with a frontier model
+
+Because each provider is native, different parts of the same session can
+run on different models:
+
+- **Switch as the task changes.** Use `/model` to move between a cheap model
+  for routine work and a stronger one for the hard parts.
+- **A cheaper subagent tier.** Subagents, workflow agents, the auto-mode
+  classifier, and the reader model behind web fetch and recaps all run on
+  their own model. By default One Code picks these for you; see the next
+  section. `/subagent` and `/auto-mode model` set them by hand.
+
+This matters most for `ultracode` workflows, which fan work out across many
+agents at once. Running those agents on a cheap tier keeps a large fan-out
+affordable while the parent session stays on a frontier model.
+
+## Automatic model selection
+
+For its side roles, One Code chooses a model from the **same provider** as
+your session; automatic picks never send your data to another provider. The
+choice is the cheapest model that clears a capability floor:
+
+- **Subagents and the classifier** share one rule: a Sonnet-class model when
+  your session runs a Sonnet-class or stronger model, and a Haiku-class model
+  otherwise. This is Claude Code's classifier rule, applied to delegated work
+  too, so on most providers both roles land on the same model. A subagent is
+  never dearer than your main model; if nothing cheaper qualifies, it runs on
+  the main model.
+- **The reader** (web fetch answers, recaps) uses the cheapest capable
+  model.
+
+Claude Code's model aliases work everywhere: `sonnet`, `haiku`, `opus` and
+`fable` resolve to a model of that name when your provider has one, and
+otherwise to the matching class within your provider (`haiku` the cheapest
+capable model, `sonnet` the cheapest Sonnet-class model, `opus` and `fable`
+your main model). They never switch providers.
+
+Capability is judged by tier (see the next section). Models are excluded
+when they cannot call tools, have no price, or are a generation behind: a
+model released more than a year after its vendor's newest is demoted one
+tier, and one more than two years behind is never picked automatically.
+Provider aliases such as `:free` or `:online` variants are skipped.
+
+### Measured selection with Artificial Analysis
+
+If you have an [Artificial Analysis](https://artificialanalysis.ai) API key,
+One Code uses measured coding ability instead of name-based tiers for these
+picks: a candidate must score at least the lower of your session model's
+coding index and a Sonnet 5 reference (the reader gets 10 percent
+tolerance; subagents and the classifier get none). The score can also move
+a model to a more scaffolded prompt: a model whose coding index is below 85
+percent of the Sonnet 5 reference gets at most the cheap register, and one
+below 60 percent at most the tiny register. A score never moves a model to
+a leaner register than its name class allows. Models sold under several
+providers share one release date for this purpose, so a Codex or Azure
+listing is scored like its OpenAI twin. Set `AA_API_KEY`, or add the key to `~/.onecode/settings.json`:
+
+```json
+{
+  "capabilityIndex": {
+    "artificialAnalysisApiKey": "…"
+  }
+}
+```
+
+The snapshot is cached under `~/.onecode/cache/` and refreshed at most once
+a day. Without a key, selection uses tiers alone. The measured index never
+changes the prompt tier itself.
+
+`/doctor report` shows the model each role gets and why, and `/doctor
+presets` offers three coordinated presets; see
+[Model presets](doctor.md#model-presets).
+
+## Prompting adapts to the model
+
+One Code classifies every model into one of four prompt tiers and adjusts
+the system prompt to match:
+
+| Tier | Models | Prompt |
+|---|---|---|
+| Frontier | Opus and Fable, current generation. | Claude Code's terse prompt. |
+| Workhorse | Sonnet-class models and comparable third-party models. | Claude Code's full prompt. |
+| Cheap | Haiku-class models and comparable "flash", "mini", or "small" models. | The verbose prompt Claude Code gives Haiku. |
+| Tiny | Sub-Haiku models. | The verbose prompt plus extra scaffolding and the `grep`, `find`, and `ls` tools. |
+
+The tier is derived from the model's name, release date, and price. You do
+not configure it; set `CC_PROMPT_TIER` to force one when you want to
+experiment. `/doctor report` shows the tier in use.
+
+## Web search on providers without a search API
+
+Web search uses your provider's own search when it has one (Anthropic,
+OpenAI, Gemini, xAI). On any other provider (OpenRouter, Z.ai, Ollama,
+DeepSeek direct, and the rest) One Code falls back to a third-party search
+API, in this order:
+
+1. **Brave Search**, when `BRAVE_SEARCH_API_KEY` is set.
+2. **Tavily**, when `TAVILY_API_KEY` is set.
+3. **Exa's free keyless endpoint**, when neither key is set. It is
+   rate-limited and best-effort, so One Code warns you the first time a
+   session uses it and labels every result that came from it.
+
+Both Brave and Tavily have free tiers. If you would rather not use
+environment variables, put the keys in `~/.onecode/settings.json`:
+
+```json
+{
+  "webSearch": {
+    "apiKeys": { "brave": "…", "tavily": "…" },
+    "order": ["tavily", "brave", "exa-free"]
+  }
+}
+```
+
+`order` is optional. A backend that fails is skipped and the result says
+so. Web fetch works on every provider; it never depends on a search API.
+
+## Provider notes
+
+- Verification has focused on Anthropic, OpenAI, and OpenRouter. Other
+  providers are less exercised.
+- Some models reject request options others accept (a temperature, a
+  reasoning setting). One Code sends minimal options to its side calls for
+  this reason, and a side call that still fails does so loudly: a
+  classifier that cannot answer blocks the action; a reader that fails
+  returns the raw page.
+- Interactive sessions request the provider's extended prompt cache (one
+  hour on Anthropic). Subagents and one-shot runs use the short default.
+  See [The prompt cache](sessions-and-context.md#the-prompt-cache).

package/docs/guide/reference.md

@@ -0,0 +1,224 @@
+# Command and keyboard reference
+
+A lookup for every slash command, keyboard shortcut, command-line flag,
+environment variable, and file location. Each entry points to the page
+that explains it.
+
+## Slash commands
+
+### One Code commands
+
+| Command | What it does | Page |
+|---|---|---|
+| `/doctor` | Run the checkup: the model reviews the measured setup report and proposes repairs. | [Doctor](doctor.md) |
+| `/doctor report` | Show the report alone in a scrollable panel. | [Doctor](doctor.md) |
+| `/doctor presets` | Show the three model presets and what each would pick. | [Doctor](doctor.md#model-presets) |
+| `/doctor preset <economical\|balanced\|quality>` | Apply a preset. | [Doctor](doctor.md#model-presets) |
+| `/agents` | Open the live subagent panel, or list the available agents. | [Subagents](subagents-and-workflows.md) |
+| `/subagent <provider/model-id>` | Save the default model for subagents and workflow agents. | [Subagents](subagents-and-workflows.md#choose-the-subagent-model) |
+| `/subagent inherit` | Use the main model for subagents. | |
+| `/subagent status` | Show the configured default and what it resolves to. | |
+| `/subagent clear` | Return to automatic selection. | |
+| `/subagent` | Open a model picker. | |
+| `/workflows` | Open the workflow run viewer. | [Workflows](subagents-and-workflows.md#the-run-viewer) |
+| `/workflows stop <runId>` | Stop a running workflow. | |
+| `/workflows log <runId>` | Print a run's recent events. | |
+| `/workflows list` | List this session's runs and the saved workflows. | |
+| `/effort [level]` | Set the reasoning effort (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultracode`), or open the slider. | [Reasoning effort](subagents-and-workflows.md#reasoning-effort) |
+| `/skills` | Manage which skills the model sees. | [Skills](skills-plugins-and-mcp.md#manage-skills) |
+| `/<skill-name> [args]` | Run a skill. | [Skills](skills-plugins-and-mcp.md#skills) |
+| `/skill:<name>`, `/skill:<plugin>:<name>` | Run a skill by its full name. | |
+| `/<command-name> [args]` | Run a custom command from `.claude/commands/`. | [Custom commands](skills-plugins-and-mcp.md#custom-commands) |
+| `/<plugin>:<command>` | Run a plugin command. | |
+| `/plugins` | Browse, install, and toggle plugins and marketplaces. | [Plugins](skills-plugins-and-mcp.md#plugins) |
+| `/mcp` | Manage MCP servers: status, reconnect, authenticate, enable, disable. | [MCP servers](skills-plugins-and-mcp.md#manage-servers) |
+| `/lsp` | Show language-server status. | [Language servers](configuration.md#language-server-diagnostics) |
+| `/permissions` | Show the permission mode and every loaded rule. | [Permissions](permissions-modes-and-auto-mode.md) |
+| `/allow <rule> [global]` | Save an allow rule for this repository, or for every repository with `global`. | [Add a rule](permissions-modes-and-auto-mode.md#add-a-rule-during-a-session) |
+| `/auto-mode`, `/auto-mode config` | Show the effective auto-mode configuration. | [Auto mode](permissions-modes-and-auto-mode.md#configure-auto-mode) |
+| `/auto-mode setup` | Draft and save an auto-mode configuration for this environment. | |
+| `/auto-mode defaults` | Show the built-in environment description. | |
+| `/auto-mode model [provider/model-id\|clear]` | Choose or clear the classifier model. | |
+| `/memory` | Open an instruction file or the memory folder. | [Memory](sessions-and-context.md#memory) |
+| `/tasks`, `/tasks hide`, `/tasks show` | Print the task list, or hide and show its widget. | [Tasks](tasks-and-background-work.md#the-task-list) |
+| `/background` | List background tasks. | [Background](tasks-and-background-work.md#the-background-list) |
+| `/loop <interval> <task>` | Repeat a task at a fixed interval (`30s`, `5m`, `1h`). | [Loops](tasks-and-background-work.md#scheduled-wake-ups-and-loops) |
+| `/loop <task>` | Repeat a task, letting the model choose the pace. | |
+| `/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) |
+| `/exit` | Quit (pi's `/quit`). | |
+
+### pi commands
+
+These come from pi and are available in every One Code session.
+
+| Command | What it does |
+|---|---|
+| `/login`, `/logout` | Add or remove provider credentials. |
+| `/model` | Switch the model. **ctrl+s** in the picker saves it as the startup default. |
+| `/thinking` | Switch the thinking level. **ctrl+s** in the picker saves it as the startup default. Covers the same dial as `/effort`. |
+| `/scoped-models` | Choose which models **ctrl+p** cycles through. |
+| `/settings` | pi's preferences: theme, message delivery, and more. |
+| `/compact [instructions]` | Compact the context now. |
+| `/resume` | Pick a previous session. |
+| `/new` | Start a new session. |
+| `/name <name>` | Name the session. |
+| `/session` | Show the session file, id, message count, tokens, and cost. |
+| `/tree` | Jump to any point in the session and continue from there. |
+| `/fork`, `/clone` | Copy the session from a message, or duplicate the current branch. |
+| `/trust` | Save the project trust decision for pi's own project resources. |
+| `/copy` | Copy the last reply to the clipboard. |
+| `/export [file]`, `/import <file>` | Export the session to HTML or JSONL; import a JSONL session. |
+| `/share` | Upload the session as a private GitHub gist. |
+| `/reload` | Reload extensions, skills, prompts, themes, and context files. |
+| `/hotkeys` | Show every keyboard shortcut. |
+| `/changelog` | Show pi's version history. |
+| `/quit` | Quit. |
+
+## Keyboard shortcuts
+
+### One Code
+
+| Shortcut | What it does |
+|---|---|
+| **ctrl+q** | 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). |
+| **Esc** | Leave a panel, or cancel a dialog. |
+| **ctrl+c** | Close any panel. |
+
+Panel-specific keys are listed in
+[The terminal interface](terminal-interface.md#panels-opened-by-commands).
+
+### pi
+
+The ones you will use most; `/hotkeys` shows all of them.
+
+| Shortcut | What it does |
+|---|---|
+| **shift+tab** | Cycle the thinking level. |
+| **ctrl+t** | Show or hide thinking blocks. |
+| **ctrl+o** | Expand or collapse a tool's output. |
+| **ctrl+p**, **shift+ctrl+p** | Cycle models forward or backward. |
+| **ctrl+l** | Open the model picker. |
+| **Esc** | Interrupt the model. |
+| **ctrl+c** | Clear the editor; press twice to exit. |
+| **ctrl+d** | Exit when the editor is empty. |
+| **alt+enter** (**ctrl+q** on Windows and WSL) | Queue a follow-up message while the model works. |
+| **alt+↑** | Restore queued messages to the editor. |
+| **ctrl+g** | Edit the prompt in your external editor. |
+| **ctrl+v** | Paste an image or text. |
+| **shift+enter**, **ctrl+j** | Insert a newline. |
+| **ctrl+x** | Copy the last reply. |
+| **PgUp**, **PgDn**, **Home**, **End** | Scroll the transcript in full-screen mode. |
+| **ctrl+shift+f** | Search the transcript in full-screen mode. |
+| **!** at the start of a line | Run a shell command yourself. |
+
+Rebind keys in pi's keybindings file; see pi's documentation.
+
+## Command-line flags
+
+`onecode` forwards every flag to pi except `--version` and `doctor`. On the
+extension installation, use `pi` in place of `onecode`.
+
+| Flag | What it does |
+|---|---|
+| `onecode --version`, `-v` | Print the app version and the pi version inside it. |
+| `onecode doctor` | Print the setup report without starting a session. Exit 1 when no provider is ready. |
+| `-p "…"`, `--print` | Run one prompt and exit. |
+| `--mode json` | Emit JSON events for scripting. |
+| `--mode rpc` | Speak pi's RPC protocol over stdin and stdout. |
+| `-c`, `--continue` | Continue the most recent session. |
+| `-r`, `--resume` | Browse and pick a session. |
+| `--session <id>`, `--fork <id>` | Open or fork a specific session. |
+| `--no-session` | Do not save this session. |
+| `--permission-mode <mode>` | Start in `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`, or `dontAsk`. |
+| `--dangerously-skip-permissions` | Start in bypass mode. |
+| `--model <provider/id>` | Start on a model. Add `:<level>` to set thinking. |
+| `--thinking <level>` | Start at a thinking level. |
+| `--provider <name>`, `--api-key <key>` | Choose a provider and supply a key for this run. |
+| `--tui-mode fullscreen` | Full-screen interface (the default under the app). |
+| `--tools <list>` | Restrict the tools available. |
+| `-e <source>` | Load an extra extension. |
+| `--offline` | Skip network checks, including the update check. |
+| `--append-system-prompt <text>` | Append to the system prompt. |
+| `--verbose` | Show the full startup listing. |
+
+## Environment variables
+
+Set these before launching.
+
+### One Code
+
+| Variable | Effect |
+|---|---|
+| `ONECODE_STATE_DIR` | Where One Code keeps its state (default `~/.onecode`). Independent of pi's agent directory. |
+| `ONECODE_NO_UPDATE_CHECK=1` | Skip the daily update check. |
+| `ONECODE_DEBUG=1` | Report when a pi-internal patch in the bundled app did not apply. |
+| `AA_API_KEY` | Artificial Analysis key for measured model selection. |
+| `BRAVE_SEARCH_API_KEY`, `TAVILY_API_KEY` | Web-search fallback keys. |
+
+### Claude Code compatibility toggles
+
+The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
+
+| Variable | Effect |
+|---|---|
+| `CC_NO_BANNER=1` | Keep pi's header instead of the One Code banner. |
+| `CC_NO_INPUT_MARKER=1` | Remove the `❯` prompt marker. |
+| `CC_NO_ASSISTANT_MARKER=1` | Remove the `●` reply marker. |
+| `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_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. |
+| `CC_TOTAL_TOKENS=0` | Remove the `<total_tokens>` budget line. |
+| `CC_TOTAL_TOKENS_BUDGET` | The per-turn budget the line counts down from (default 15000000). |
+| `CC_PROMPT_TIER=frontier\|workhorse\|cheap\|tiny` | Force a system-prompt tier. |
+| `CC_HOOKS_DEBUG=1` | Print hook dispatches to stderr and log decisions. |
+| `CC_AUTO_MODE_DEBUG=1` | Print classifier verdicts to stderr. `2` is more verbose. |
+| `CC_VERSION` | The version shown in the banner (set by the app). |
+| `CC_PERMISSION_MODE` | Set by One Code to the live mode for child processes. Not an input; use `--permission-mode`. |
+
+### pi and Claude Code variables honored
+
+| Variable | Effect |
+|---|---|
+| `PI_CODING_AGENT_DIR` | pi's agent directory. The app sets `~/.onecode/agent`. |
+| `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_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`). |
+| Provider keys | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `OPENCODE_API_KEY`, and the rest pi supports. |
+
+Variables One Code sets for hooks and children: `CLAUDE_PROJECT_DIR` in a
+hook's environment, `CC_PERMISSION_MODE` for child tool gates.
+
+## Files and directories
+
+| Path | Contents |
+|---|---|
+| `~/.onecode/` | One Code's state. See [What is stored under ~/.onecode](configuration.md#what-is-stored-under-onecode). |
+| `~/.onecode/agent/` | pi's state under the bundled app: credentials, sessions, pi's settings, plugins. |
+| `~/.claude/` | Claude Code's configuration, read only, except `projects/<slug>/memory/`. |
+| `~/.claude/projects/<slug>/memory/` | Per-repository memory, shared with Claude Code. |
+| `.claude/` | Project configuration: `settings.json`, `settings.local.json`, `skills/`, `commands/`, `agents/`, `workflows/`, `worktrees/`. |
+| `.mcp.json` | Project MCP servers. |
+| `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `ONECODE.md` | Instruction files. |
+| System temp directory | Session scratchpads. |
+
+## Tools
+
+The tools available to the model are listed in [Tools](tools.md), with the
+mapping from Claude Code's names.
+
+## Themes
+
+`onecode` (dark) and `onecode-light`. See
+[Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).

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

@@ -0,0 +1,190 @@
+# Sessions and context
+
+This page covers what One Code puts into the model's context, how it keeps
+long sessions within the context window, what it remembers between
+sessions, and how to continue or branch a session.
+
+## What the model sees at the start
+
+The first message of every session carries a context block built the same
+way Claude Code builds it, so the model reads your instructions exactly as
+it would there. The block contains, in order:
+
+1. **Project instructions.** Every `CLAUDE.md` from your home directory's
+   `~/.claude/CLAUDE.md` down through each ancestor directory to the
+   working directory. In a directory that has no `CLAUDE.md`, an
+   `AGENTS.md` is used instead. A `CLAUDE.local.md` next to either is
+   included as your private, uncommitted instructions.
+2. **The auto-memory index.** The first 200 lines or 25 KB of `MEMORY.md`
+   from the repository's memory folder. See [Memory](#memory).
+3. **Your email**, from `git config user.email` (or `GIT_AUTHOR_EMAIL` or
+   `EMAIL`), for attribution.
+4. **Today's date.**
+
+`@path` references inside a `CLAUDE.md` are expanded in place, up to five
+levels deep, so a file that imports shared instructions keeps working.
+Paths resolve relative to the importing file; `~/` resolves to your home
+directory. References inside code spans and fenced blocks are left alone.
+
+A `CLAUDE.md` larger than 40,000 characters, or a set of instruction files
+whose total exceeds that, triggers a warning at startup so you can trim it.
+Run `/memory` to open any of these files.
+
+### ONECODE.md
+
+Instructions that only One Code should read go in `ONECODE.md`
+(`onecode.md` and `One Code.md` also work). Claude Code never reads this
+file. One Code adds it as a separate block after the Claude Code context,
+marked as taking precedence, so the order is ONECODE.md, then CLAUDE.md,
+then AGENTS.md. A global `~/.onecode/ONECODE.md` is read too.
+
+Use it for instructions that mention One Code features, such as the
+`ultracode` keyword or a subagent model preference, without confusing a
+real Claude Code session on the same repository.
+
+### The system prompt
+
+The system prompt is an adaptation of Claude Code's, chosen by the
+capability of the model in use. Stronger models receive a terse prompt;
+smaller models receive more guidance and, on the smallest tier, extra
+search tools. It ends with a git status snapshot (branch, main branch, user,
+working-tree status, recent commits) taken once per session. See
+[Prompting adapts to the model](providers-and-models.md#prompting-adapts-to-the-model).
+
+## Memory
+
+One Code keeps per-repository memory in the same place Claude Code does:
+`~/.claude/projects/<slug>/memory/`, where the slug is derived from the
+repository root (or the working directory outside a repository). Worktrees
+and subdirectories of one repository share one memory folder. This is the
+one place One Code writes under `~/.claude`, so a real Claude Code session
+on the same repository reads the same memories.
+
+The model writes one file per memory and keeps an index in `MEMORY.md`.
+When the index grows near its limit (200 lines or 25 KB), the model is
+warned; past the limit, a write to it still succeeds but returns an error
+so the model trims the index.
+
+Run `/memory` to open the memory folder or any instruction file. Files open
+in `$VISUAL` or `$EDITOR`; folders open in your file manager.
+
+## The context window
+
+### Compaction
+
+When the conversation approaches the context limit, One Code replaces the
+older part with a summary, using Claude Code's compaction instruction: the
+summary keeps the request and intent, key concepts, the files touched,
+errors and fixes, every user message, pending tasks, and the current work.
+The summary also points the model at the session file so it can search the
+full transcript if it needs a detail.
+
+Run `/compact` to compact at any time; you can pass instructions about what
+the summary should focus on. Compaction that happens because the context is
+full is more expensive than a manual or threshold compaction, because it
+cannot reuse the cached prefix of the conversation.
+
+Set `CC_COMPACTION=0` to use pi's own summary instead.
+
+### The token budget line
+
+Like Claude Code, One Code tells the model how many tokens it has left in
+the current turn: a `<total_tokens>` line appears in the system prompt, at
+the end of every user message, and after every tool result. The budget is
+15,000,000 tokens per turn, Claude Code's own figure. Set
+`CC_TOTAL_TOKENS_BUDGET` to change it or `CC_TOTAL_TOKENS=0` to remove it.
+
+### Thinking blocks and the cache
+
+On Anthropic's own API, One Code asks the provider to keep earlier thinking
+blocks in place rather than strip them, because stripping them invalidates
+the prompt cache on older models. This is on by default for
+`api.anthropic.com` and off for Bedrock, Vertex, and proxies. Set
+`CC_CLEAR_THINKING=1` to force it on elsewhere or `CC_CLEAR_THINKING=0` to
+turn it off.
+
+### The prompt cache
+
+Interactive sessions ask the provider for an extended cache lifetime (one
+hour on Anthropic; provider-dependent elsewhere), so a pause between turns
+does not re-send the whole conversation. Subagents, workflow agents, and
+`-p` or `--mode json` runs use the provider's short default. Set
+`PI_CACHE_RETENTION` yourself to take over the choice. The footer shows the
+cache-hit rate of the latest turn.
+
+Changing the reasoning effort or the model re-caches the conversation, so
+one request after such a change costs more than usual.
+
+## Scratch space and large output
+
+Each session gets a scratchpad directory under the system temp directory,
+named by project and session. The model is told to use it for temporary
+files instead of `/tmp`; writes there need no approval.
+
+Tool output larger than 50 KB is not truncated. It is written to a file
+under the session directory, and the model receives the path, the size,
+and a 2 KB preview in a `<persisted-output>` block, so it can read the part
+it needs.
+
+## While you are away
+
+After five minutes without a keystroke following a turn, One Code shows a
+short recap of what the model was doing and what comes next, prefixed with
+`※ recap:`. The recap is produced by a cheap model on your provider using
+Claude Code's own recap prompt, is display-only, and is never sent back to
+the model. Its cost is included in the footer's total.
+
+Set `CC_RECAP_IDLE_MS` to change the delay (in milliseconds) or `CC_RECAP=0`
+to turn recaps off.
+
+## Continue, resume, and branch
+
+Session management is pi's own. The commands work the same under `onecode`:
+
+```bash
+onecode -c                    # continue the most recent session
+onecode -r                    # browse and pick a session to resume
+onecode --session <id>        # open a specific session
+onecode --fork <id>           # fork a session into a new file
+onecode --no-session          # do not save this session
+```
+
+Inside a session, `/resume` browses sessions, `/tree` shows the session's
+branches and lets you switch between them, `/fork` and `/clone` copy the
+session, `/name` names it, and `/export` writes it to HTML.
+
+The resume hint printed when a session ends reads `onecode --session …`
+under the bundled app.
+
+### What comes back after a resume or branch switch
+
+Restored from the session file:
+
+- The file-tracker's record of which files the model has read, checked
+  against the current contents on disk.
+- The structured task list.
+- The plan file, when the session was in plan mode.
+- The history of subagent runs, so a finished subagent can still be
+  messaged.
+
+Not restored:
+
+- The permission mode. A resumed session starts in the configured default.
+- Background shells, monitors, running subagents, and background workflow
+  runs. They stop when a session ends; the next session is told what was
+  stopped. A workflow can be resumed from its journal.
+- Session-only approvals from the permission prompt.
+- The reasoning effort level.
+
+### Start over
+
+`/clear` starts a new session in the same directory, the same as pi's
+`/new`. Running background tasks are stopped and listed. The permission
+mode you chose carries over.
+
+## Turn timing
+
+After each turn, a dim line such as `✻ Cooked for 5m 12s` reports how long
+it took, with a random verb, as in Claude Code. When background shells are
+still running, the line adds a count. Set `CC_TURN_DURATION=0` to turn it
+off.