# Command and keyboard reference

[← One Code user guide](README.md)

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 auto` | Choose automatically on every provider, ignoring the subagent model variables. | |
| `/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 `auto` to clear the saved level), 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` | Open the permissions panel: approve calls auto mode denied, and manage rules, auto-mode rules, and workspace directories. | [Manage permissions in the panel](permissions-modes-and-auto-mode.md#manage-permissions-in-the-panel) |
| `/add-dir [path]` | Add a workspace directory, for this session or remembered. | [Workspace directories](permissions-modes-and-auto-mode.md#workspace-directories) |
| `/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 the classifier model, or go back to the automatic pick. | [The classifier model](permissions-modes-and-auto-mode.md#the-classifier-model) |
| `/memory` | Open an instruction file or the memory folder, turn auto-memory on or off, or switch config sources. | [Memory](sessions-and-context.md#memory) |
| `/config` | Change this project's external instruction import approval. | [External instruction imports](sessions-and-context.md#external-instruction-imports) |
| `/artifacts` | Pick a saved artifact to open, save to `~/Downloads`, or delete, or open the gallery. | [Artifacts](tools.md#artifacts) |
| `/tasks` | List background shells, running agents and the agents you've viewed; open or stop one. | [Talk to an agent](subagents-and-workflows.md#talk-to-an-agent) |
| `/background` | List background tasks. | [Background](tasks-and-background-work.md#the-background-list) |
| `/loop <interval> <task>` | Repeat a task at a fixed interval (`5m`, `2h`, `1d`, or `… every 20m`). Ask the model to stop it. | [Loops](tasks-and-background-work.md#scheduled-wake-ups-and-loops) |
| `/loop <task>` | Repeat a task, letting the model choose the pace. | |
| `/loop`, `/loop <interval>` | Run the autonomous check, or the tasks in `.claude/loop.md`, on a 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`); the model is told. | [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** (**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). |
| **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. |
| **alt+t** (**ctrl+\\** on macOS) | Show or hide the task list. |
| **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. |
| **Enter** while the model works | Queue a message. It reaches the model once the running tool calls finish. |
| **ctrl+x ctrl+s** | Send queued messages now: interrupt the running turn and send them, with anything in the editor, as your next prompt. Running tools are cancelled. |
| **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. While the model works with a message queued or typed, it starts **ctrl+x ctrl+s** instead. |
| **PgUp**, **PgDn**, **ctrl+home**, **ctrl+end** | Scroll the transcript in full-screen mode. On pi before 1.0.3, **Home** and **End** jump to the top and bottom instead. |
| **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 install, 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. |
| `--add-dir <paths>` | Add workspace directories for this run, separated by `:` (`;` on Windows). |
| `--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. On pi 1.0 and later, `--provider` needs `--model` too. |
| `--tui-mode fullscreen`, `--tui-mode regular` | Full-screen interface (the default under the app and on pi 1.0 and later), or the terminal's normal screen with its scrollback. |
| `--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. |
| `--profile <name>` | Run under one of your own profiles: see [Profiles](#profiles). `ONECODE_PROFILE=<name>` does the same. |
| `--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_AGENT_DIR` | pi's agent directory under the bundled app (default `~/.onecode/agent`). |
| `ONECODE_NO_UPDATE_CHECK=1` | Skip the daily update check. |
| `ONECODE_DEBUG=1` | Report when a pi-internal patch in the bundled app didn't apply. |
| `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 |
|---|---|
| `ONECODE_NO_BANNER=1` | Keep pi's header instead of the One Code banner. |
| `ONECODE_NO_INPUT_MARKER=1` | Remove the `❯` prompt marker. |
| `ONECODE_NO_ASSISTANT_MARKER=1` | Remove the `●` reply marker. |
| `ONECODE_FEATURES_OFF=<id>[,<id>…]` | Turn optional features off for this run, by id, comma-separated. The rows below name the common ones. |
| `ONECODE_FEATURES_OFF=footer` | Keep pi's footer instead of One Code's status line. |
| `ONECODE_FEATURES_OFF=turn-duration` | Remove the post-turn timing line. |
| `ONECODE_FEATURES_OFF=recap` | Turn off the "while you were away" recap. |
| `ONECODE_FEATURES_OFF=session-title` | Turn off the automatic session title. |
| `ONECODE_RECAP_IDLE_MS` | Idle time before a recap, in milliseconds (default 300000). |
| `ONECODE_FEATURES_OFF=compaction` | Use pi's compaction summary instead of Claude Code's. |
| `ONECODE_FEATURES_OFF=idle-compact` | Turn off compaction of an idle session before its prompt cache expires. |
| `ONECODE_CLEAR_THINKING=0`, `=1` | Force the thinking-preservation request off or on for Anthropic models. Default: on for `api.anthropic.com` only. |
| `ONECODE_FEATURES_OFF=context-budget` | Remove the `<total_tokens>` budget line. |
| `ONECODE_TOTAL_TOKENS_BUDGET` | The per-turn budget the line counts down from (default 15000000). |
| `ONECODE_PROMPT_TIER=frontier\|workhorse\|cheap\|tiny` | Force a system-prompt tier. |
| `ONECODE_HOOKS_DEBUG=1` | Print hook dispatches to stderr and log decisions. |
| `ONECODE_AUTO_MODE_DEBUG=1` | Print classifier verdicts to stderr. `2` is more verbose. |
| `ONECODE_VERSION` | The version shown in the banner (set by the app, and not passed on to the commands it runs). |
| `ONECODE_PERMISSION_MODE` | Set by One Code to the live mode for child processes. Not an input; use `--permission-mode`. |

### Variables with a Claude Code spelling

Each of these variables also works under Claude Code's name, with
`CLAUDE_CODE_` in place of `ONECODE_`, so the ones you set for Claude Code
keep working. One Code reads Claude Code's spelling only in Claude-compatible
mode. When both spellings are set, One Code's wins.

| Variable | Effect |
|---|---|
| `ONECODE_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). |
| `ONECODE_GIT_BASH_PATH` | The bash that drives the `bash` tool, hooks, and background shells. Also read from the `env` block of your user settings; a non-bash binary is ignored with a warning. |
| `ONECODE_SUBAGENT_MODEL` | Default subagent model. Claude Code's `CLAUDE_CODE_SUBAGENT_MODEL` applies only on a Claude session. |
| `ONECODE_DISABLE_AUTO_MEMORY=1` | Turn auto-memory off, overriding the setting in `/memory`. `0` turns it on. |
| `ONECODE_ENABLE_TODO_TOOLS=1` | Give frontier models and Sonnet 5 or later the task tools, which they run without by default. |
| `ONECODE_LOOP_KEEPALIVE=0` | Turn off the fallback wake-up of a self-paced `/loop`. |
| `ONECODE_TICKLISH_WHISPER_TIMEOUT_MS` | How long an unanswered auto-mode prompt waits before it denies the action, in milliseconds (default 120000). |

### pi and Claude Code variables honored

| Variable | Effect |
|---|---|
| `PI_CODING_AGENT_DIR` | pi's agent directory on your own pi. The bundled app ignores it and uses `ONECODE_AGENT_DIR`; commands the app runs get your own value back. |
| `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. |
| `ONECODE_CONFIG_MODE` | `claude-compatible` or `independent`, overriding the mode saved by `/memory`. See [Run One Code on its own setup](bring-your-claude-code-setup.md#run-one-code-on-its-own-setup). |
| `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, `ONECODE_PERMISSION_MODE` for child tool gates.

## Profiles

A profile is a saved set of choices you start One Code with: which tools it has, and what the
model is told. It's a folder of your own, `~/.onecode/profiles/<name>/`, and every file in it is
optional:

| File | Effect |
|---|---|
| `profile.json` | The switches. `{"tools": {"off": ["web_fetch"], "deferred": ["notebook_edit"], "eager": ["lsp_diagnostics"]}, "features": {"off": ["artifacts"]}}` turns tools and optional features off, moves a tool behind `tool_search`, or loads one up front. |
| `system-prompt.md` | Replaces the whole system prompt, including the tool guidance One Code writes. The first message still tells the model its working directory, platform and model. |
| `append-system-prompt.md` | Is added after the system prompt. |
| `tools/<tool>.md` | Replaces that tool's description. |
| `tools/<tool>.append.md` | Is added after that tool's description. |

Start it with `onecode --profile <name>`. The flag wins over `ONECODE_PROFILE`. `/doctor` shows the profile in force and what it changes.

A few things to know:

- Adding to a description is safer than replacing it. A replacement stays as you wrote it when a
  release rewords the tool.
- A profile can't turn off the permission checks, the hooks or the tools One Code needs to run
  (`tool_search`, for one). A profile that tries stops the launch and says what to fix.
- Profiles are read only from your own folder, never from a project.
- A session remembers the profile it ran under. Resume it under another one and One Code sends
  the system prompt and tools again, so the first reply after that reads no prompt cache.

## 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/`. Not read in independent mode. |
| `~/.claude/projects/<slug>/memory/` | Per-repository memory, shared with Claude Code. |
| `~/.onecode/projects/<slug>/memory/` | Per-repository memory in independent mode. |
| `.onecode/` | Project `commands/`, `agents/`, `workflows/` and `worktrees/` in independent mode. |
| `.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).
