Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
name: CodeQL

on:
push:
branches: [main]
pull_request:
schedule:
- cron: "17 4 * * 1"

permissions: {}

concurrency:
group: codeql-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
analyze:
name: Analyze (${{ matrix.language }})
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write # upload CodeQL results
strategy:
fail-fast: false
matrix:
language: [actions, javascript-typescript]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
languages: ${{ matrix.language }}
build-mode: none
queries: security-and-quality
- uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
category: /language:${{ matrix.language }}
9 changes: 9 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,15 @@ jobs:
env:
GH_TOKEN: ${{ github.token }}
TAG: ${{ github.event.release.tag_name }}
# Pi shows CHANGELOG.md to users after an update.
- name: Require a changelog entry
run: |
if ! grep -q "^## \[${TAG#v}\]" CHANGELOG.md; then
echo "CHANGELOG.md needs a '## [${TAG#v}]' entry." >&2
exit 1
fi
env:
TAG: ${{ github.event.release.tag_name }}
- run: npm ci --ignore-scripts
- name: Publish to npm
run: |
Expand Down
44 changes: 44 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Changelog

Pi shows the entries newer than your installed version after `pi update`.

## [0.4.1] - 2026-11-13

- The README has a quick start and a troubleshooting section. No change to the extension.

## [0.4.0] - 2026-11-13

- The footer shows how full the context is and when cleanup starts, for example `Context 62% · cleanup at 75%`.
- `/context-kit` opens a panel to turn cleanup on or off, and to choose when and how to clean up.
- Settings move to their own file: `~/.pi/agent/context-kit.json`, and `.pi/context-kit.json` in a trusted project. At the first start, the `contextKit` entry of Pi's `settings.json` moves there with the same behavior.
- The default threshold is now `75%`. Set `"threshold": "pi"` to wait for Pi's limit as before.

## [0.3.2] - 2026-11-11

- Documentation only.

## [0.3.1] - 2026-11-11

- Documentation and package metadata only.

## [0.3.0] - 2026-11-11

- Breaking: the `staleSuffixTokens` setting is removed. Remove it from your settings.
- Supports Pi 1.5. Pi 1.0.3 is still the oldest supported version.
- Requires Node.js 22.19 or later, as Pi does.
- pi-context-kit edits the context only at the threshold, in one batch, so the provider's prompt cache breaks less often.
- After a handoff note, shaking runs only when pruning is not enough.
- With Pi's compaction off, pi-context-kit changes the context only on `/compact`.
- Background handoff notes are cancelled after session-tree navigation.

## [0.2.1] - 2026-10-06

- The README explains each term, the steps of a session, and each setting.

## [0.2.0] - 2026-10-06

- Handoff notes use the session's thinking level and tool choice, so Anthropic can reuse the cached conversation.
- An earlier threshold compacts at the end of a turn, even when no handoff note is ready.
- Recall regex searches are bounded and can be cancelled.
- Handoff notes that are truncated, too large or that call a tool are rejected.
- A failed threshold note is not retried until the next compaction.
15 changes: 8 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,14 @@ Do not bump the package version in pull requests. The release tag sets the publi

### Release procedure

1. Wait for CI to succeed on the `main` commit you want to publish.
2. On GitHub, open **Releases > Draft a new release**.
3. Create the tag `vX.Y.Z` on `main`. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes.
4. Select **Generate release notes**, then **Publish release**.
5. Approve the `npm` environment deployment in the Actions run.

The workflow rejects a release that is not from the owner, a prerelease, a tag that is not `vX.Y.Z`, a commit outside `main`, or a commit without successful CI. It runs `npm run check`, sets the package version from the tag and publishes with npm provenance. A new npm publication updates the `latest` dist-tag.
1. In a pull request, add a `## [X.Y.Z] - YYYY-MM-DD` entry at the top of `CHANGELOG.md`, in words a user understands. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes. Pi shows this entry to users after `pi update`.
2. Wait for CI to succeed on the `main` commit you want to publish.
3. On GitHub, open **Releases > Draft a new release**.
4. Create the tag `vX.Y.Z` on `main`.
5. Select **Generate release notes**, then **Publish release**.
6. Approve the `npm` environment deployment in the Actions run.

The workflow rejects a release that is not from the owner, a prerelease, a tag that is not `vX.Y.Z`, a commit outside `main`, a commit without successful CI, or a version without a `CHANGELOG.md` entry. It runs `npm run check`, sets the package version from the tag and publishes with npm provenance. A new npm publication updates the `latest` dist-tag.

Releases and `v*` tags are immutable. If publication fails for an external cause, use **Re-run failed jobs** on the original run. If the code needs a fix, publish a new version.

Expand Down
48 changes: 32 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
# pi-context-kit
# pi-context-kit: long Pi sessions that stay sharp

[![npm version](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit) [![CI](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml) [![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org) [![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE)

**Long Pi sessions that stay sharp.**
[![CI](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit)
[![Pi package](https://img.shields.io/badge/pi.dev-package-blue)](https://pi.dev/packages/pi-context-kit)
[![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org)
[![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE)

Pi compaction and context management for the [Pi coding agent](https://github.com/earendil-works/pi). pi-context-kit clears stale file reads and old tool outputs out of the context window, writes the handoff summary in the background before Pi needs it, and keeps the original text of the current branch one `recall` search away.

```sh
pi install npm:pi-context-kit
```

Restart Pi. That is all: the defaults work without configuration. Requirements: Pi 1.0.3 or later, Node.js 22.19 or later.
Restart Pi. The defaults work without configuration.

## Why pi-context-kit

Expand Down Expand Up @@ -75,22 +77,24 @@ In a long session, the conversation fills the context window. File reads and com

</details>

## Install

1. Open a terminal.
2. Type this command and press Enter:
## Quick start

```sh
pi install npm:pi-context-kit
```
You need Pi 1.0.3 or later and Node.js 22.19 or later.

3. Restart Pi.
1. Install the package with the command above.
2. Restart Pi.
3. Look at the footer. It shows `Context 0% · cleanup at 75%` when the extension is active.
4. Work as usual. Type `/context-kit` to change the settings.

To check the installation, type `pi list`. The list must show `npm:pi-context-kit`.
## Update, try or remove

To update, type `pi update npm:pi-context-kit` and restart Pi.
```sh
pi update npm:pi-context-kit # update, then restart Pi
pi -e npm:pi-context-kit # try for one session without installing
pi remove npm:pi-context-kit # remove, then restart Pi
```

To remove it, type `pi remove npm:pi-context-kit` and restart Pi.
After an update, Pi shows what changed, from [CHANGELOG.md](CHANGELOG.md).

## Use it

Expand Down Expand Up @@ -329,6 +333,18 @@ pi-context-kit has no setting per model. To start earlier for one model only, ma
- **The method order stops at `soft`.** The methods after `soft` do not run.
- **Subagents** read the same settings files. They show no warnings and no status, because they have no screen.

## Troubleshooting

**No `Context` in the footer**: type `pi list` and check that it shows `npm:pi-context-kit`. Then restart Pi. Pi shows the footer only in the interactive mode.

**`pi-context-kit settings need attention`**: a value in a settings file is not valid. pi-context-kit uses the default for that value. Type `/context-kit` to see the problem, then correct the file or select a new value in the panel.

**`pi-context-kit moved its settings to ...`**: an earlier version kept the settings in Pi's `settings.json`. pi-context-kit copied them to its own file once. You can remove the `contextKit` entry from `settings.json`.

**`pi-context-kit: handoff note failed`**: the summary request failed. pi-context-kit uses the next method or Pi's summary, so your session continues. Check the model and your provider limits.

**The panel cannot save a value**: Pi shows `pi-context-kit:` and the file error. Check that you can write the settings file, then select the value again.

## FAQ

**Does it slow down my work?**
Expand Down
8 changes: 4 additions & 4 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "pi-context-kit",
"version": "0.2.1",
"description": "Pi compaction and context management for the Pi coding agent: replace stale file reads, prune old tool outputs, prepare handoff notes in the background, and recall the original text.",
"description": "Keep long Pi coding agent sessions sharp. Clears old file reads and tool outputs from the context, writes the compaction summary in the background, and lets the agent recall the original text.",
"type": "module",
"license": "MIT",
"author": "HugoLopes45 (https://github.com/HugoLopes45)",
Expand Down Expand Up @@ -30,7 +30,8 @@
"files": [
"extensions",
"src",
"context-kit.schema.json"
"context-kit.schema.json",
"CHANGELOG.md"
],
"engines": {
"node": ">=22.19.0"
Expand All @@ -43,8 +44,7 @@
"scripts": {
"check": "tsc --noEmit && npm run lint && vitest --run",
"lint": "node scripts/lint.ts",
"test": "vitest --run",
"prepublishOnly": "test -n \"$GITHUB_ACTIONS\" || test \"$(npm whoami)\" = hugolopes45 || { echo 'Publish only as the npm user hugolopes45.' >&2; exit 1; }; npm run check"
"prepublishOnly": "npm run check"
},
"peerDependencies": {
"@earendil-works/pi-ai": "*",
Expand Down
4 changes: 1 addition & 3 deletions scripts/lint.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,12 @@ const config: Linter.Config = {
rules: { complexity: ["error", 10] },
};

let problems = 0;
for (const file of globSync("{extensions,scripts,src,test}/**/*.ts")) {
const code = stripTypeScriptTypes(readFileSync(file, "utf8"));
for (const message of linter.verify(code, config, file)) {
problems++;
process.exitCode = 1;
console.error(
`${file}:${message.line}:${message.column} ${message.message}`,
);
}
}
if (problems) process.exit(1);
Loading