command-code 0.52.5 → 1.0.0

package/dist/bundled/command-code-knowledge/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: command-code-knowledge
+description: Authoritative Command Code product knowledge — slash commands, CLI options, permissions, skills, custom agents, MCP servers, hooks, memory, headless mode, plan mode, checkpoints, sessions, the model catalog, taste, pricing, and troubleshooting. Use when the user asks how Command Code works, how to configure or extend it, which models exist, or when you need product facts to answer a "can Command Code do X" question. Do NOT search the codebase for product behavior — read the reference files here instead.
+---
+
+# Command Code Knowledge
+
+You are answering a question about Command Code itself (or configuring/extending it). The
+`reference/` directory next to this file IS the authoritative product documentation — it is
+generated from the public docs (commandcode.ai/docs) and from the same registries that drive
+the product (`/model` catalog, billing tables, slash-command menu), so it can never be more
+wrong than the product. Never guess and never grep the codebase for product behavior: open
+the matching reference file.
+
+## How to use this skill
+
+1. Pick the reference file(s) below that cover the question and read them.
+2. Answer from what they say; quote exact ids, flags, paths, and settings keys verbatim.
+3. Model questions (which model, exact ids, context windows, efforts, prices): read
+   `reference/models.md` — ids there are EXACT; never invent a model id.
+4. Anything about the help surface (slash commands, keyboard shortcuts, CLI flags, taste,
+   FAQ, pricing links): `reference/product-help.md` — the same document the
+   `get_command_code_knowledge` tool serves.
+5. Building a mod (a loadable ModApi plugin)? Switch to the `mod-builder` skill — it has
+   the mods reference and runnable examples.
+
+## Reference index
+
+<!-- generated:reference-index:start -->
+- `reference/permissions.md` — Permissions
+- `reference/skills.md` — Agent Skills
+- `reference/mcp.md` — MCP Servers
+- `reference/hooks.md` — Hooks
+- `reference/custom-slash-commands.md` — Slash Commands
+- `reference/custom-agents.md` — Custom Agents
+- `reference/memory.md` — Memory
+- `reference/headless.md` — Headless Mode
+- `reference/plan-mode.md` — Plan Mode and Auto-Accept Mode
+- `reference/checkpoints.md` — Checkpoints
+- `reference/models.md` — Command Code Models
+- `reference/product-help.md` — Product help (slash commands, CLI, taste, FAQ, pricing)
+<!-- generated:reference-index:end -->
+
+## Verify your answer
+
+- Ids and flags must appear verbatim in a reference file — if you cannot find it, say so
+  rather than inventing it.
+- When the user should run something, prefer the exact command a reference file shows
+  (e.g. `cmd mcp add --transport http …`, `cmd --mod ./file.ts`).
+- These files regenerate from the docs via `pnpm generate:knowledge`; if the user reports a
+  mismatch with the live product, the public docs at https://commandcode.ai/docs are the
+  place to check.

package/dist/bundled/command-code-knowledge/reference/checkpoints.md

@@ -0,0 +1,366 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/core-concepts/checkpoints/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Sessions & Checkpoints
+
+Every conversation you have with Command Code is a **session**: a durable transcript on disk that you can resume, rename, fork, clone, rewind, share, and export. Close your terminal mid-task, come back tomorrow, and pick up exactly where you left off.
+
+---
+
+## What is a session?
+
+A session is a single append-only **JSONL file** — one JSON record per line. The first line is a header (session id, creation time, working directory); every line after it is an entry: your messages, the model's replies (with token usage and cost), model and effort changes, compaction summaries, and more.
+
+Entries form a **tree**, not just a list. Each entry points at its parent, so a session can hold multiple branches of the same conversation — this is what powers `/rewind`, `/tree`, and forking. The file itself is never rewritten in place: navigating history just moves a pointer, and new entries are appended.
+
+### Where session files live
+
+Sessions are stored per project, keyed by a slug of the working directory:
+
+```text  theme={null}
+~/.commandcode/projects/<project-slug>/<session-id>.jsonl
+```
+
+Because the catalog is project-scoped, `/resume` and `--continue` only ever see sessions from the directory you launched Command Code in.
+
+Alongside the transcript, a session can have sidecar files:
+
+| **File** | **Contents** |
+| -------- | ------------ |
+| `<id>.jsonl` | The transcript itself (header + entries) |
+| `<id>.meta.json` | Title, model, lineage, trace ids, compaction stats |
+| `<id>.share.json` | Share link state, if the session was shared |
+| `<id>.checkpoints.jsonl` | Checkpoint snapshots for `/rewind` |
+| `<id>.prompts.jsonl` | Prompt history |
+
+### Finding the current session file
+
+```bash
+# In Command Code session
+/session-file
+```
+
+`/session-file` prints the current session id and the absolute path of its transcript. In terminals that support hyperlinks the path is clickable. If you haven't sent a message yet you'll see a `(not created yet)` note — the transcript is created on the first save.
+
+---
+
+## Durability and crash safety
+
+Sessions are designed so you never lose committed work:
+
+- **Per-turn commit:** Every completed turn is appended to the transcript as it commits — not on exit. Kill the process mid-run and everything up to the last committed turn is on disk.
+- **A turn either commits or is lost:** There is no torn state: an interrupted turn simply doesn't make it into the file, and the session resumes cleanly from the previous commit.
+- **User messages survive failed turns:** If a turn dies on a model/API error, your message that opened it is still written to disk — so a session that errored on its very first turn still shows up in `/resume`.
+- **Empty sessions leave no file:** A brand-new session buffers in memory until the first assistant reply, so opening Command Code and quitting without a real exchange doesn't litter your session catalog.
+- **Torn files never block startup:** If a transcript is damaged, corrupted lines are skipped and the session still loads.
+
+---
+
+## Starting fresh
+
+### In a session: `/clear`
+
+```bash
+# In Command Code session
+/clear
+```
+
+`/clear` starts a new session with empty context. The previous session stays on disk, fully resumable with `/resume`. `/new` is an alias — same command, same menu row.
+
+### At launch
+
+| **Flag** | **What it does** |
+| -------- | ---------------- |
+| `-n, --name <name>` | Set the new session's display name at startup |
+| `--no-session` | Don't persist the session to disk at all (in-memory only) |
+
+```bash
+cmd -n "auth refactor"        # named session
+cmd --no-session              # throwaway session, nothing written to disk
+```
+
+  `--no-session` sessions never appear in `/resume` and leave no transcript. Use them for experiments you explicitly don't want in your history.
+
+---
+
+## Resuming
+
+### The resume picker
+
+```bash
+# In Command Code session
+/resume
+```
+
+`/resume` (alias `/sessions`) opens the session picker — the same picker you get from `cmd -r` with no argument. It supports search, renaming (without leaving the picker), deleting sessions, and filtering by the git branch a session was started on. Forked sessions show their provenance (`fork of <parent>`), and the session you're currently in is highlighted and can't be deleted.
+
+Two kinds of sessions are hidden from the picker:
+
+- **Headless (`cmd -p`) sessions** — they carry no title and stay out of the picker and `--continue`, but an exact session id still resumes them.
+- **In-memory (`--no-session`) sessions** — they were never written to disk.
+
+### At launch
+
+| **Flag** | **What it does** |
+| -------- | ---------------- |
+| `-r, --resume [name]` | Resume a session by id or name; with no argument, open the picker |
+| `--sessions [name]` | Alias of `--resume` |
+| `-c, --continue` | Continue the most recent session in the current directory |
+| `--session <path\|id>` | Resume by transcript path (`.jsonl`) or a unique session-id prefix |
+| `--fork-session` | With `--resume`/`--continue`/`--session`: fork the resolved session into a new one, leaving the original untouched |
+
+```bash
+cmd -r                        # open the resume picker
+cmd -r "auth refactor"        # resume by name (or id) — id is tried first, then a case-insensitive title match
+cmd -c                        # continue the most recent session here
+cmd --session 3f9a            # unique id prefix
+cmd --session ~/exported/session.jsonl   # a transcript file directly
+cmd -c --fork-session         # branch off the latest session without touching it
+```
+
+A `--session` path inside the current project resumes like `-r`; a path outside it keeps appending to that file where it is.
+
+### Model restored on resume
+
+The model a session was using is stored in its meta and **adopted when you resume**. An in-session `/resume` always adopts the resumed session's model (clearing any `--model` launch override so the resumed model wins); a cold `cmd -r` adopts it unless you explicitly passed `--model` for that launch.
+
+---
+
+## Branching
+
+Three commands let one conversation become many.
+
+### `/fork [name]` — copy everything
+
+```bash
+# In Command Code session
+/fork
+/fork payments-experiment
+```
+
+`/fork` copies the **entire session** — the full tree with every branch, plus checkpoints and file backup history, so `/rewind` keeps working in the fork — into a new session and switches to it. The original is left untouched and resumable.
+
+Lineage is recorded on the fork's meta: `parentSessionId` (the source session) and `branchPoint` (the stable message id of the last source message at the fork point), so the picker can render `fork of <parent>` provenance. Names are optional (up to 200 characters) and must be unique.
+
+### `/clone` — copy the current branch only
+
+```bash
+# In Command Code session
+/clone
+```
+
+`/clone` duplicates just the **active branch** of the conversation (from the current point back to the root) into a brand-new session file and switches into it. Unlike `/fork`, checkpoints and file history are deliberately not copied — a clone is "duplicate the conversation", and `/rewind` in the clone legitimately starts empty. The new file's header records the source transcript as its `parentSession`.
+
+### `/tree` — browse the whole tree
+
+```bash
+# In Command Code session
+/tree
+```
+
+`/tree` opens the session-tree navigator: every branch of the session, not just the active one. From there you can jump to **any point** in the tree, fold segments, search, attach labels to entries, and cycle display filters (`default`, `no-tools`, `user-only`, `labeled-only`). When you navigate away from a branch, Command Code can generate a **branch summary** so the work you're leaving behind stays findable — you can confirm, customize, or skip the summary (and set a default in `/config`).
+
+---
+
+## Naming and session info
+
+| **Command** | **What it does** |
+| ----------- | ---------------- |
+| `/rename <name>` | Rename the current session; bare `/rename` auto-generates a title with the model |
+| `/name` | Alias of `/rename`; bare `/name` shows the current name |
+| `/session` | Show session info: id, name, model, message counts, tree entries, tokens, cost, context usage, transcript path |
+| `/session-file` | Show the current session id and transcript path |
+| `/status` | Show comprehensive environment status |
+| `/trace` | Copy the current OpenTelemetry trace id (for support); works mid-turn, and persisted trace ids survive resume |
+
+Names must be unique within a project — renaming to a taken name is rejected. The name also becomes your terminal tab title, and it's what `-r <name>` resolves.
+
+---
+
+## Checkpoints and rewind
+
+Every prompt you send opens a **checkpoint**: a snapshot of the conversation plus a backup of every file Command Code goes on to edit. If something goes off track, rewind to any earlier checkpoint and continue from there.
+
+### Opening the rewind UI
+
+Press **`Esc`** twice within 500ms, or run:
+
+```bash
+/rewind
+```
+
+Each row in the selector shows when the checkpoint was taken, a preview of the message that opened it, and how many files that checkpoint changed (or `No code changes`).
+
+### Restore modes
+
+| Mode | What it restores |
+| ---- | ----------------- |
+| **Both** | Restores conversation and code together (recommended). |
+| **Conversation only** | Removes messages after the checkpoint. Files are untouched. |
+| **Code only** | Restores files to their state at the checkpoint. Conversation is untouched. |
+
+Checkpoints with no file changes only offer **Conversation only**.
+
+Rewinding removes the messages after the checkpoint **and the checkpoint itself** — you land *before* the message that opened it. The context token count updates to reflect the shorter conversation.
+
+Rewinds persist. If you rewind and then quit, the rewound state is what you'll see when you resume the session later — it isn't a preview.
+
+### What a file rewind does to your working tree
+
+A **Code only** or **Both** rewind doesn't just undo edits — it puts the tree back the way it was:
+
+| If a file was… | After the rewind |
+| -------------- | ---------------- |
+| **Modified** after the checkpoint | Restored to its contents at the checkpoint |
+| **Created** after the checkpoint | **Deleted** — it didn't exist at the checkpoint |
+| **Deleted** after the checkpoint | Restored |
+
+Backups are taken before each `write_file` or `edit_file` call and replayed newest-first, so a run of edits to the same file lands back on its oldest state. Backups are byte-faithful, so binary files (images, compiled artifacts) survive a backup–restore round-trip unchanged — no special handling needed.
+
+### Restores are verified before they run
+
+Command Code checks every backup in the set can actually be restored *before* writing anything, so a rewind either applies in full or not at all — it won't leave you half-restored. If a file can't be restored, you're told which one and why.
+
+### Limits and pausing
+
+Checkpoints are kept for **30 days**, capped at **200 backups per session**. Backups live in `~/.commandcode/file-history/<session-id>/`, and identical content is stored once no matter how many checkpoints reference it.
+
+File backups are capped at **10MB per file**. An oversized file is never read or backed up — and because it was never captured, a rewind **leaves it exactly as it is** rather than deleting it. Once a session hits the 200-backup cap, or 30 days pass, older checkpoints age out.
+
+If the disk runs low, checkpointing **pauses for the whole session** rather than silently degrading file by file, and you'll see a notice. Checkpoints already taken stay usable, and checkpointing resumes on its own — with a second notice — once enough space is free.
+
+---
+
+## Session scratchpad
+
+Each session gets a **scratchpad**: a per-session temporary workspace for intermediate files — analysis notes, throwaway scripts, generated data — that don't belong in your project.
+
+```text  theme={null}
+/tmp/commandcode-<uid>/<sanitized-cwd>/<session-id>/scratchpad
+```
+
+- **Silent access:** Reads and writes inside the scratchpad need no permission prompts (explicit deny/ask rules still take precedence). The path is advertised in the system prompt and exported to shell commands as `$COMMANDCODE_SCRATCHPAD`.
+- **Shared with sub-agents:** Every sub-agent in the session sees the same directory, so agents can hand intermediate results to each other by file name.
+- **Survives compaction:** After history compaction, a bounded metadata-only **manifest** of the scratchpad is re-injected, so the model remembers which working files still exist on disk without re-reading them.
+- **Follows launch-time forks:** Forking at launch with `--fork-session` copies the source session's scratchpad into the fork, so the branched conversation keeps its working files.
+- **Cleaned up with retention:** Scratchpads older than 30 days are swept, and deleting a session deletes its scratchpad. It's temp space — keep durable deliverables in the project itself.
+
+The whole tree can be relocated with the `COMMANDCODE_SCRATCHPAD_BASE` environment variable. Provisioning is fail-open: if the scratchpad can't be created safely, the feature silently disables and the session runs normally without it.
+
+Disable it entirely in `settings.json`:
+
+```json
+{
+  "disableScratchpad": true
+}
+```
+
+---
+
+## Sharing and exporting
+
+### `/share` — live share link
+
+```bash
+# In Command Code session
+/share
+```
+
+`/share` uploads the conversation, copies a share URL to your clipboard, and — this is the key part — keeps the shared page **live**: every turn committed after sharing is streamed to the link automatically. Resuming a previously shared session re-arms the live updates. Run `/share` again to re-copy the existing link.
+
+```bash
+# In Command Code session
+/unshare
+```
+
+`/unshare` deletes the share and stops the live updates.
+
+### `/share gist` — GitHub gist
+
+```bash
+# In Command Code session
+/share gist            # secret gist, default format (html unless configured)
+/share gist md         # markdown
+/share gist jsonl      # raw transcript
+```
+
+`/share gist [html|jsonl|md]` renders the session and posts it as a **secret GitHub gist** via the `gh` CLI, then copies the gist URL. The default format comes from `/config`'s "Default share gist format" setting.
+
+### `/export` — write a file
+
+```bash
+# In Command Code session
+/export                          # default format to a generated filename
+/export md                       # pick a format: html | jsonl | md
+/export ~/notes/session.html     # or a path; the extension picks the format
+```
+
+With no path, the file is written as `command-code-session-<first 8 chars of id>.<format>` using `/config`'s "Default export format" (`html` when unset). `jsonl` exports the raw transcript.
+
+### `/copy` — clipboard
+
+```bash
+# In Command Code session
+/copy
+```
+
+`/copy` copies the last assistant reply to the clipboard. Best-effort: in headless/SSH terminals without clipboard access, the feed line tells you it couldn't.
+
+---
+
+## Compaction and the session log
+
+When the conversation approaches the context limit, Command Code compacts history (automatically, or on `/compact`). Two guarantees matter for sessions:
+
+- **The on-disk log is never rewritten:** Compaction appends a compaction entry (the summary plus a pointer to the first entry kept verbatim) to the transcript tree. Your full history stays in the file — context building just reads through the compaction entry, and `/tree` can still reach everything.
+- **Savings persist across resumes:** Cumulative compaction stats (event count, total tokens saved, last event) are written to the session's meta on every compaction, so the "total this session" figure `/compact` reports survives `--resume`.
+
+---
+
+## Design decisions
+
+- **One picker, not two.** `/resume` and `/sessions` open the same unified picker rather than separate interactive/print views, so there's one mental model for "where are my sessions."
+- **Rewind is destructive on purpose, but reversible.** Restoring is instant and irreversible in the moment, but because it's just moving between checkpoints, you can rewind forward again if you change your mind.
+- **Print sessions are real sessions.** They're saved and resumable, just hidden from the picker by default — automation output doesn't have to mean throwaway state.
+
+---
+
+## Troubleshooting
+
+### Checkpoints not appearing
+
+1. Ensure you've sent at least one message in the session
+2. Check if checkpointing is paused (you'll have seen a disk-space notice)
+3. Verify the session has file modifications — a checkpoint with no file changes only offers a conversation restore
+
+### Restore failed
+
+1. Check the error message for which file failed
+2. Ensure backup files haven't been manually deleted from `~/.commandcode/file-history/`
+3. Verify you have write permissions to the target files
+
+### Double-Esc not working
+
+1. Press Esc twice within 500ms
+2. Ensure focus is on the Command Code input
+3. Use `/rewind` instead
+
+---
+
+## Tips
+
+- **Name sessions you'll come back to:** `/rename auth-refactor` (or launch with `-n`) makes `cmd -r auth-refactor` a one-liner later — and a bare `/rename` will generate a decent title for you.
+- **Fork before risky experiments:** `cmd -c --fork-session` or `/fork` gives you a full copy — checkpoints included — while the original stays pristine.
+- **Use `/clone` to tidy up:** After heavy rewinding, `/clone` extracts just the branch you kept into a clean new session.
+- **Label important points in `/tree`:** Labels survive forks and make long trees navigable.
+- **Let the scratchpad absorb clutter:** Ask for throwaway scripts and intermediate outputs in the scratchpad — no permission prompts, no files polluting your repo, and it's cleaned up automatically.
+- **`/share` before pairing:** The link updates live as the session continues, so a teammate can follow along in real time.
+- **Grab `/trace` when something breaks:** The trace id is what support needs, it's copyable mid-turn, and past ids survive a resume.
+
+---
+
+## See also
+
+- [Headless Mode](./headless.md) — resuming and naming sessions from scripts and CI.
+- [Interactive Mode](https://commandcode.ai/docs/core-concepts/interactive-mode) — the full session experience.
+- [Context & Compaction](https://commandcode.ai/docs/core-concepts/context) — how history is summarized as it grows.
+- [Permissions](./permissions.md) — how permission decisions apply as you resume or fork a session.

package/dist/bundled/command-code-knowledge/reference/custom-agents.md

@@ -0,0 +1,91 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/core-concepts/custom-agents/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Custom Agents
+
+Custom agents are specialized **subagents** Command Code can delegate to. Each one gets its own context window, **system prompt**, and **tool** set, so you can keep exploration, planning, or niche workflows separate from the main session.
+
+Built-in defaults (**Explore** and **Plan**) are always available. Your definitions live alongside them as Markdown files in **project** `.commandcode/agents/` or **personal** `~/.commandcode/agents/`.
+
+---
+
+## Open the agents manager
+
+In [interactive mode](https://commandcode.ai/docs/core-concepts/interactive-mode), run:
+
+```text
+/agents
+```
+
+This opens the agents screen: your custom agents (if any), **Create new agent**, and the default agents list.
+
+---
+
+## Create a new agent
+
+Choose **Create new agent**, then walk through the wizard.
+
+### 1. Choose where it lives
+
+| **Scope** | **Path** | **When to use** |
+| --------- | -------- | --------------- |
+| **Project** | `.commandcode/agents/` in the current repo | Shared with the team; commit in Git. |
+| **Personal** | `~/.commandcode/agents/` | Available in every project on your machine. |
+
+### 2. Choose how to build it
+
+| **Option** | **Description** |
+| ---------- | --------------- |
+| **Generate with Command Code (recommended)** | Describe the agent’s role and when to use it; Command Code drafts configuration for you. |
+| **Manual configuration** | Set the identifier, system prompt, “when to use” description, and tools yourself. |
+
+### 3. Generate: write a thorough description
+
+If you chose **Generate with Command Code**, you’ll see a prompt like the one below. The more specific you are about responsibilities, boundaries, and when delegation should happen, the better the result.
+
+Command Code will automatically generate:
+
+- **Agent name**
+- **Description** (when to use it)
+- **System prompt**
+
+You only need to review them, choose which **tools** the agent should have access to, and pick which **model** it runs on (or keep the default of inheriting the session model).
+
+After generation, you’ll confirm tools and save. Manual creation follows the same tool-selection and confirmation steps, but you’ll enter the **name**, **description**, and **system prompt** yourself.
+
+---
+
+## Agent files (manual editing)
+
+Each agent is a **Markdown file** with YAML front matter and a body that becomes the **system prompt**.
+
+- **`name`** — Identifier and filename (e.g. `security-review.md` → agent `security-review`).
+- **`description`** — Tells Command Code **when** to use this agent.
+- **`tools`** — Comma-separated tool list, **`"*"`** for all tools, or a restriction such as read-only style lists.
+- **`model`** — Optional model this agent always runs on (any `/model` id, e.g. `deepseek/deepseek-v4-pro` or `claude-sonnet-5`). Omit it or set `model: inherit` to follow the session's current model. Per-agent models let you pin deep-reasoning models to architect/planner agents while implementation or docs agents ride faster, cheaper ones — each keeps its own prompt cache.
+
+Do not use reserved names for custom agents: `explore`, `plan`, `review`, and `general`. Those names are reserved for built-in or internal behavior; custom files with those names are ignored.
+
+Example shape:
+
+**Example agent file**
+```markdown
+---
+name: "security-review"
+description: "Use for dependency and secret-scanning review before release."
+tools: "glob, grep, read_file, think"
+model: "claude-sonnet-5"
+---
+
+You are a security-focused reviewer. Prioritize dependency risks, secrets in code,
+and unsafe patterns. Be concise; cite file paths and lines.
+```
+
+You can edit files directly in `.commandcode/agents/` or `~/.commandcode/agents/`, or recreate them through `/agents`.
+
+---
+
+## Next steps
+
+- [Interactive mode](https://commandcode.ai/docs/core-concepts/interactive-mode) — slash commands and session controls
+- [Memory](./memory.md) — project and user instructions in `AGENTS.md`
+- [Skills](./skills.md) — reusable skill packages vs. full subagents