Imported from yldgio/copilot-compress (
AGENTS.md). Install upstream withnpx skills add yldgio/copilot-compress. Copyright stays with the author.
AGENTS.md
What this repository is
This repository is a Copilot CLI extension, not a plugin.
Why: Copilot CLI plugins (hooks.json) cannot replace user prompts and do not support bundling extension.mjs session logic. Prompt interception/modification requires joinSession() from @github/copilot-sdk/extension and returning { modifiedPrompt } from onUserPromptSubmitted.
Architecture summary
Core structure:
extension.mjs— entry point;joinSession(), slash command registration, hook wiring, session statesrc/compress.mjs— pure EN/IT compression algorithm (verbatim upstream copy)src/code-blocks.mjs— code block extraction/restoration with placeholderssrc/lang-detect.mjs— per-message EN/IT detection heuristic (IT_THRESHOLD=0.30)dist/extension.mjs— committed build artifact; rollup bundle ofextension.mjs+ allsrc/modules. This is what the installers copy.
Design rule: src/ has no external dependencies. Only extension.mjs imports @github/copilot-sdk/extension.
Build
The installers deploy dist/extension.mjs, not the raw source files. This single-file bundle is produced by rollup.
| What | Value |
|---|---|
| Source | extension.mjs + src/*.mjs |
| Output | dist/extension.mjs (committed to git) |
| Command | npm run build |
| Config | rollup.config.js |
| External | @github/copilot-sdk/extension (never bundled — installed via npm) |
Build invariant: after every change to extension.mjs or any src/ file, run both of these commands before committing:
npm run build
cp dist/extension.mjs .github/extensions/copilot-compress/extension.mjs
The dist/ folder is committed so users can install without a build step. The .github/extensions/copilot-compress/ directory is gitignored (it's the project-scoped dogfooding install) — keep it in sync manually after every build.
Key design decisions
- Slash commands are registered in
joinSession({ commands: [...] }), not parsed insideonUserPromptSubmittedvia regex. - Code blocks are extracted before prose compression and restored after compression.
- Language is auto-detected per message (
en/it) withIT_THRESHOLD=0.30. - Savings estimates use
1 token ≈ 4 chars. src/compress.mjsis a verbatim copy from source and must be synced from upstream without local divergence.
Installation
Quick install — no clone required (agent one-liner)
# Linux/macOS — latest release
curl -fsSL https://raw.githubusercontent.com/yldgio/copilot-compress/main/install.sh | sh -s -- --remote
# Windows (pwsh) — downloads installer to temp, then runs with -Remote
$f = "$env:TEMP\copilot-compress-install.ps1"
Invoke-WebRequest https://raw.githubusercontent.com/yldgio/copilot-compress/main/install.ps1 -OutFile $f
pwsh $f -Remote
User-wide install (recommended)
Linux / macOS
git clone https://github.com/yldgio/copilot-compress.git
cd copilot-compress
sh install.sh
Windows (pwsh)
git clone https://github.com/yldgio/copilot-compress.git
Set-Location copilot-compress
pwsh .\install.ps1
Project-scoped install (.github/extensions/)
Linux / macOS
git clone https://github.com/yldgio/copilot-compress.git
cd /path/to/your-project
sh /path/to/copilot-compress/install.sh --project
Windows (pwsh)
git clone https://github.com/yldgio/copilot-compress.git
Set-Location C:\path\to\your-project
pwsh C:\path\to\copilot-compress\install.ps1 -Project
Manual install from clone (copy-based)
Linux / macOS
git clone https://github.com/yldgio/copilot-compress.git
cp -R copilot-compress ~/.copilot/extensions/copilot-compress
cd ~/.copilot/extensions/copilot-compress
npm install --omit=dev
Windows (pwsh)
git clone https://github.com/yldgio/copilot-compress.git
Copy-Item -Recurse .\copilot-compress $HOME\.copilot\extensions\copilot-compress -Force
Set-Location $HOME\.copilot\extensions\copilot-compress
npm install --omit=dev
Release process
Releases are tag-based. GitHub Actions handles everything:
git tag v1.x.x
git push --tags
The release.yml workflow will:
npm ci+npm test(must be 23/23)npm run build+ verify no local imports indist/extension.mjs- Create a GitHub Release with
dist/extension.mjs,package.json,install.sh,install.ps1,README.mdas assets
Testing
Run:
node --test src/*.test.mjs
Current suite total: 23 tests.
Extending the extension
Add a new language
- Add a filler/phrase list in
src/compress.mjsand route language-specific passes incompressText(). - Extend
src/lang-detect.mjsscoring and thresholds for the new language. - Add/expand tests to verify detection + compression behavior.
Add a new slash command
- Add command metadata to the
commands[]array inextension.mjs. - Dispatch and handle subcommand behavior in
handleCompressCommand. - Return user-facing feedback through
session.log().
Invariants (must not be violated)
src/compress.mjsis verbatim upstream copy — no local edits.src/modules have zero external imports.onUserPromptSubmittedmust never throw.- Command output must use
session.log()and nevermodifiedPrompt. dist/extension.mjsmust be rebuilt (npm run build) and committed wheneverextension.mjsor anysrc/file changes.- After every
npm run build, copydist/extension.mjsto.github/extensions/copilot-compress/extension.mjsto keep the project-scoped dogfooding install in sync.
