paseo-smart-session

Give Paseo agents a safe way to manage long-running work.

Smart 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.

Install

Install from npm using the latest Paseo release:

paseo plugin install paseo-smart-session

paseo plugin ls                    # confirm it is running
paseo plugin update smart-session
paseo plugin remove smart-session

On 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.

What it does

Lets agents compact themselves

An 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.

The 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.

Smart 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.

Shows session and plan usage

Smart Session keeps a local history of:

• Context-window usage for each agent session
• Claude plan usage, burn rate, and reset times
• Token spend by model, workspace, and main agent versus subagent
• Compaction requests and their before/after context sizes

That history remains useful after an individual session ends or a provider cache changes.

How an agent uses it

Smart Session exposes these MCP tools to Paseo agents:

The usual flow is:

context_status → checkpoint → request_compaction → stop, or re-read state and continue

request_compaction refuses when the state file is missing or stale. The agent can checkpoint and request again in the same turn.

Smart Compact

Smart 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.

There 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.

Every request sends the /compact command. The agent can also set:

• continue_after_compaction: false to finish without starting another turn.
• continue_after_compaction: true to start another turn after compaction.
• 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.

Omitting 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.

The composer pill

The composer pill shows whether the current session is enrolled:

If Smart Compact is disabled globally, the pill is not shown.

Settings

The 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.

Usage history and state

Smart Session stores its data under:

$PASEO_HOME/plugin-data/smart-session/

Usage and context observations are append-only. A damaged line is skipped rather than putting the rest of the history at risk. Existing compaction rows are read as “continue with the default prompt,” so upgrading requires no data migration.

Password-protected daemons

When the Paseo daemon requires a password, Smart Session resolves it in this order:

1. PASEO_PASSWORD
2. The file named by PASEO_PASSWORD_FILE
3. ~/paseo-hub/secrets/daemon-password

The secret is used only to connect to the daemon. It is never written or logged.

Development

git clone https://github.com/tomgrin10/paseo-smart-session.git
cd paseo-smart-session
npm ci
npm run verify
paseo plugin install "$PWD"

After editing:

npm run verify
paseo plugin reload smart-session

Reloading the plugin is enough. Do not restart the Paseo daemon: that interrupts every running agent.

Data and privacy

Smart Session reads local Claude Code usage information and communicates with the local Paseo daemon. Its usage history, settings, and task state stay under $PASEO_HOME. Apart from narrowly maintaining its own Claude Code hook and MCP entries, it does not modify user configuration.

License

MIT © 2026 Tom Gringauz.

Other plugins

• Defer — Schedule messages for later delivery.
• Graphite — Graphite stacks and PR status.
• Vitals — Host, agent, and Docker health.
• Session Guard — Pause at session limits and continue after reset.
• Transfer — Copy or move workspaces between hosts.
• Transcript Search — Search conversations across connected hosts.
• Send to Paseo — Send GitHub and Graphite PRs to Paseo from Chrome.
• Dispatch — Route tasks to existing workspaces (development preview).