Install from npm using the latest Paseo release:
\npaseo plugin install paseo-smart-session\npaseo plugin ls # confirm it is running\npaseo plugin update smart-session\npaseo plugin remove smart-session\nOn first load, Smart Session registers its Claude Code hooks and MCP server. It only manages entries that point at its own scripts; other Claude Code configuration is left alone.
","readmeText":"# paseo-smart-session\n\n[](https://www.npmjs.com/package/paseo-smart-session)\n[](https://www.npmjs.com/package/paseo-smart-session)\n[](https://paseo.sh)\n[](LICENSE)\n\nGive Paseo agents a safe way to manage long-running work.\n\nSmart Session lets an agent see how full its context is, save durable task state, and compact itself when it is ready. It also records session and plan-usage statistics, so you can understand where tokens are going and when limits reset.\n\n\n\n## Install\n\nInstall from npm using the latest Paseo release:\n\n```sh\npaseo plugin install paseo-smart-session\n```\n\n```sh\npaseo plugin ls # confirm it is running\npaseo plugin update smart-session\npaseo plugin remove smart-session\n```\n\nOn first load, Smart Session registers its Claude Code hooks and MCP server. It only manages entries that point at its own scripts; other Claude Code configuration is left alone.\n\n## What it does\n\n### Lets agents compact themselves\n\nAn agent can check how much context it has used, checkpoint the work that must survive a reset, and request compaction when it reaches a safe stopping point. The agent also decides whether another turn should start afterwards and can write the exact follow-up message. A completed task can compact and stop; work in progress can resume from its saved state.\n\nThe saved state captures the goal, the current step, decisions already made, and approaches that have already failed. That prevents a resumed agent from redoing work or asking a person how to continue.\n\nSmart Session never chooses to compact an agent by itself. It can let an agent know that context is filling, but the agent decides whether to checkpoint, compact, or defer.\n\n### Shows session and plan usage\n\nSmart Session keeps a local history of:\n\n- Context-window usage for each agent session\n- Claude plan usage, burn rate, and reset times\n- Token spend by model, workspace, and main agent versus subagent\n- Compaction requests and their before/after context sizes\n\nThat history remains useful after an individual session ends or a provider cache changes.\n\n## How an agent uses it\n\nSmart Session exposes these MCP tools to Paseo agents:\n\n| Tool | What it does |\n| --- | --- |\n| `context_status` | Shows current context usage, filling rate, and relevant thresholds. |\n| `checkpoint` | Writes durable task state for the current session. |\n| `request_compaction` | Queues compaction and chooses whether and how to continue afterwards. |\n| `defer_compaction` | Defers a compaction request and records why. |\n| `budget_status` | Shows plan usage, burn rate, and reset times. |\n\nThe usual flow is:\n\n```text\ncontext_status → checkpoint → request_compaction → stop, or re-read state and continue\n```\n\n`request_compaction` refuses when the state file is missing or stale. The agent can checkpoint and request again in the same turn.\n\n## Smart Compact\n\nSmart Compact is the session-control feature. As a session fills, hooks can provide context notices at useful thresholds. When the compact threshold is reached at the end of a turn, the agent is asked whether it wants to compact.\n\nThere is no forced compaction. An agent can compact immediately, defer with a reason, or keep working. A request is delivered only when the agent is idle and its state file is current.\n\nEvery request sends the `/compact` command. The agent can also set:\n\n- `continue_after_compaction: false` to finish without starting another turn.\n- `continue_after_compaction: true` to start another turn after compaction.\n- `continue_message` to choose the exact follow-up; when omitted, the default tells the agent to re-read the state file and continue from its **Current step**.\n\nOmitting the new options preserves the earlier behavior: Smart Session continues with the default state-aware prompt. The durable state wins if it disagrees with the automatic summary. A `/compact` entered by a person never receives a plugin continuation.\n\n### The composer pill\n\nThe composer pill shows whether the current session is enrolled:\n\n| State | Meaning |\n| --- | --- |\n| **Smart Compact on** | The session can receive context notices and request compaction. |\n| **Smart Compact off** | The session is not enrolled. |\n\nIf Smart Compact is disabled globally, the pill is not shown.\n\n## Settings\n\n| Setting | Default | Description |\n| --- | --- | --- |\n| **Smart Compact** | On | Enables context notices and agent-requested compaction. |\n| **Large-window compact threshold** | 30% | Sets when Smart Compact asks on context windows of 400k tokens or more. |\n| **Small-window compact threshold** | 85% | Sets when Smart Compact asks on smaller context windows. |\n| **Enrol sessions automatically** | On | Enrols a session after it writes task state. |\n| **Show the pill on every agent** | On | Shows the Smart Compact control in the composer. |\n| **Register the hooks with Claude Code** | On | Keeps the context and compaction hooks installed. |\n\nThe remaining settings apply only while Smart Compact is enabled. Thresholds accept whole percentages from 1% to 99%; lowering one also moves its earlier notice bands down when needed.\n\n## Usage history and state\n\nSmart Session stores its data under:\n\n```text\n$PASEO_HOME/plugin-data/smart-session/\n```\n\n| File | Contains |\n| --- | --- |\n| `usage-YYYY-MM.jsonl` | Plan-usage observations and reset times. |\n| `context-YYYY-MM.jsonl` | Context-window usage changes. |\n| `compactions.json` | Compaction requests, continuation choices, and context sizes. |\n| `spend-index.json` | Hourly token spend by model, workspace, and agent type. |\n| `state/