@code-yeongyu/senpi 0.74.0

package/dist/utils/version-check.js

@@ -0,0 +1,78 @@
+import { PACKAGE_NAME } from "../config.js";
+import { getPiUserAgent } from "./pi-user-agent.js";
+const LATEST_VERSION_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;
+function parsePackageVersion(version) {
+    const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        major: Number.parseInt(match[1], 10),
+        minor: Number.parseInt(match[2], 10),
+        patch: Number.parseInt(match[3], 10),
+        prerelease: match[4],
+    };
+}
+export function comparePackageVersions(leftVersion, rightVersion) {
+    const left = parsePackageVersion(leftVersion);
+    const right = parsePackageVersion(rightVersion);
+    if (!left || !right) {
+        return undefined;
+    }
+    if (left.major !== right.major)
+        return left.major - right.major;
+    if (left.minor !== right.minor)
+        return left.minor - right.minor;
+    if (left.patch !== right.patch)
+        return left.patch - right.patch;
+    if (left.prerelease === right.prerelease)
+        return 0;
+    if (!left.prerelease)
+        return 1;
+    if (!right.prerelease)
+        return -1;
+    return left.prerelease.localeCompare(right.prerelease);
+}
+export function isNewerPackageVersion(candidateVersion, currentVersion) {
+    const comparison = comparePackageVersions(candidateVersion, currentVersion);
+    if (comparison !== undefined) {
+        return comparison > 0;
+    }
+    return candidateVersion.trim() !== currentVersion.trim();
+}
+export async function getLatestPiRelease(currentVersion, options = {}) {
+    if (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE)
+        return undefined;
+    const response = await fetch(LATEST_VERSION_URL, {
+        headers: {
+            "User-Agent": getPiUserAgent(currentVersion),
+            accept: "application/json",
+        },
+        signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        return undefined;
+    const data = (await response.json());
+    if (typeof data.version !== "string" || !data.version.trim()) {
+        return undefined;
+    }
+    const packageName = typeof data.packageName === "string" && data.packageName.trim() ? data.packageName.trim() : undefined;
+    return { version: data.version.trim(), packageName };
+}
+export async function getLatestPiVersion(currentVersion, options = {}) {
+    return (await getLatestPiRelease(currentVersion, options))?.version;
+}
+export async function checkForNewPiVersion(currentVersion) {
+    try {
+        const latestVersion = await getLatestPiVersion(currentVersion);
+        if (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {
+            return latestVersion;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=version-check.js.map

package/dist/utils/version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { PACKAGE_NAME } from \"../config.js\";\nimport { getPiUserAgent } from \"./pi-user-agent.js\";\n\nconst LATEST_VERSION_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n}\n\ninterface ParsedVersion {\n\tmajor: number;\n\tminor: number;\n\tpatch: number;\n\tprerelease?: string;\n}\n\nfunction parsePackageVersion(version: string): ParsedVersion | undefined {\n\tconst match = version.trim().match(/^v?(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+.*)?$/);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tmajor: Number.parseInt(match[1], 10),\n\t\tminor: Number.parseInt(match[2], 10),\n\t\tpatch: Number.parseInt(match[3], 10),\n\t\tprerelease: match[4],\n\t};\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = parsePackageVersion(leftVersion);\n\tconst right = parsePackageVersion(rightVersion);\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\n\tif (left.major !== right.major) return left.major - right.major;\n\tif (left.minor !== right.minor) return left.minor - right.minor;\n\tif (left.patch !== right.patch) return left.patch - right.patch;\n\tif (left.prerelease === right.prerelease) return 0;\n\tif (!left.prerelease) return 1;\n\tif (!right.prerelease) return -1;\n\treturn left.prerelease.localeCompare(right.prerelease);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestPiRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { packageName?: unknown; version?: unknown };\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName =\n\t\ttypeof data.packageName === \"string\" && data.packageName.trim() ? data.packageName.trim() : undefined;\n\treturn { version: data.version.trim(), packageName };\n}\n\nexport async function getLatestPiVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestPiRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewPiVersion(currentVersion: string): Promise<string | undefined> {\n\ttry {\n\t\tconst latestVersion = await getLatestPiVersion(currentVersion);\n\t\tif (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {\n\t\t\treturn latestVersion;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}

package/docs/agents.md

@@ -0,0 +1,348 @@
+> pi can create custom agents. Ask it to build one for your use case.
+
+# Agents
+
+Agents are typed subagent profiles that control which tools a spawned task can use and what system prompt it receives. Use agents to enforce read-only exploration, restrict dangerous operations, or create specialized task runners.
+
+## Table of Contents
+
+- [Built-in Agents](#built-in-agents)
+- [Using Agents](#using-agents)
+- [Custom Agents](#custom-agents)
+  - [Locations](#locations)
+  - [Frontmatter](#frontmatter)
+  - [Example](#example)
+- [Permissions](#permissions)
+  - [Permission Actions](#permission-actions)
+  - [Permission Config](#permission-config)
+  - [Evaluation Order](#evaluation-order)
+  - [Ask Mode](#ask-mode)
+- [Configuration](#configuration)
+  - [Directory Setup](#directory-setup)
+  - [Writing an Agent File](#writing-an-agent-file)
+  - [Settings](#settings)
+  - [Priority Order](#priority-order)
+  - [Quick Start Recipes](#quick-start-recipes)
+- [How It Works](#how-it-works)
+- [Known Limitations](#known-limitations)
+
+## Built-in Agents
+
+| Agent | Tools | System Prompt | Description |
+|-------|-------|---------------|-------------|
+| `general` | All except `task`, `todowrite` | Default pi prompt | General-purpose agent for parallel work |
+| `explore` | `read`, `grep`, `find`, `ls`, `bash` | File search specialist | Read-only codebase exploration |
+
+### general
+
+The default agent for complex multi-step tasks. It can use all tools except `task` and `todowrite` (to prevent nested subagent spawning and todo list conflicts).
+
+Permission config:
+
+```json
+{
+   "*": "allow",
+   "task": "deny",
+   "todowrite": "deny"
+}
+```
+
+### explore
+
+A read-only agent optimized for fast codebase exploration. It can search, read, and list files but cannot modify anything.
+
+Permission config:
+
+```json
+{
+   "read": "allow",
+   "grep": "allow",
+   "find": "allow",
+   "ls": "allow",
+   "bash": "allow"
+}
+```
+
+System prompt appended:
+
+```
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Guidelines:
+- Search file contents by regex or literal pattern when you need to locate usages or definitions
+- Read files directly when you already know the path
+- List directory contents to build a map of unfamiliar areas
+- Return file paths as absolute paths
+- Do not create any files or modify the system state
+Complete the search request efficiently and report findings clearly.
+```
+
+## Using Agents
+
+Pass `agent_type` when spawning a task:
+
+```typescript
+task(agent_type="explore", prompt="Find all files importing React", run_in_background=true)
+task(agent_type="general", prompt="Refactor the auth module", run_in_background=false)
+```
+
+Without `agent_type`, the task tool works exactly as before (no restrictions, full backward compat).
+
+## Custom Agents
+
+### Locations
+
+Pi loads custom agents from Markdown files in:
+
+- Global: `~/.senpi/agent/**/*.md` and `~/.senpi/agents/**/*.md`
+- Project: `.senpi/agent/**/*.md` and `.senpi/agents/**/*.md` (in current working directory)
+
+Both `agent/` and `agents/` directories are scanned recursively. The agent name is derived from the filename: `my-agent.md` becomes `my-agent`.
+
+**Name collision resolution:** Project-local agents override global agents with the same name.
+
+### Frontmatter
+
+Custom agents use YAML frontmatter (same format as skills):
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `description` | string | No | What this agent does and when to use it |
+| `mode` | string | No | `"subagent"`, `"primary"`, or `"all"` (default: `"all"`) |
+| `model` | string | No | Model ID for this agent (e.g., `"anthropic/claude-haiku-4-5"`) |
+| `temperature` | number | No | Sampling temperature 0-2 |
+| `tools` | object | No | Permission config (see below) |
+| `disable` | boolean | No | When `true`, agent is not loaded |
+
+**Mode values:**
+- `"subagent"` - Only runs as a task subagent (spawned via `task()`)
+- `"primary"` - Only runs in the main session (not as a subagent)
+- `"all"` - Can run in both contexts
+
+### Example
+
+Create `.senpi/agents/readonly.md`:
+
+```markdown
+---
+description: Read-only agent for safe codebase exploration
+mode: subagent
+tools:
+   read: allow
+   grep: allow
+   find: allow
+   ls: allow
+   bash: deny
+   write: deny
+   edit: deny
+---
+
+You are a read-only exploration agent. You can search and read files but cannot modify anything.
+
+Guidelines:
+- Use grep to search for code patterns
+- Use read to examine file contents
+- Use find and ls to navigate the filesystem
+- Never suggest file modifications
+- Report findings clearly and concisely
+```
+
+Use it:
+
+```typescript
+task(agent_type="readonly", prompt="Find all TODO comments in the codebase", run_in_background=true)
+```
+
+## Permissions
+
+### Permission Actions
+
+Three actions control tool access:
+
+- `allow` - Tool executes normally
+- `deny` - Tool blocked, LLM receives error message explaining the restriction
+- `ask` - In interactive mode, user is prompted to allow/deny. In non-interactive mode (json/print), auto-denied.
+
+### Permission Config
+
+The `tools` frontmatter field accepts two formats.
+
+**Simple format** - single action for all patterns:
+
+```yaml
+tools:
+   read: allow
+   bash: deny
+   edit: ask
+```
+
+**Nested format** - pattern-specific rules (for future extensibility):
+
+```yaml
+tools:
+   read:
+      "*": allow
+      "*.env": ask
+   bash: deny
+```
+
+Currently, pattern matching is not implemented for specific paths. The `"*"` pattern applies to all uses of that tool.
+
+### Evaluation Order
+
+Permissions are evaluated using `findLast` semantics: **later rules override earlier ones**.
+
+Merge order (later wins):
+
+1. Global defaults from `settings.json` (`agentDefaults.permission`)
+2. Built-in agent permissions (for built-in agents)
+3. Custom agent permissions (from frontmatter `tools`)
+
+Example: If global defaults set `"bash": "ask"` but a custom agent sets `"bash": "allow"`, the agent's explicit permission wins.
+
+### Ask Mode
+
+In **interactive mode**, when a tool with `"ask"` permission is called:
+
+1. TUI displays a select prompt: "Allow once / Allow always / Deny"
+2. "Allow once" permits this single call
+3. "Allow always" persists a matching approval rule to `.senpi/permissions-approved.jsonl`, so matching calls are auto-allowed after reload too
+4. "Deny" blocks with an error message
+
+In **non-interactive mode** (json or print output), `ask` permissions are auto-denied with an explanatory message.
+
+## Configuration
+
+### Directory Setup
+
+Create your agent directory structure:
+
+```
+# Project-local agents (recommended)
+.senpi/
+   agents/
+      my-agent.md
+      code-reviewer.md
+
+# Global agents (shared across projects)
+~/.senpi/
+   agents/
+      my-global-agent.md
+```
+
+Both `agent/` and `agents/` subdirectories are scanned recursively.
+
+### Writing an Agent File
+
+Agent files are Markdown with YAML frontmatter. The body (after `---`) becomes the agent's system prompt.
+
+```markdown
+---
+description: Strict code reviewer that only reads and analyzes
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.3
+tools:
+   read: allow
+   grep: allow
+   find: allow
+   ls: allow
+   bash: allow
+   edit: deny
+   write: deny
+   task: deny
+---
+
+You are a code review specialist. Analyze code for bugs, security issues, and style violations.
+
+Rules:
+- Never suggest modifying files directly
+- Always reference specific line numbers
+- Categorize issues as: critical, warning, or suggestion
+```
+
+### Settings
+
+Configure default permissions and model for all agents in `settings.json`.
+
+| Location | Scope |
+|----------|-------|
+| `~/.senpi/agent/settings.json` | Global (all projects) |
+| `.senpi/settings.json` | Project (overrides global) |
+
+Add the `agentDefaults` key:
+
+```json
+{
+   "agentDefaults": {
+      "permission": {
+         "write": "ask",
+         "edit": "ask",
+         "bash": "allow",
+         "read": "allow"
+      },
+      "model": "anthropic/claude-haiku-4-5"
+   }
+}
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `agentDefaults.permission` | object | `{}` | Default tool permissions for all agents (see [Permission Actions](#permission-actions)) |
+| `agentDefaults.model` | string | - | Default model ID for spawned agents |
+
+These defaults are the **lowest priority** layer. Agent-specific permissions (from frontmatter `tools`) override them.
+
+### Priority Order
+
+Permissions are resolved in this order (later wins):
+
+1. `settings.json` -> `agentDefaults.permission` (lowest priority)
+2. Built-in agent permissions (`general`, `explore` configs)
+3. Custom agent frontmatter `tools` (highest priority)
+
+Example: Global settings set `bash: ask`, but your custom agent sets `bash: allow` -> bash is allowed for that agent.
+
+### Quick Start Recipes
+
+**Read-only explorer:**
+```typescript
+task(agent_type="explore", prompt="Find all error handling patterns", run_in_background=true)
+```
+
+**Custom strict reviewer:**
+1. Create `.senpi/agents/reviewer.md` (see [Writing an Agent File](#writing-an-agent-file))
+2. Use: `task(agent_type="reviewer", prompt="Review changes in src/auth/", run_in_background=false)`
+
+**Restrict all agents by default:**
+Add to `~/.senpi/agent/settings.json`:
+```json
+{
+   "agentDefaults": {
+      "permission": {
+         "write": "ask",
+         "edit": "ask"
+      }
+   }
+}
+```
+Now every agent must get user confirmation before writing or editing files.
+
+## How It Works
+
+The agent system is implemented as a builtin extension that intercepts the task tool:
+
+1. **Environment variable** - When `task(agent_type="...")` is called, the agent type is passed via `SANEPI_AGENT_TYPE` environment variable to the subprocess
+2. **Registry lookup** - On session start, the extension scans `~/.senpi/` and `.senpi/` for agent definitions, merges with built-in agents, and resolves by name
+3. **Tool filtering** - `setActiveTools()` removes denied tools from the LLM's tool list entirely (they don't appear in the API call)
+4. **Defense in depth** - A `tool_call` event handler acts as backup, catching any tools that slip through (e.g., added dynamically after session start)
+5. **System prompt** - The `before_agent_start` event appends the agent's custom prompt to the existing system prompt (doesn't replace it)
+6. **Permission evaluation** - Each tool call is checked against the merged permission rules (global defaults + agent config)
+
+## Known Limitations
+
+- `disable: true` in custom agents does not currently remove built-in agents (v1 limitation)
+- Bash permission bypass: denying `edit` but allowing `bash` still permits `echo > file` via bash redirection
+- No sub-pattern matching for bash commands (entire bash tool allow/deny only, no per-command filtering)
+- `ask` mode in non-interactive (json/print) mode auto-denies without user input
+- No dynamic permission changes at runtime (permissions are immutable after agent start)
+- No agent permission inheritance chains (flat configs only, no "extends" mechanism)

package/docs/compaction-guide.md

@@ -0,0 +1,240 @@
+# Compaction Guide
+
+Pi's compaction system helps you work on complex tasks that would otherwise exceed the LLM's context window. This guide explains how compaction works from a user perspective and how to get the most out of it.
+
+## What is Compaction?
+
+LLMs have finite context windows. When conversations grow too long, pi uses compaction to summarize older messages while preserving recent ones. Think of it like taking notes during a long meeting: you write down the key decisions and next steps so you can continue the conversation without remembering every word that was said.
+
+Compaction happens automatically when needed, or you can trigger it manually with the `/compact` command.
+
+## How It Works
+
+### Automatic Compaction
+
+When the conversation approaches the context limit, pi automatically compacts older messages. You'll see a `[compaction]` message in the TUI with a summary like "Compacted from 45000 tokens". The conversation continues seamlessly.
+
+### Manual Compaction
+
+Use `/compact` to trigger compaction on demand. This is useful when:
+
+- You want to free up context before a complex operation
+- You're about to switch topics and want a clean slate
+- Auto-compaction hasn't triggered yet but you know the context is cluttered
+
+Add custom instructions to focus the summary: `/compact focus on the API design decisions`. The summarizer will prioritize that aspect.
+
+### What You See in the TUI
+
+When compaction occurs, you'll see:
+
+```
+[compaction] Compacted from 45000 tokens (Ctrl+O to expand)
+```
+
+Press `Ctrl+O` (or your configured expand keybinding) to view the full summary. The summary follows a structured format covering goals, progress, decisions, and next steps.
+
+### Your History is Never Lost
+
+Compaction only affects what the LLM sees in its context window. The full conversation history remains in your session file. Use `/tree` to navigate back to any point before compaction and see the complete, un-summarized history.
+
+## What Gets Preserved vs Lost
+
+### Preserved
+
+- Goals and objectives you've stated
+- Progress tracking (what's done, in progress, blocked)
+- Key decisions and their rationale
+- File paths and function names
+- Error messages and their resolutions
+- Next steps and action items
+- Critical context needed to continue
+
+### Potentially Lost
+
+- Exact wording of old messages
+- Nuanced tone or style preferences mentioned early
+- Very detailed tool output (summarized instead)
+- Transient discussion that didn't result in decisions
+
+### The Summary Format
+
+Compaction produces structured summaries in this format:
+
+```markdown
+## Goal
+What you're trying to accomplish
+
+## Constraints & Preferences
+Requirements and preferences you've mentioned
+
+## Progress
+### Done
+- [x] Completed tasks
+
+### In Progress
+- [ ] Current work
+
+### Blocked
+Any issues
+
+## Key Decisions
+- **[Decision]**: Rationale
+
+## Next Steps
+1. What should happen next
+
+## Critical Context
+Data needed to continue
+
+<read-files>
+path/to/file1.ts
+</read-files>
+
+<modified-files>
+path/to/changed.ts
+</modified-files>
+```
+
+## Branch Summarization
+
+When you use `/tree` to switch to a different branch, pi offers to summarize the work you're leaving behind. This injects context from the abandoned branch into your new position.
+
+### User Experience
+
+After selecting a target in `/tree`, pi asks: "Summarize branch?" You have three options:
+
+1. **No summary** - Switch immediately
+2. **Summarize** - Generate a summary using the default prompt
+3. **Summarize with custom prompt** - Add focus instructions
+
+The summary appears as a `branch_summary` entry in your new branch, providing context about what was explored on the path you left.
+
+### Skipping the Prompt
+
+If you frequently switch branches and don't want the prompt, set `branchSummary.skipPrompt: true` in your settings. Pi will switch branches without asking.
+
+## Settings & Tuning
+
+Configure compaction in `~/.senpi/agent/settings.json` (global) or `.senpi/settings.json` (project):
+
+```json
+{
+   "compaction": {
+      "enabled": true,
+      "reserveTokens": 16384,
+      "keepRecentTokens": 20000
+   },
+   "branchSummary": {
+      "reserveTokens": 16384,
+      "skipPrompt": false
+   }
+}
+```
+
+### Compaction Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `compaction.enabled` | `true` | Enable auto-compaction. Set to `false` for manual control only. |
+| `compaction.reserveTokens` | `16384` | Tokens reserved for the LLM's response. Lower values allow more context but risk truncation. |
+| `compaction.keepRecentTokens` | `20000` | How much recent conversation to keep uncompressed. Higher values preserve more context but trigger compaction sooner. |
+
+### Branch Summary Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `branchSummary.reserveTokens` | `16384` | Tokens reserved when generating branch summaries |
+| `branchSummary.skipPrompt` | `false` | Skip the "Summarize branch?" prompt when using `/tree` |
+
+### Tuning Recommendations
+
+**For complex, multi-file tasks:**
+Increase `keepRecentTokens` to 40000 or higher. This preserves more of the recent conversation, helping the model remember intricate relationships between files.
+
+**For simple tasks with lots of back-and-forth:**
+The defaults work well. Frequent compaction keeps context fresh without losing important state.
+
+**If the model seems forgetful:**
+Check if compaction happened recently (look for the `[compaction]` marker). Expand it to review summary quality. If key information is missing, mention it again in your next message. It will be included in the next compaction's "Critical Context" section.
+
+## Practical Tips
+
+### Long Sessions Are Fine
+
+Compaction lets sessions run indefinitely. Don't worry about starting fresh sessions just to manage context. Pi handles it automatically.
+
+### If Something Gets Forgotten
+
+If the model forgets something after compaction:
+
+1. Mention it again explicitly in your next message
+2. Use `/compact "focus on X"` to ensure it's captured
+3. Navigate back via `/tree` to the point before compaction if you need the exact details
+
+### Use Custom Instructions
+
+When compacting manually, tell the summarizer what matters:
+
+```
+/compact focus on the database schema decisions and migration plan
+```
+
+This shapes the summary to preserve what's relevant for your next steps.
+
+### Navigate Back Anytime
+
+The full history is always available via `/tree`. Compaction doesn't delete anything. It just changes what the LLM sees in its working context.
+
+### Multiple Compactions Stack
+
+Each new compaction builds on the previous summary. The summarizer sees the earlier summary and the new messages to summarize, producing an iteratively refined context. This works well for long-running tasks where understanding evolves over time.
+
+## Customization via Extensions
+
+Extensions can customize compaction behavior entirely. You can:
+
+- Replace the default summarizer with your own
+- Add custom data to compaction entries
+- Trigger compaction on custom events
+- Modify the summary format
+
+For technical details, see:
+
+- [`compaction.md`](compaction.md) - Internals and extension hooks
+- [`extensions.md`](extensions.md) - Extension API reference
+- [`examples/extensions/custom-compaction.ts`](../examples/extensions/custom-compaction.ts) - Working example
+
+## FAQ / Troubleshooting
+
+### "The model forgot something important"
+
+**Check:** Look for the `[compaction]` marker in the conversation. Expand it with `Ctrl+O` to see what was preserved.
+
+**Fix:** Re-mention the forgotten information. It will be included in the next compaction. Consider increasing `keepRecentTokens` if this happens frequently.
+
+### "Compaction keeps triggering too often"
+
+**Cause:** Your `reserveTokens` may be too low for your typical response sizes, or you're using a model with a small context window.
+
+**Fix:** Increase `reserveTokens` (e.g., to 24000) or switch to a model with a larger context window. You can also increase `keepRecentTokens` to reduce compaction frequency.
+
+### "I want to disable auto-compaction"
+
+Set `compaction.enabled: false` in your settings. Use `/compact` manually when you want to compact. Be aware that without auto-compaction, long sessions may hit context limits and fail.
+
+### "How do I see what was compacted?"
+
+Expand the `[compaction]` message with `Ctrl+O` (or your configured expand keybinding). For the complete, un-summarized history, use `/tree` to navigate back to any point before the compaction.
+
+### "Can I recover the full conversation after compaction?"
+
+Yes. The full history is in your session file. Use `/tree` to navigate to any point before compaction and view the complete messages. Compaction only affects the LLM's working context, not the stored session.
+
+## See Also
+
+- [`compaction.md`](compaction.md) - Technical internals and extension hooks
+- [`settings.md`](settings.md) - Complete settings reference
+- [`tree.md`](tree.md) - Session tree navigation
+- [`extensions.md`](extensions.md) - Extension API for custom compaction
+- [`session.md`](session.md) - Session file format