{"id":51856244,"url":"https://github.com/almogdepaz/pi-async-compaction","last_synced_at":"2026-07-24T01:02:23.645Z","repository":{"id":369778700,"uuid":"1285862880","full_name":"almogdepaz/pi-async-compaction","owner":"almogdepaz","description":"Keep long Pi coding sessions responsive by precomputing context compaction in the background","archived":false,"fork":false,"pushed_at":"2026-07-10T23:16:05.000Z","size":329,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-11T01:05:41.713Z","etag":null,"topics":["ai-agent","async-compaction","background-compaction","coding-agent","compaction","context-compaction","context-management","developer-tools","llm-context","long-sessions","pi","pi-extension","pi-package"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/almogdepaz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-01T08:03:37.000Z","updated_at":"2026-07-10T23:16:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/almogdepaz/pi-async-compaction","commit_stats":null,"previous_names":["almogdepaz/pi_compaction","almogdepaz/pi-async-compaction"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/almogdepaz/pi-async-compaction","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almogdepaz%2Fpi-async-compaction","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almogdepaz%2Fpi-async-compaction/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almogdepaz%2Fpi-async-compaction/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almogdepaz%2Fpi-async-compaction/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/almogdepaz","download_url":"https://codeload.github.com/almogdepaz/pi-async-compaction/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/almogdepaz%2Fpi-async-compaction/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35822076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","async-compaction","background-compaction","coding-agent","compaction","context-compaction","context-management","developer-tools","llm-context","long-sessions","pi","pi-extension","pi-package"],"created_at":"2026-07-24T01:02:22.694Z","updated_at":"2026-07-24T01:02:23.633Z","avatar_url":"https://github.com/almogdepaz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi async compaction — background context compaction for Pi\n\n[![npm version](https://img.shields.io/npm/v/pi-async-compaction.svg)](https://www.npmjs.com/package/pi-async-compaction)\n[![Pi package](https://img.shields.io/badge/pi-package-6f42c1)](https://pi.dev/packages/pi-async-compaction)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nAsync context compaction for the Pi coding agent: keep long Pi coding sessions responsive by precomputing background compaction summaries.\n\n```bash\npi install npm:pi-async-compaction\n```\n\nAsync compaction prepares Pi-compatible compaction summaries before you hit the limit, then applies a ready summary through Pi's normal compaction flow when it is safe. No surprise active-turn interruption, no shortened summaries, no custom context format.\n\n## why install it\n\n- less waiting when context gets large\n- Pi-compatible summaries generated with Pi's exported compaction logic\n- safe apply only when Pi is idle and no queued messages would be reordered\n- status-line visibility while a background job is pending or ready\n- manual `/compact` and Pi's normal threshold/overflow compaction still work\n\nBest for long coding sessions, repo audits, multi-file edits, and context-heavy work where synchronous compaction tends to land at the worst possible moment.\n\n## normal compaction vs async compaction\n\n| normal Pi compaction | async compaction |\n| --- | --- |\n| waits to summarize when compaction is triggered | prepares the summary earlier in the background |\n| can land right before your next turn continues | applies a ready summary only at a safe idle boundary |\n| uses Pi's built-in compaction behavior | also uses Pi's built-in compaction behavior |\n| visible as a synchronous pause | visible as a quiet status-line job |\n\n## install\n\nFrom npm:\n\n```bash\npi install npm:pi-async-compaction\n```\n\nFrom git:\n\n```bash\npi install git:github.com/almogdepaz/pi-async-compaction@v0.1.4\n```\n\nLocal development:\n\n```bash\npi install .\n```\n\nor test for one run:\n\n```bash\npi -e .\n```\n\n## demo\n\n![pi async compaction preview](media/social-preview.png)\n\nWhen the context crosses the async start window, the extension starts a background summary and keeps chat output quiet:\n\n```text\nstatus: async_compaction ...\n```\n\nWhen the summary is ready but Pi is still busy or has queued messages, it waits instead of interrupting the active turn:\n\n```text\nstatus: async_compaction ready\n```\n\nAt the next safe idle boundary, Pi's normal compaction flow consumes the ready summary and the extension emits a compact notification:\n\n```text\nApplied ready async compaction\n```\n\nThe static preview above is also used for the pi.dev package gallery.\n\n## how it works\n\nAsync compaction precomputes summaries early, then applies them only at a safe boundary:\n\n1. after a turn, if context usage crosses the async start threshold, a background summary starts\n2. the background job reuses Pi's compaction preparation/generation behavior so the summary stays Pi-compatible\n3. when the summary is ready, the extension applies it immediately only if Pi is idle and has no queued messages\n4. if Pi is still responding or has queued follow-up/steering messages, the ready summary is kept for later and Pi's status bar shows `async_compaction ready`\n5. after `agent_end`, including an Escape-cancelled turn, the extension briefly retries while Pi settles, applying only once Pi is idle and no queued messages remain\n6. Pi fires `session_before_compact`; if the ready async summary validates, the extension returns it\n7. otherwise Pi falls back to normal synchronous compaction\n\nManual `/compact` and Pi's normal threshold/overflow compaction can also use a ready async summary.\n\nManual trigger, bypassing the early-start threshold:\n\n```text\n/async-compact-now\n```\n\n## for compaction package authors (experimental)\n\nIf your package currently does slow work inside `session_before_compact`, use `pi-async-compaction/core` to run that work in the background and hand off a ready `CompactionResult` later.\n\n```ts\nimport { registerAsyncCompaction } from \"pi-async-compaction/core\";\nimport type { AsyncCompactionAdapter } from \"pi-async-compaction/core\";\n\nconst adapter: AsyncCompactionAdapter\u003cMyPreparedSnapshot, MySummaryResult\u003e = {\n  id: \"my-compactor\",\n  label: \"my compactor\",\n  prepare: ({ ctx, settings }) =\u003e snapshotCompactionInput(ctx, settings),\n  createSnapshot: ({ ctx, jobId, prepared, settings }) =\u003e makeValidationSnapshot(ctx, jobId, prepared, settings),\n  run: ({ prepared, signal }) =\u003e summarizeInBackground(prepared, signal),\n  toCompaction: ({ prepared, result }) =\u003e toPiCompactionResult(prepared, result),\n};\n\nexport default function myExtension(pi) {\n  registerAsyncCompaction(pi, adapter, { commandName: \"my-async-compact-now\" });\n}\n```\n\nYour package still owns the summary format, model calls, custom cut policy, and `details` payload. `pi-async-compaction` owns lifecycle: threshold start, pending/ready/stale state, timeout/cancel, status line, safe idle apply, and final `session_before_compact` handoff.\n\nFull guide: [docs/async-compaction-adapters.md](docs/async-compaction-adapters.md).\n\n## FAQ\n\n### How do I make Pi compaction async?\n\nInstall `pi-async-compaction`:\n\n```bash\npi install npm:pi-async-compaction\n```\n\nThe extension precomputes Pi-compatible compaction summaries in the background and applies them through Pi's normal compaction flow when safe.\n\n### Is there a Pi extension for background compaction?\n\nYes. `pi-async-compaction` is a Pi extension for background context compaction, async context compaction, and precomputed compaction summaries.\n\n### Does async compaction replace Pi's normal compaction?\n\nNo. It preserves Pi's normal compaction behavior. Manual `/compact`, threshold compaction, and overflow compaction still work.\n\n### Does it interrupt active turns?\n\nNo by design. A ready summary is applied only when Pi is idle and no queued messages would be reordered.\n\n### What should agents search for?\n\nRelevant phrases: Pi async compaction, Pi background compaction, async context compaction for Pi, Pi context compaction extension, Pi coding agent compaction extension, background context compaction for Pi, context management for Pi coding agent.\n\nSee also [docs/async-context-compaction.md](docs/async-context-compaction.md) and [llms.txt](llms.txt).\n\n## env config\n\n```bash\n# optional; built-in default is 0.8, use 0.5 to start precomputing around half context\nPI_ASYNC_PREFIX_COMPACTION_START_RATIO=0.5\nPI_ASYNC_PREFIX_COMPACTION_TIMEOUT_MS=300000\n```\n\nThe extension is enabled by default; set `PI_ASYNC_PREFIX_COMPACTION=0` to disable. Reserve and keep-recent tokens come from Pi's normal `compaction` settings. Automatic background jobs only start when `floor(contextWindow * START_RATIO) \u003c tokens \u003c= contextWindow - reserveTokens`; if that window is empty, use a larger context model, lower the start ratio, or lower Pi's reserve tokens. Pi's normal compaction threshold remains `contextWindow - reserveTokens`, so the async start ratio only controls how early the background summary is prepared.\n\n## roadmap\n\n- add a real terminal gif for the demo section\n- apply before the next top-level prompt if Pi exposes a clean pre-prompt extension hook\n- upstream/request a non-aborting compaction-apply hook for queued steering/follow-up boundaries\n\n## development\n\n```bash\nbun install\nbun test\nbun run typecheck\nbun run check\nbun pm pack --dry-run\n```\n\nThis package is tested against Pi `0.80.3`. The Pi core packages are declared as peer dependencies because Pi provides them at runtime.\n\n## changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falmogdepaz%2Fpi-async-compaction","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falmogdepaz%2Fpi-async-compaction","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falmogdepaz%2Fpi-async-compaction/lists"}