@tempr/cli 0.9.21 → 0.9.23

package/README.md

@@ -6,7 +6,7 @@ Sign in, chat, and run agentic coding tasks against your Tempr license from the
 
 ## Install
 
-The standalone builds need nothing installed first -- no .NET, no Node.
+The standalone builds need nothing installed first: no .NET, no Node.
 
 **macOS and Linux**
 
@@ -45,49 +45,58 @@ tempr                          # interactive session
 
 ## Usage
 
-- `tempr "<prompt>"` -- one-shot agent turn with real tool-calling (file read/write/edit, run_command, semantic search).
-- `tempr` -- interactive REPL with persistent history and tab-completion for `/commands` and `@personas`. The first run plays a short animated ASCII logo; `TEMPR_LOGO=1` plays it again, `TEMPR_NO_LOGO` skips it, and `NO_COLOR` shows a plain one-line name instead of the animation.
-- `<something> | tempr` -- headless/piped mode: with no prompt argument, stdin is the whole prompt (`{ echo "review this:"; git diff; } | tempr`). Given a prompt argument, the piped text follows it as context (`git diff | tempr "review this"`), as in Claude Code and Codex. If nothing arrives on stdin within 3 seconds, the prompt runs on its own and a note goes to stderr; redirect from `/dev/null` (`NUL` on Windows) to skip the wait.
-- `tempr --ask "<prompt>"` -- plain chat, no tools.
-- `tempr "@debugger why does this fail"` -- run a specialist persona. In the REPL, `/persona` opens a picker to switch personas for the rest of the session instead of typing `@name` every turn.
-- `@workspace`/`#codebase` anywhere in a message attaches a brief workspace overview; `@problems`/`@diagnostics` attaches current compiler errors/warnings (via `dotnet build`/`tsc --noEmit`); `@relative/path/to/file` attaches that file -- images (`.png`/`.jpg`/`.gif`/`.webp`/`.bmp`) go in as real image content, other files as inline text.
-- Workspace instructions: every agent turn carries `AGENTS.md` and `.github/copilot-instructions.md` from the current directory, other agents' files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules` and Cursor rules in `.cursor/rules` that always apply; the others are listed with their description for the agent to read when relevant), then a global `~/.tempr/AGENTS.md` for every workspace, each under its own heading and 16 KB combined at most. Where they disagree, AGENTS.md wins. `--verbose` names the files it found.
-- `tempr auth` signs in through your browser: it shows a code, opens the Tempr portal, and you approve the sign-in there -- on any device, so it works over SSH too. `tempr auth --browser` skips the question; `tempr auth <key>` or `TEMPR_LICENSE_KEY` still sign in with a license key, for scripts and CI. Running `tempr` for the first time walks through signing in, adding a provider key and picking a model.
+- `tempr "<prompt>"`: one-shot agent turn with real tool-calling (file read/write/edit, run_command, semantic search).
+- `tempr`: interactive REPL with persistent history and tab-completion for `/commands` and `@personas`. The first run plays a short animated ASCII logo; `TEMPR_LOGO=1` plays it again, `TEMPR_NO_LOGO` skips it, and `NO_COLOR` shows a plain one-line name instead of the animation.
+- `<something> | tempr`: headless/piped mode. With no prompt argument, stdin is the whole prompt (`{ echo "review this:"; git diff; } | tempr`). Given a prompt argument, the piped text follows it as context (`git diff | tempr "review this"`), as in Claude Code and Codex. If nothing arrives on stdin within 3 seconds, the prompt runs on its own and a note goes to stderr; redirect from `/dev/null` (`NUL` on Windows) to skip the wait.
+- `tempr --ask "<prompt>"`: plain chat, no tools.
+- `tempr "@debugger why does this fail"`: run a specialist persona. In the REPL, `/persona` opens a picker to switch personas for the rest of the session instead of typing `@name` every turn.
+- `@workspace`/`#codebase` anywhere in a message attaches a brief workspace overview; `@problems`/`@diagnostics` attaches current compiler errors/warnings (via `dotnet build`/`tsc --noEmit`); `@relative/path/to/file` attaches that file. Images (`.png`/`.jpg`/`.gif`/`.webp`/`.bmp`) go in as real image content, other files as inline text.
+- Workspace instructions: every agent turn carries `AGENTS.md` and `.github/copilot-instructions.md` from the current directory, Claude Code's memory files (see [Memory files](#memory-files)), other agents' files (`GEMINI.md`, `.cursorrules` and Cursor rules in `.cursor/rules` that always apply; the others are listed with their description for the agent to read when relevant), then a global `~/.tempr/AGENTS.md` for every workspace, each under its own heading. Where they disagree, AGENTS.md wins. `/memory` lists what a turn sends, and `--verbose` names the files it found.
+- `tempr auth` signs in through your browser: it shows a code, opens the Tempr portal, and you approve the sign-in there, on any device, so it works over SSH too. `tempr auth --browser` skips the question; `tempr auth <key>` or `TEMPR_LICENSE_KEY` still sign in with a license key, for scripts and CI. Running `tempr` for the first time walks through signing in, adding a provider key and picking a model.
 - `tempr -c` resumes this folder's most recent session; `/resume` picks one from a list.
-- `!command` in the REPL runs a command yourself -- `!git status` -- in this folder, and its output goes in front of your next message. No approval: it's your own command.
+- `!command` in the REPL runs a command yourself (`!git status`) in this folder, and its output goes in front of your next message. No approval: it's your own command.
 - A turn that runs 30 seconds or more rings the terminal bell when it's done or needs approval, with a desktop notification where the terminal shows one; `tempr config set-notifications off` or `TEMPR_NO_NOTIFY` turns it off.
-- `/diff` shows what the last turn changed on disk, and `/undo` puts it back -- skipping any file that has changed since, so an undo never overwrites work it didn't make. `/rewind` goes back to before any earlier message: its files, the conversation, or both.
+- `/diff` shows what the last turn changed on disk, and `/undo` puts it back, skipping any file that has changed since, so an undo never overwrites work it didn't make. `/rewind` goes back to before any earlier message: its files, the conversation, or both.
 - `--plan` (or `/plan` in the REPL) starts in plan mode: the agent looks around with read-only tools and proposes a plan, and nothing changes until you approve it.
-- `/compact [focus]` summarizes the conversation so far so the session can go on inside the model's context; it also happens by itself near the limit.
-- The agent can start a command in the background (a dev server, a watcher) and read its output later; `/tasks` lists them and `/tasks stop <id>` ends one. They all stop when the session ends.
+- `/compact [focus]` summarizes the conversation so far so the session can go on inside the model's context; it also happens by itself near the limit. With `tempr config set-idle-compaction on` (Claude Code's idle compaction, off by default), a conversation of 200K tokens or more left at the prompt is summarized just before its prompt cache runs out (about 5 minutes), and if you come back after that the next message starts from the summary instead of resending the whole conversation uncached.
+- `/btw <question>` asks a quick question about the conversation so far: answered without tools, shown apart, and not kept in the conversation. `/btw` alone shows the last answer again.
+- `/output-style [name]` picks how the agent works and answers: Default, Explanatory, Learning, Proactive, Concise, or your own (see [Output styles](#output-styles)).
+- `/code-review [low|medium|high|xhigh|max] [target] [--fix] [--max-findings n|all|default]` is Claude Code's review command, built in: it reviews this branch's commits ahead of its upstream plus uncommitted changes, or a PR number, a branch, a range or a path, and prints the findings as a numbered list (severity, place, summary, how it fails). `--fix` then fixes the important ones. It works under a one-shot prompt too (`tempr "/code-review high"`). The level you type is remembered; `medium` is the default.
+- The agent can start a command in the background (a dev server, a watcher) and read its output later, and start a sub-agent in the background and carry on. `/tasks` (or `/bashes`) lists both, `/tasks <id>` prints one's whole output, `/tasks stop <id>` stops one and `/tasks stop all` stops everything. A finished sub-agent's result goes to the agent before your next message (or press Enter alone to hand it over); a one-shot run waits for its sub-agents before it exits. They all stop when the session ends.
+- Live preview (a project's `.claude/launch.json` dev servers and the agent's browser tools: screenshots, clicking, the console) is Tempr Code's: it needs a browser pane, which a terminal doesn't have, so the CLI doesn't offer those tools. Run the server in the background instead.
 - A model that reasons shows "✻ Thought for Ns" before each step; `--verbose` prints what it thought.
-- `-w/--worktree <name>` runs the session in a git worktree of its own, on a new branch, so it doesn't touch this folder.
+- `-w/--worktree <name>` runs the session in a git worktree of its own, on a new branch, so it doesn't touch this folder. A `.worktreeinclude` at the repository's root (`.gitignore` syntax, as in Claude Code) names gitignored files a new worktree gets copied, such as `.env`. A `WorktreeCreate` hook, when there is one, makes the worktree instead of git.
+- `--add-dir <dir>` (or `/add-dir <dir>` in the REPL) lets the agent read and edit files in another folder too, for the session; `permissions.additionalDirectories` in settings adds one for good.
 - `tempr history search <text>` finds past sessions by what was said in them; `tempr history export` (or `/export`) writes one out as Markdown.
-- `tempr keys` lists your provider keys -- Tempr calls every model with your own key for its provider. `tempr keys add [provider]` adds or replaces one (no provider opens a picker), and `tempr keys remove <provider>` removes one; `/keys` does the same inside the REPL. The key is typed at a hidden prompt, piped in on stdin, or read with `--from-env VARIABLE` -- never passed as an argument, where it would land in shell history. Tempr checks it with the provider before saving it; a key the provider rejects isn't saved unless you say so or pass `--force`, and one that couldn't be checked (the provider was down, or offers no way to check) is saved with a note. Azure OpenAI, Azure AI Foundry, AWS Bedrock and custom endpoints need more than a key, so they're set up on the Portal's Provider keys page; on a Team plan, your organization's admin manages keys.
+- `tempr keys` lists your provider keys: Tempr calls every model with your own key for its provider. `tempr keys add [provider]` adds or replaces one (no provider opens a picker), and `tempr keys remove <provider>` removes one; `/keys` does the same inside the REPL. The key is typed at a hidden prompt, piped in on stdin, or read with `--from-env VARIABLE`, never passed as an argument, where it would land in shell history. Tempr checks it with the provider before saving it; a key the provider rejects isn't saved unless you say so or pass `--force`, and one that couldn't be checked (the provider was down, or offers no way to check) is saved with a note. Azure OpenAI, Azure AI Foundry, AWS Bedrock and custom endpoints need more than a key, so they're set up on the Portal's Provider keys page; on a Team plan, your organization's admin manages keys.
 - `tempr models` lists the models your licence can use, with prices and context sizes; `/model` with no argument opens a picker over the same list.
 - `tempr init` drafts an `AGENTS.md` for this workspace from a scan of what's in it.
 - `tempr usage` shows what this machine's turns have cost, by model.
 - `tempr completion bash|zsh|fish|powershell` prints a completion script.
-- `tempr config`, `tempr history`, `tempr mcp`, `tempr doctor` -- manage config, saved sessions, MCP servers, and connectivity. `tempr mcp browse` (or `/mcp browse` in the REPL) opens a picker over Tempr's curated MCP catalog.
+- `tempr config`, `tempr history`, `tempr mcp`, `tempr doctor`: manage config, saved sessions, MCP servers, and connectivity. `tempr mcp browse` (or `/mcp browse` in the REPL) opens a picker over Tempr's curated MCP catalog.
+- Remote MCP servers, as in Claude Code: `tempr mcp add --transport http <name> <url>` (or `sse`, the deprecated transport), with `--header "Name: value"`. One that uses OAuth signs in with `tempr mcp login <name>` or `/mcp login <name>` (`--no-browser` prints the address instead of opening it): the browser opens, comes back to `http://localhost:PORT/callback`, and the tokens are kept encrypted in `~/.tempr` and refreshed; `tempr mcp logout <name>` (or removing the server) deletes them. For an authorization server that can't register Tempr itself, add `--client-id` and `--callback-port`. `tempr mcp list` and `/mcp` show each server's sign-in state.
+- A server's resources are mentioned as `@server:protocol://path` (completed after `@`) and attached to the message; its prompts are commands, `/mcp__server__prompt arg1 arg2`, in the REPL, in `tempr acp` and at the start of a one-shot prompt (`tempr "/mcp__github__review 42"`, piped input after it). A server that says its tools, resources or prompts changed is listed again.
 - Agent-mode tools also include `get_diagnostics`, `search_symbols` (where a name is defined, then where it's used, in C#, TypeScript and JavaScript, Python, Go, Rust, Java, Kotlin, C and C++, Swift, Ruby and PHP), `get_callers`/`get_callees` (lexical, not a real language server), and `get_solution`/`get_projects`/`get_project_references`/`get_tests`/`run_tests`/`get_test_results` for .NET workspaces.
 - Web search: on an Anthropic, OpenAI or xAI model, the agent can search the web with the provider's own search, shown as `Searching the web for "…"`. The provider runs the search and bills it to your key for that provider, on top of the tokens: $10 per 1,000 searches on Anthropic and OpenAI, and $5 per 1,000 on xAI, where opening a page counts as a search too; the cost `tempr usage` and the Portal show includes it. It's on in an interactive session and off in scripts (`--json`, piped input, `CI`); `--search` and `--no-search` decide for one run, and `tempr config set-web-search off` turns it off for interactive sessions too. The pages a search finds are ones the agent may then open with `web_fetch`.
 - Chat history (`~/.tempr/sessions/`) and auth tokens are both encrypted at rest (DPAPI on Windows, AES-256-GCM elsewhere).
 
 ## Approval modes
 
-Mutating tool calls -- file writes, patches, commands and MCP calls -- are gated by an approval
+Mutating tool calls (file writes, patches, commands and MCP calls) are gated by an approval
 mode. `tempr config set-approval-mode <mode>` sets the default; `--yolo` uses `autopilot` for one
-run without changing it, and on Linux puts its commands in the sandbox (see below).
+run without changing it, and on Linux and macOS puts its commands in the sandbox (see below).
 
 | Mode | File edits and MCP calls | Commands |
 |---|---|---|
 | `interactive` (default) | asks | asks |
 | `autopilot` | run | allow-listed commands run; ones that delete, publish, force-push, reset or reboot, and anything not allow-listed, ask |
-| `bypass` | run | always asks -- **stricter than `autopilot`**, despite the name |
+| `bypass` | run | always asks: **stricter than `autopilot`**, despite the name |
 
 The mode names are shared with Tempr's IDE extensions, which is why `bypass` reads the way it does.
 `autopilot` is the one to use unattended. With no terminal to ask on (piped input, `--json`, CI), a
-call that would have asked is refused and the model is told why.
+call that would have asked is refused and the model is told why. When any settings file sets
+`permissions.disableBypassPermissionsMode` to `"disable"` (Claude Code's switch), `--yolo` and
+`--approval-mode autopilot` are refused (exit code 2) and a saved `autopilot` asks first instead.
 
 The allow-list starts with read-only commands and each ecosystem's build, test, lint and type-check
 commands: `dotnet build`/`test`, `npm test` and `npm run build`/`test`/`lint`/`typecheck` (and
@@ -95,25 +104,27 @@ the pnpm, yarn and bun equivalents), `pytest`, `go build`/`test`/`vet`, `cargo
 build`/`check`/`test`/`clippy`, `mvn compile`/`test`, `gradle build`/`test` and their wrapper
 scripts, `git status`, `git log` and the like. Other `package.json` scripts (`npm run deploy`)
 aren't on it. A prefix covers whole words: `npm run build` doesn't cover `npm run build-and-deploy`.
+A command with a line break or a redirection (`>`, `<`) is never allowed by the list.
 Add to it per machine with `tempr config allow-command <prefix>`, or per repository with an
 `.agentcommands.json` file at the workspace root: `{ "allowedPrefixes": ["docker build"] }`.
 
-Each turn tells the model which projects the workspace holds -- a few folders deep, so a monorepo's
-projects are listed with their folders -- and how each one builds and tests. A command runs in the
+Each turn tells the model which projects the workspace holds (a few folders deep, so a monorepo's
+projects are listed with their folders) and how each one builds and tests. A command runs in the
 workspace root or, with `working_directory`, a folder inside it (chaining `cd` is refused). It's
 stopped after 2 minutes unless the model asks for longer, up to 10, and long output keeps its start
 and its end. The .NET-only tools (projects, references, tests) are offered only where there's a .NET
 project.
 
-Every tool path is checked against the current directory, including through symbolic links and
-Windows junctions, so a link inside the workspace can't be used to read or write outside it.
+Every tool path is checked against the current directory (and the folders added with `--add-dir` or
+`additionalDirectories`), including through symbolic links and Windows junctions, so a link inside
+the workspace can't be used to read or write outside it.
 
-## Sandbox (Linux)
+## Sandbox (Linux and macOS)
 
 `--sandbox` runs the agent's commands inside a sandbox. They can change files only in the current
-folder, the temp folders and the package stores and caches builds write to (npm's, pip's, NuGet's,
-Go's, Cargo's, Gradle's and Maven's), and they can't open network connections. Reading is open.
-`tempr config set-sandbox on` turns it on for every run; `--no-sandbox` turns it off for one.
+folder, the folders added to it and the temp folders, and they can't open network connections.
+Package managers get a cache of their own. Reading is open. `tempr config set-sandbox on` turns it
+on for every run; `--no-sandbox` turns it off for one.
 
 **On by default for `--yolo` and CI.** A run on autopilot with nobody deciding command by command
 (`--yolo`, `--approval-mode autopilot`, or autopilot in CI) runs its commands in the sandbox with the
@@ -125,33 +136,77 @@ unless asked: the sandbox would let their commands run without asking.
 
 Inside the sandbox any command runs without asking, in every approval mode, so an unattended run can
 build, test and try things it has no allow-list entry for. Commands that delete, publish or
-force-push still ask. When a command fails because the sandbox blocked it -- a download, say -- the
+force-push still ask. When a command fails because the sandbox blocked it (a download, say), the
 agent can ask to run it outside the sandbox, which always asks you first; a run with nobody to ask
 refuses it.
 
-dotnet in the sandbox keeps its own per-user files in `~/.cache/tempr/sandbox-dotnet` rather than
-`~/.dotnet`, which holds global tools and stays read-only; it restores into your own
-`~/.nuget/packages` and reads your NuGet package sources.
-
 - **What it covers:** `run_command`, the .NET test tools and `get_diagnostics`. Not `!command`,
   which you type yourself, and not MCP servers.
-- **Git hooks:** a command may not keep changes to `.git/hooks`, `.git/config` or
-  `.agentcommands.json`, which run or allow things later, outside the sandbox. Tempr puts back
-  anything a command changed there and tells the agent.
+- **Protected files:** a command may not keep changes to files that run or allow things later,
+  outside the sandbox, as Claude Code's sandbox guards them: `.git/hooks`, `.git/config`, the
+  `core.hooksPath` folder (Husky's `.husky/`), submodules' config and hooks, `.agentcommands.json`,
+  `.claude/settings.json` and `settings.local.json`, `.tempr/settings*.json`, `.mcp.json`,
+  `launch.json` under `.claude` and `.tempr`, the `.claude/agents`, `commands`, `hooks` and `skills`
+  folders, the scripts the folder's hooks run, `.vscode`, `.idea`, and the shell and git startup
+  files at the workspace root (`.bashrc`, `.zshrc`, `.profile`, `.gitconfig`, `.gitmodules` and the
+  like). On Linux, Tempr puts back anything a command changed there and tells the agent; on macOS
+  the sandbox refuses the write. The agent's own edits to these files always ask, in every approval
+  mode, as do `git config` writes of `core.*` and `include` keys. `CLAUDE.md` isn't among them.
+- **One at a time:** one sandboxed command runs at a time per repository.
+- **Package caches:** each package manager (npm, pip, NuGet, Go, Cargo, Gradle, Maven and others) is
+  pointed at Tempr's own cache in `~/.cache/tempr/sandbox-cache`. Your own caches are read-only from
+  the sandbox, since builds outside it load code from them; NuGet still reads your packages as a
+  fallback folder. dotnet keeps its per-user files in `~/.cache/tempr/sandbox-dotnet` rather than
+  `~/.dotnet`, which holds global tools and stays read-only.
 - **The network:** `--sandbox-network` (or `set-sandbox network`) keeps the file limits and leaves
-  the network on. Cutting the network off blocks TCP only, so name lookups still work.
-- **Where it runs:** Linux 5.13 or later, and 6.7 or later to cut off the network, through the
-  kernel's Landlock. It needs no install and no privileges, and works in a container and on
-  Ubuntu 24.04. On macOS and Windows it isn't available yet (inside WSL2 it works). If you ask for
-  the sandbox where it can't run, nothing runs: the CLI exits with code 7 rather than run your
-  commands unsandboxed. `tempr doctor` says what this machine supports.
+  the network on. Cutting the network off blocks TCP on Linux, so name lookups still work, and TCP,
+  UDP and name lookups on macOS.
+- **Unix sockets:** blocked whether the network is on or off, as in Claude Code's sandbox, so a
+  command can't reach Docker's socket, an ssh-agent or tmux, which would act for it outside the
+  sandbox (sockets in the command's own temp folder still work). `"sandbox": {"network":
+  {"allowAllUnixSockets": true}}` lifts the block; on macOS, `allowUnixSockets` lists single socket
+  paths to let through. Tempr reads them from managed settings, your own `~/.claude/settings.json`
+  and `~/.tempr/settings.json`, and the folder's `.claude/settings.local.json`, never from a
+  repository's committed `.claude/settings.json`. On Linux, `allowUnixSockets` can't let single
+  sockets through (as in Claude Code); only `allowAllUnixSockets` does. `tempr doctor` says which
+  applies.
+- **Where it runs:** on Linux 5.13 or later, and 6.7 or later to cut off the network, through the
+  kernel's Landlock; it needs no install and no privileges, and works in a container and on Ubuntu
+  24.04. On macOS through Seatbelt (`/usr/bin/sandbox-exec`), as Claude Code's sandbox does it
+  there. On Windows it isn't available yet (inside WSL2 it works), nor in a remote environment
+  (`--env`). If you ask for the sandbox where it can't run, nothing runs: the CLI exits with code 7
+  rather than run your commands unsandboxed. `tempr doctor` says what this machine supports.
+
+## Remote environments (WSL and SSH)
+
+`--env` runs the session's workspace and every tool in another environment while the CLI runs here.
+Files are read and written there, and commands, git, the folder's hooks and stdio MCP servers run
+there. Nothing is installed or uploaded on the other side.
+
+```
+tempr --env wsl:Ubuntu                          # this folder's /mnt path in the distro (Windows)
+tempr --env ssh:devbox --env-dir ~/src/app      # a Host from ~/.ssh/config, or user@host
+```
+
+- `--env-dir <path>` names the folder over there; it's required for ssh, and WSL defaults to this
+  folder's `/mnt/<drive>` path. The home folder itself is refused unless you add `--env-allow-home`,
+  since its dotfiles (`.ssh`, `.aws`, shell profiles) would be in the agent's reach.
+- ssh runs in batch mode with your own config, keys and agent, and never asks for a password.
+  `TEMPR_SSH_CONFIG` points it at another config file. A host may use only letters, digits and
+  `. _ @ : [ ] -`.
+- Only the remote folder's own `.mcp.json` stdio servers start there, unless you add
+  `--env-user-mcp`; remote (HTTP) servers connect from here.
+- Not available remotely yet: the sandbox (asking for it exits with code 7), `--worktree` and
+  `--add-dir` (refused), language servers, the symbol, project, test and semantic-search tools,
+  rewinding or reverting files, and the folder's own skills, commands and agents.
+- The `--json` session line says which environment a run used (`environment`).
 
 ## Your own commands and agents
 
 Markdown files, shared with Tempr Code. Put them in `.tempr/` in a project to commit them with it,
 or in `~/.tempr/` to have them everywhere.
 
-`.tempr/commands/deploy.md` — invoked as `/deploy staging`:
+`.tempr/commands/deploy.md`, invoked as `/deploy staging`:
 
 ```markdown
 ---
@@ -164,7 +219,7 @@ Deploy to $ARGUMENTS. Check the health endpoint afterwards and report what you s
 
 `$ARGUMENTS` is everything after the command name; `$1`…`$9` are its whitespace-separated words.
 
-`.tempr/agents/dba.md` — invoked as `@dba what's slow about this query`:
+`.tempr/agents/dba.md`, invoked as `@dba what's slow about this query`:
 
 ```markdown
 ---
@@ -182,7 +237,63 @@ You know this schema inside out. Prefer an index over a rewrite, and always expl
 
 A repository set up for Claude Code works unchanged: commands in `.claude/commands` and
 `~/.claude/commands`, subagents in `.claude/agents` and `~/.claude/agents`, skills in
-`~/.claude/skills`, and the project's `.mcp.json` servers. Tempr's own file of the same name wins.
+`~/.claude/skills`, the project's `.mcp.json` servers, its memory files and output styles, and its
+settings. Tempr's own file of the same name wins.
+
+### Memory files
+
+Every turn carries Claude Code's memory files, read the way Claude Code reads them: an
+administrator's managed `CLAUDE.md` and `claudeMd` setting; your `~/.claude/CLAUDE.md` and
+`~/.claude/rules`; `CLAUDE.md`, `.claude/CLAUDE.md` and `CLAUDE.local.md` in each folder from the
+repository's root down to the workspace; the workspace's `.claude/rules` (a rule with `paths:` front
+matter loads once the agent touches a file it matches); a subfolder's `CLAUDE.md` once the agent
+works there; and `@path` imports, up to four hops. A file is cut at 40,000 characters and all of them
+together at 64 KB, the least specific first, and the turn says what was cut. Links are followed only
+while they stay inside the project (or `~/.claude`, for your own files), and a project's imports stay
+inside the project. `/memory` lists what's sent and what was left out, and `tempr doctor` names the
+files.
+
+### Output styles
+
+Claude Code's output styles: the built-in Default, Explanatory, Learning, Proactive and Concise, and
+your own Markdown files (`name`, `description`, `keep-coding-instructions` front matter) in
+`~/.claude/output-styles`, `~/.tempr/output-styles`, `.claude/output-styles` (up to the repository's
+root, the nearest winning), `.tempr/output-styles`, or a plugin. The `outputStyle` setting picks one;
+`/output-style <name>` saves it to the folder's `.claude/settings.local.json`, as Claude Code does.
+
+### Settings
+
+Settings are read in Claude Code's precedence: managed settings (`managed-settings.json` and
+`managed-settings.d/` in `C:\Program Files\ClaudeCode`, `/Library/Application Support/ClaudeCode` or
+`/etc/claude-code`), then the folder's `.claude/settings.local.json`, then its `.claude/settings.json`
+and `.tempr/settings.json`, then your own `~/.claude/settings.json` and `~/.tempr/settings.json`.
+Lists (rules, hooks, directories) combine; for a single value the file higher up wins.
+
+- **`env`:** variables for the session and everything it starts (commands, hooks, MCP and language
+  servers).
+- **Permission rules:** `permissions.allow`, `ask` and `deny` (`Read(./.env)`, `Bash(git push:*)`),
+  or `permissionsAllow` / `permissionsAsk` / `permissionsDeny` in `~/.tempr/config.json`. Deny beats
+  ask, and ask beats allow, whatever the file; an ask rule asks every time, in every mode.
+  `permissions.additionalDirectories` adds folders the agent may use. `/permissions` lists the rules
+  with their files and the calls refused lately; `/permissions check <tool> <arg>` says which rule
+  decides a call.
+- **MCP servers:** `allowedMcpServers` / `deniedMcpServers` (by `serverName`, `serverCommand` or
+  `serverUrl`) apply to every server, whatever its source; `allowManagedMcpServersOnly` in managed
+  settings counts only the managed list. For a folder's `.mcp.json`, `disabledMcpjsonServers` keeps a
+  server off, and `enabledMcpjsonServers` / `enableAllProjectMcpServers` in your own or managed
+  settings start them without the folder's OK.
+- **Managed settings** also take `allowManagedPermissionRulesOnly`, `allowManagedHooksOnly` and
+  `disableAllHooks`, and the sandbox's `network.allowUnixSockets` and `allowAllUnixSockets`. Keys
+  Tempr doesn't apply yet (such as `availableModels`, the other `sandbox` keys or `managed-mcp.json`)
+  get one warning at the start of a session.
+
+A folder's hooks, allow rules, additional directories, `env` variables, its entries in
+`allowedMcpServers`, `allowedHttpHookUrls` and `httpHookAllowedEnvVars`, and its `.mcp.json` servers
+are things someone else may have written, so they wait until you allow them for that folder, once
+(`tempr hooks allow`, or the prompt in a session), and again after any change. Its deny and ask
+rules apply at once.
+
+### Plugins
 
 **Plugins** are Claude Code's: bundles of commands, agents, skills, hooks, MCP servers and language
 servers, installed from Claude Code's marketplaces.
@@ -196,16 +307,18 @@ tempr plugin install <name>                 # its commands are /<plugin>:<name>,
 `enable`, `disable` and `uninstall` do what they say; `/plugin` in the REPL takes the same words, and
 `--plugin-dir <dir>` loads one from a folder for a session, for trying a plugin you're writing.
 
-**Hooks** use Claude Code's settings format, in `~/.tempr/settings.json` and the folder's
-`.tempr/settings.json`, `.claude/settings.json` and `.claude/settings.local.json`: PreToolUse,
-PostToolUse, UserPromptSubmit, Stop, SessionStart, SessionEnd, Notification, PreCompact and
-PostCompact, as commands or as prompts the model judges. `tempr hooks list` shows them.
+### Hooks
 
-A folder's hooks, allow rules and `.mcp.json` servers are commands someone else may have written,
-so they wait until you allow them for that folder, once (`tempr hooks allow`, or the prompt in a
-session), and again after any change. Lasting allow and deny rules for tools and paths
-(`Read(./.env)`, `Bash(git push:*)`) go in the same settings files; `/permissions` lists the ones in
-force.
+**Hooks** use Claude Code's settings format, in `~/.tempr/settings.json`, `~/.claude/settings.json`
+and the folder's `.tempr/settings.json`, `.claude/settings.json` and `.claude/settings.local.json`.
+Events: PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure,
+UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, SubagentStart, SubagentStop, SessionStart,
+SessionEnd, Notification, PreCompact, PostCompact, InstructionsLoaded, ConfigChange,
+DirectoryAdded, WorktreeCreate, WorktreeRemove, PreModelSwitch and PostModelSwitch. Handlers are
+commands, prompts or agents the model judges, `http` (the event POSTed to a URL, limited by
+`allowedHttpHookUrls` and `httpHookAllowedEnvVars`) and `mcp_tool` (a tool of one of the session's
+MCP servers); `"onFailure": "block"` makes a failing hook block. `tempr hooks list` and `/hooks` show
+them; `/hooks events` lists the events, and Claude Code's that Tempr doesn't raise, with why.
 
 **Code intelligence:** a language server from a plugin's `.lsp.json`, or under `"lspServers"` in
 `~/.tempr/settings.json`, starts the first time the agent edits a file it handles. The edit's result
@@ -214,8 +327,8 @@ carries the errors and warnings it reports, so the agent fixes them without a se
 
 ## Local models
 
-Models on your own machine or server -- Ollama, LM Studio, llama.cpp, vLLM or anything else that
-speaks OpenAI's chat API -- run here, talking to the server directly: nothing you send them goes
+Models on your own machine or server (Ollama, LM Studio, llama.cpp, vLLM or anything else that
+speaks OpenAI's chat API) run here, talking to the server directly: nothing you send them goes
 through Tempr's server, and they're free.
 
 Ollama (port 11434) and LM Studio (port 1234) are found when they're running; `tempr models` lists
@@ -257,7 +370,7 @@ tempr --json --yolo "fix the failing test" | tail -1 | jq '{status, summary, fil
 |---|---|
 | 0 | the turn finished |
 | 1 | something went wrong (server, network, tool, unhandled error) |
-| 2 | the command line didn't make sense |
+| 2 | the command line didn't make sense, or asked for something settings forbid (`--yolo` with autopilot turned off) |
 | 3 | not signed in, session expired, or no active plan |
 | 4 | hit the step limit with work still to do |
 | 5 | a tool call was refused and the turn carried on without it |
@@ -268,11 +381,12 @@ tempr --json --yolo "fix the failing test" | tail -1 | jq '{status, summary, fil
 Useful flags for an unattended run: `--max-turns`, `--max-cost` (stop once the run's model calls
 have cost this many dollars), `--allowed-tools`, `--disallowed-tools`, `--approval-mode`,
 `--prompt-file`, and `--search` to let the model search the web, which a script doesn't do unless
-asked. The first `--json` line is a `session` object (session id, model, settings), and each tool the
-CLI runs locally adds a `tool-result` line with its output. Sign in with `TEMPR_LICENSE_KEY` rather than on a command line,
-where the key would land in shell history and in every process listing on the machine. Setting `CI`
-turns off the logo, the update check and crash reports, and makes any call that would have asked a
-question refuse instead of waiting.
+asked. The first `--json` line is a `session` object (session id, model, environment, settings), and
+each tool the CLI runs locally adds a `tool-result` line with its output. A one-shot run waits for
+its background sub-agents and hands their results to the agent before it exits. Sign in with
+`TEMPR_LICENSE_KEY` rather than on a command line, where the key would land in shell history and in
+every process listing on the machine. Setting `CI` turns off the logo, the update check and crash
+reports, and makes any call that would have asked a question refuse instead of waiting.
 
 There's a GitHub Action at the repository root; `docs/examples/tempr-agent-workflows.md` has a
 PR-review workflow and a fix-the-build workflow built on it.
@@ -295,9 +409,10 @@ In JetBrains IDEs, the same entry goes under `agent_servers` in `~/.jetbrains/ac
 full path to `tempr` as the command; AI Chat's ⋮ menu > Add Custom Agent opens that file.
 
 The editor shows Tempr's replies, its tool calls (edits as diffs) and its questions, and you answer
-them there. Tempr runs its tools itself, so the allow-list, the approval mode and, on Linux, the
-[sandbox](#sandbox-linux) work as they do here; autopilot in an editor counts like `--yolo`. Sign in
-with `tempr auth` first, or from the editor, which offers the browser sign-in.
+them there. Tempr runs its tools itself, so the allow-list, the approval mode, your settings and, on
+Linux and macOS, the [sandbox](#sandbox-linux-and-macos) work as they do here; autopilot in an
+editor counts like `--yolo`. Sign in with `tempr auth` first, or from the editor, which offers the
+browser sign-in.
 
 - **Sessions** are saved like any other, so `tempr history` lists them and `tempr -c` in the same
   folder carries one on. The editor's own session list shows them too, and opening one there
@@ -306,10 +421,11 @@ with `tempr auth` first, or from the editor, which offers the browser sign-in.
   A new session starts on the model last picked in an editor, or on your default until you pick one
   (`tempr config set-model` makes the default the starting model again). A reasoning level is kept
   per model, as `/reasoning` keeps it.
-- **Slash commands:** your command templates, plus `/undo`, `/diff`, `/agents` and `/compact`.
+- **Slash commands:** your command templates, plus `/undo`, `/diff`, `/agents`, `/compact` and
+  `/code-review`, and each running MCP server's prompts as `/mcp__server__prompt`.
 - **Thinking:** a model's reasoning shows as the agent's thoughts, in editors that show them.
-- **MCP servers** the editor passes run beside yours from `~/.tempr/mcp.json`; one with the same name
-  as one of yours takes its place for the session.
+- **MCP servers** the editor passes (local, HTTP or SSE) run beside yours from `~/.tempr/mcp.json`;
+  one with the same name as one of yours takes its place for the session.
 - **Command output** streams into a terminal under the call, in editors that draw one (Zed); in
   others it shows when the command ends.
 - **Sub-agents** answer under the call that delegated to them, apart from the reply.
@@ -317,6 +433,38 @@ with `tempr auth` first, or from the editor, which offers the browser sign-in.
 It passes the ACP conformance kit ([acp-tck](https://github.com/agentclientprotocol/acp-tck)). The
 setup for each editor is at <https://temprhq.io/docs/cli-editors>.
 
+## Monitoring (OpenTelemetry)
+
+Tempr exports metrics and events to your own OpenTelemetry collector, set up as Claude Code's
+[monitoring](https://code.claude.com/docs/en/monitoring-usage) is, with the same variables, in the
+environment or in `env` of `~/.tempr/settings.json` (a folder's settings can't turn it on). It's off
+unless you set it up, and nothing of it goes to Tempr.
+
+```sh
+export CLAUDE_CODE_ENABLE_TELEMETRY=1        # or TEMPR_ENABLE_TELEMETRY=1
+export OTEL_METRICS_EXPORTER=otlp            # otlp, console (stderr) or none
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_PROTOCOL=grpc      # or http/protobuf (the default)
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"
+```
+
+- **Metrics** (meter `io.temprhq.tempr`): `tempr.session.count`, `tempr.token.usage`,
+  `tempr.cost.usage`, `tempr.lines_of_code.count`, `tempr.commit.count`, `tempr.pull_request.count`,
+  `tempr.code_edit_tool.decision` and `tempr.active_time.total`, with Claude Code's attributes
+  (`claude_code.` becomes `tempr.`).
+- **Events:** `tempr.user_prompt`, `tempr.tool_result`, `tempr.tool_decision`, `tempr.api_request`
+  and `tempr.api_error`. A prompt's text is `<REDACTED>` unless `OTEL_LOG_USER_PROMPTS=1`; tool
+  parameters and MCP tool names go only with `OTEL_LOG_TOOL_DETAILS=1`.
+- Also read: the per-signal `OTEL_EXPORTER_OTLP_METRICS_*` and `_LOGS_*` endpoint, protocol and
+  headers, `OTEL_METRIC_EXPORT_INTERVAL` (60000 ms), `OTEL_LOGS_EXPORT_INTERVAL` (5000 ms),
+  `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` (delta), `OTEL_RESOURCE_ATTRIBUTES` and
+  `OTEL_METRICS_INCLUDE_SESSION_ID` / `_VERSION` / `_ACCOUNT_UUID`.
+- Unlike Claude Code: no Prometheus exporter (have the collector serve one), `http/json` is sent as
+  `http/protobuf`, and there are no traces.
+
+The same export works in `tempr acp` and in Tempr Code (`~/.tempr-code/settings.json`).
+
 ## What leaves your machine
 
 Everything below goes to your Tempr server (`api.temprhq.io` unless the `TEMPRAPP_SERVER_URL`
@@ -327,8 +475,9 @@ and Tempr's server doesn't see it.
 **Sent on every turn you send**
 
 - Your message, and the conversation so far in this session.
-- `AGENTS.md`, `.github/copilot-instructions.md`, `CLAUDE.md`, `GEMINI.md` and Cursor rules from the
-  current directory, and `~/.tempr/AGENTS.md`, up to 16 KB combined.
+- `AGENTS.md`, `.github/copilot-instructions.md`, Claude Code's memory files (`CLAUDE.md` at every
+  level, `.claude/rules` and their imports), `GEMINI.md` and Cursor rules, and `~/.tempr/AGENTS.md`,
+  up to 64 KB combined.
 - Files you attach with `@path`, including images, and anything `@workspace` or `@problems` pulls
   in (a workspace overview, or your current build errors).
 - The contents of files the agent reads or searches, as tool results.
@@ -352,7 +501,8 @@ and Tempr's server doesn't see it.
 
 - Your license key after sign-in (it is exchanged once for a session token).
 - Any file the agent didn't read, and any command output you didn't approve.
-- Telemetry: there is none beyond the requests above.
+- Telemetry: none goes to Tempr beyond the requests above. The [OpenTelemetry export](#monitoring-opentelemetry),
+  when you turn it on, goes only to the collector you name.
 
 See `tempr --help` for the full command reference, and `docs/plans/plan-tempr-cli-v1-roadmap.md` in
 the Tempr repo for design notes.

package/package.json

@@ -1,17 +1,17 @@
 {
     "name": "@tempr/cli",
-    "version": "0.9.21",
+    "version": "0.9.23",
     "description": "Sign in, chat, and run agentic coding tasks against your Tempr license from the terminal.",
     "homepage": "https://temprhq.io",
     "license": "SEE LICENSE IN README.md",
     "bin": { "tempr": "bin/tempr.js" },
     "files": ["bin/"],
     "optionalDependencies": {
-        "@tempr/cli-win32-x64": "0.9.21",
-        "@tempr/cli-win32-arm64": "0.9.21",
-        "@tempr/cli-linux-x64": "0.9.21",
-        "@tempr/cli-linux-arm64": "0.9.21",
-        "@tempr/cli-darwin-x64": "0.9.21",
-        "@tempr/cli-darwin-arm64": "0.9.21"
+        "@tempr/cli-win32-x64": "0.9.23",
+        "@tempr/cli-win32-arm64": "0.9.23",
+        "@tempr/cli-linux-x64": "0.9.23",
+        "@tempr/cli-linux-arm64": "0.9.23",
+        "@tempr/cli-darwin-x64": "0.9.23",
+        "@tempr/cli-darwin-arm64": "0.9.23"
     }
 }