npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@foliox/transparent-compact-pi

v0.13.1

Published

Model-free, deterministic, and self-aware compaction; with session-backed subagent context recovery, and optional context pruning and fidelity controls.

Readme

transparent-compact-pi

Context compaction and pruning for Pi that keeps conversation text verbatim instead of replacing it with a model-generated summary or truncation. It removes thinking and most tool output from the active context, while keeping user messages, assistant text, algorithmically compacted tool-call stubs and explicitly selected reads.

When the agent needs a detail that is no longer in context, it can use retrieval tools to search the recorded session history with a subagent. Compaction itself does not make a model call.

The user can also selectively manipulate which turns to hold in the current context in higher or lower fidelity, and specify file reads to be retained in the context in full, (e.g. a spec or plan).

This extension is aimed at addressing two main issues that other compaction techniques face, which are especially exacerbated in agents running on lightweight and local LLMs:

  • Model summaries such as Pi's default method can lead to degradation and confabulation of details that can cause confident blunders.
  • Retrieval-based systems like pi-vcc can be effective when the agent knows what to look for, but omitting session structure from the retained context can make the actual use of retrieval less reliable.

transparent-compact is also a retrieval-based system, but its design keeps manipulation of conversation text to a minimum and maximises the agent's awareness of its own compacted state, with the aim of avoiding confabulation and encouraging accurate retrieval of historical details. This study found that a minimal approach outperformed more complex techniques with lightweight models and was at least as effective with frontier models.

The verbatim compaction system plays particularly nicely with manual pruning of the context. This allows you to decide which parts of the session remain important to the current work, without having to commit to a particular branching point with /tree or decide at the time of the prompt with something like claude's /btw.

The extension is particularly suited to capable local models with reasonably large context windows (over 128k tokens), such as Qwen 3.8 27B running on llama.cpp with an RTX 5090, but it is also effective with frontier models and larger context windows.

Install

pi install npm:@foliox/transparent-compact-pi

Alternatively, install from GitHub or a local checkout:

pi install git:github.com/felixwoolford/transparent-compact-pi
pi install /absolute/path/to/transparent-compact

Once loaded, the extension uses verbatim compaction by default. Pi's automatic compaction continues to work, using the extension's configured method; to compact manually, enter:

/compact

No additional setup is required. The agent can recover missing details from session history as needed.

Filter turns

Use these commands while the agent is idle:

/filter-turns       # edit an existing checkpoint
/compact-filtered   # compact first, then open the editor

Use /compact-filtered if there is no checkpoint yet. Cancelling its editor does not undo the compaction that just completed. If there is nothing new to compact, it opens the existing checkpoint.

Each selection covers a user message and all following activity up to the next user message:

| Mode | What stays in context | | --- | --- | | PRUNED [X] | A marker in place of the turn | | PROSE [ ] | Conversation text and compact tool stubs | | PROSE+TOOLS [○] | Conversation text and recorded tool arguments and results; thinking markers only | | FULL [■] | All recorded content, including thinking and images | | LOCKED [-] | Not available for editing |

Navigate with ↑/↓; use ←/→ to collapse or expand details. Press Space to prune a turn or restore it to PROSE, or f to cycle through all four modes. Press Enter to review changes, then Enter again to save; Esc goes back or cancels. The editor shows an estimated context size as you choose.

You can restore filtered turns later. Choices persist in the current session branch through later verbatim compactions and reloads. Turns overlapping Pi's retained recent history are locked until they can be filtered as a whole; individual content inside an inherited summary cannot be selected.

PROSE+TOOLS and FULL can use substantial context. Oversized selections are rejected, and if later context growth or a model change makes them too large, use /filter-turns to downgrade them. FULL includes only what was recorded; provider and model limitations can still affect thinking and images.

Manual context editing and caching

Manual context edits typically reduce prompt-cache reuse for the next model request, so frequent edits of the retained reads or turn filters are discouraged, and the best time to adjust them is just after compaction, before the next request.

The extension never automatically modifies the context outside of Pi's usual compaction trigger. The user is expected to control the filtering system, or simply ignore it when not needed. Treat filtering/pruning/read-retention as useful tools when the situation calls for them, not necessary to the use of the compaction system.

Flag an aside

/filter-later <message>  # send a turn and flag it for filtering
/fl <message>            # short alias
/filter-auto             # show automatic filtering policy
/filter-auto on          # apply flags during automatic compaction
/filter-auto off         # stop automatically applying new flags

A flagged turn remains in context until it is eligible for filtering. It is preselected for pruning in the editor, where you can keep or later restore it. Automatic application of flags is off by default. /fl is a normal conversation turn, not an isolated aside.

Retain reads

Use /retain-reads while the agent is idle to keep selected text-read outputs verbatim in the checkpoint. Each file can be OFF, FIRST, or LATEST. In the picker, controls are as in the turn-filtering picker.

Consecutive partial reads of the same file with connected ranges form one selectable read episode. Another tool operation, a restarted range, or a new user turn starts a new episode. The picker shows full or partial coverage and flags reads from filtered turns. Retention survives turn filtering;

Retained outputs are historical snapshots of the read tool output, not current file contents.

Automatic file retention

Nothing is retained automatically, but files can be declared for retention in AGENTS.md or CLAUDE.md like so:

<retain-reads>
docs/SPEC.md
latest: docs/WORKING-NOTES.md
</retain-reads>

Use one literal path per line, relative to the instruction file. Plain paths default to FIRST; latest: selects the latest read. These declarations do not read files themselves. Manual choices override the defaults.

Control compaction

Export the checkpoint

Use /export-checkpoint [path] to save the current checkpoint as plain text. Without a path, it writes pi-checkpoint-<session-id>.txt in the working directory; quote paths containing spaces.

This exports the saved text, including confirmed filtering and read-retention edits, without rebuilding or changing context. Recent messages and separately reinserted PROSE+TOOLS/FULL messages are not included.

Choose the method

/compaction-method           # show current method
/compaction-method verbatim  # extension's compaction (default)
/compaction-method summary   # Pi's built-in summary compaction

The selection applies to manual and automatic compaction, including overflow recovery, and persists in the session branch. New sessions default to verbatim. Manual filtering requires verbatim mode.

Set the size cap

By default, the extension warns before trimming a checkpoint that exceeds an estimated 25% of the model's context window. The interactive prompt lets you apply trimming, disable the cap for the session, change the budget, or cancel compaction. Capping works by progressively reducing the size of tool stubs and then as a last resort truncating assistant prose and finally truncating user prose. With normal use, this shouldn't occur until over a dozen compactions. If you regularly reach the cap, consider starting a new session or using a different compaction method that is more suited to your workflow.

/cap-compaction               # show mode and budget
/cap-compaction warn          # prompt before trimming (default)
/cap-compaction on            # trim without prompting
/cap-compaction off           # disable cap-based trimming
/cap-compaction warn 20000t   # estimated token budget
/cap-compaction warn 25%      # percentage of model context window
/cap-compaction on 80000c     # character budget
/cap-compaction 40000c        # change budget without changing mode

Mode and budget persist in the session branch; changing one leaves the other unchanged. They apply only to verbatim compaction. The cap estimates tokens at four characters each and is not a limit on the whole model context. Some content, including retained reads, is not trimmed. Disabling the cap may leave too much context for the model.

For unattended use, choose on to avoid interactive prompts. Without an interactive UI, warn emits a warning and applies the cap. If the model's context window is unavailable, use a fixed token or character budget, or turn the cap off.

Configuration

No configuration file is needed. Set these environment variables before starting Pi:

| Variable | Default | Purpose | | --- | --- | --- | | MECH_COMPACT_MAX_SUMMARY_PERCENT | 25 | Initial cap as a percentage of the model's context window (greater than 0, up to 100). | | MECH_COMPACT_MAX_SUMMARY_CHARS | Unset | Initial fixed character budget; overrides the percentage. | | MECH_COMPACT_LOOKUP_MODEL | Session model | Lookup model as provider/modelId; it must be available in Pi and support tool calls. An unresolved model falls back to the session model. | | MECH_COMPACT_LOOKUP_TURNS | 25 | Maximum substantive search turns per lookup. | | MECH_COMPACT_LOOKUP_MAX_CALLS | 3 | Maximum consecutive lookup attempts; 0 means unlimited. | | MECH_COMPACT_LOOKUP_SESSION_FILE | Unset | Absolute path to a full session JSONL to search instead of the current branch, for harnesses using pruned forks. Leave unset for ordinary use. | | MECH_COMPACT_MAIN_AGENT_LOOKUP | Unset | 1 opts into direct recovery; 0 overrides the file setting for sessions without a recorded choice. |

For example:

MECH_COMPACT_MAX_SUMMARY_PERCENT=30 pi
MECH_COMPACT_LOOKUP_MODEL=provider/modelId pi

A session setting from /cap-compaction takes precedence over the environment defaults. Restart Pi after changing its launching environment; /reload cannot change inherited environment variables.

Optional direct recovery

Subagent lookup is the default. To let the main agent search and read history directly instead, add this to Pi's ~/.pi/agent/settings.json or trusted project .pi/settings.json:

{
  "transparentCompact": {
    "mainAgentLookup": true
  }
}

Alternatively, launch with MECH_COMPACT_MAIN_AGENT_LOOKUP=1 pi. The environment variable overrides the file setting. Run /reload after editing settings.

Opt-in requires a session with no existing compactions. Once enabled, the choice persists through compaction and resume; changing configuration does not switch that session back. Forks inherit the choice when their copied history includes it. Start another session to use a different mode.

Direct recovery exposes listing, search, and entry-reading tools instead of context_lookup. It avoids a separate model call but puts retrieved pages into the main context. The subagent model and search-turn/call budgets do not apply to direct recovery. This is a second-class operational mode and has not been tested in practice as much as the subagent lookup.

Local inference

Lookups using the session model can disrupt the main session's prompt cache. For a single-slot llama.cpp server (-np 1), enable --cache-ram <MiB> with enough host memory for the main session state. On other engines, use prefix caching, KV offloading, or sufficient parallel capacity to keep both sessions resident.

License

MIT.