{"id":50689381,"url":"https://github.com/victor-software-house/pi-live-compaction","last_synced_at":"2026-06-09T01:10:03.409Z","repository":{"id":361744619,"uuid":"1255608518","full_name":"victor-software-house/pi-live-compaction","owner":"victor-software-house","description":"Live streaming compaction for Pi — structured summaries with preset routing, Liquid templates, and a TUI settings panel","archived":false,"fork":false,"pushed_at":"2026-06-08T05:36:08.000Z","size":1532,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T07:22:57.164Z","etag":null,"topics":["ai-agent","compaction","context-engineering","context-management","liquid-templates","llm-transparency","pi","pi-agent","pi-ecosystem","pi-extension","pi-package","streaming","tui"],"latest_commit_sha":null,"homepage":"https://pi.dev/packages/pi-live-compaction","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/victor-software-house.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-01T02:29:50.000Z","updated_at":"2026-06-08T05:36:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/victor-software-house/pi-live-compaction","commit_stats":null,"previous_names":["victor-software-house/pi-live-compaction"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/victor-software-house/pi-live-compaction","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-software-house%2Fpi-live-compaction","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-software-house%2Fpi-live-compaction/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-software-house%2Fpi-live-compaction/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-software-house%2Fpi-live-compaction/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/victor-software-house","download_url":"https://codeload.github.com/victor-software-house/pi-live-compaction/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victor-software-house%2Fpi-live-compaction/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34086798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"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","compaction","context-engineering","context-management","liquid-templates","llm-transparency","pi","pi-agent","pi-ecosystem","pi-extension","pi-package","streaming","tui"],"created_at":"2026-06-09T01:10:02.794Z","updated_at":"2026-06-09T01:10:03.393Z","avatar_url":"https://github.com/victor-software-house.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-live-compaction\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/victor-software-house/pi-live-compaction/main/assets/thumbs/final/pi-live-compaction-og.png\" alt=\"pi-live-compaction\" width=\"720\" /\u003e\n\u003c/p\u003e\n\nLive streaming compaction for [Pi](https://github.com/earendil-works/pi-mono) — structured summaries with preset routing, Liquid templates, files-touched manifests, task-state continuity, and a full TUI settings panel.\n\n## Highlights\n\n- **11 continuity sections** instead of 5 — intent trail, dead ends, task state, file manifests, mandatory reading\n- **Live streaming** — watch the summary form as it compacts; partial recovery if the stream breaks\n- **Preset routing** — route compaction to any model with per-preset thinking levels and fallback chains\n- **Liquid templates** — fully customizable prompts with layout inheritance, partials, frontmatter knobs\n- **Focus directive** — `/compact \u003cfocus\u003e` preserves the exact operator goal through compaction\n- **TUI settings panel** — scope switching, preset editor, prompt editor, runtime status\n\n## Install\n\n```bash\npi install npm:pi-live-compaction\n```\n\nOr try without installing:\n\n```bash\npi -e npm:pi-live-compaction\n```\n\n## How it works\n\n\u003cimg src=\"https://raw.githubusercontent.com/victor-software-house/pi-live-compaction/main/assets/readme/final/pipeline.png\" alt=\"Compaction pipeline\" /\u003e\n\nThe extension hooks into Pi's `session:beforeCompact` and `session:beforeTree` events:\n\n1. **Resolves the summarizer** — picks a model from presets, inherits the session model, or falls back to a configured default\n2. **Renders the prompt** — Liquid template engine composes the request from partials with all context blocks\n3. **Streams the summary** — calls the summarizer with live streaming, showing progress in the chat flow\n4. **Recovers on failure** — if the stream breaks mid-summary, recovers whatever was streamed\n5. **Logs diagnostics** — writes attempt entries with SHA-256 hashes, token counts, and transport info\n\n### What the summary preserves\n\n\u003cimg src=\"https://raw.githubusercontent.com/victor-software-house/pi-live-compaction/main/assets/readme/final/sections.png\" alt=\"11 continuity sections\" /\u003e\n\nEvery compaction summary captures what happened, where things stand, and what to do next — so the next agent (or the same session after compaction) opens the right files and doesn't repeat failed approaches.\n\n### Preset routing\n\n\u003cimg src=\"https://raw.githubusercontent.com/victor-software-house/pi-live-compaction/main/assets/readme/final/presets.png\" alt=\"Preset routing\" /\u003e\n\nRoute compaction to different models with different thinking levels. Use `/compact --preset deep` for thorough compaction or let the default kick in automatically. If the selected preset's model auth fails, the fallback chain tries cheaper models before falling back to the session model.\n\n```json\n{\n  \"defaultPreset\": \"default\",\n  \"fallbackPreset\": \"cheap\",\n  \"presets\": {\n    \"fast\": { \"model\": \"openai-codex/gpt-5.4-mini\", \"thinkingLevel\": \"medium\" },\n    \"cheap\": { \"model\": \"anthropic/claude-haiku-4-5\", \"thinkingLevel\": \"low\" },\n    \"default\": { \"model\": \"anthropic/claude-sonnet-4-6\", \"thinkingLevel\": \"medium\" },\n    \"deep\": { \"model\": \"anthropic/claude-sonnet-4-6\", \"thinkingLevel\": \"high\" },\n    \"thorough\": { \"model\": \"anthropic/claude-opus-4-8\", \"thinkingLevel\": \"xhigh\" }\n  }\n}\n```\n\n### Template engine\n\nPrompts are [LiquidJS](https://liquidjs.com/) templates powered by [pi-template-kit](https://github.com/victor-software-house/pi-template-kit):\n\n- **Layout inheritance** — `{% layout '_base' %}` + `{% block content %}`\n- **Partials** — `{% include '_blocks' %}` from the sibling `templates/` directory\n- **Frontmatter** — `preset:`, `thinking_level:`, `model:`, `description:` override runtime behavior per template\n- **Custom filters** — `present`, `quote`, `tokens`, `text`, `last_user_text`\n- **XML tags** — `{% xml \"tag-name\" %}...{% endxml %}` emits `\u003ctag-name\u003e...\u003c/tag-name\u003e` or nothing when empty\n\n### Context blocks\n\n| Variable | Content |\n|---|---|\n| `previous_summary` | Prior compaction summary (if any) |\n| `discarded` | Serialized discarded conversation being replaced |\n| `kept_tail` | Serialized kept-tail messages that remain raw after compaction |\n| `task_state` | Live task-tracking snapshot at compaction time |\n| `files_touched` | Files-touched manifest with operation badges |\n| `focus` | Operator's `/compact \u003cfocus\u003e` directive |\n| `last_user_message` | Most recent user message text |\n\n## Configuration\n\nAll configuration lives in `config.json` files. Prompts are Liquid templates (`.md`). Both support a two-level scope cascade:\n\n| Scope | Path |\n|---|---|\n| Project | `.pi/extensions/live-compaction/` |\n| Global | `~/.pi/agent/extensions/live-compaction/` |\n\nResolution order: **project → global → built-in defaults**. Project overrides win. The TUI panel (`/live-compaction`) lets you switch between scopes when editing.\n\nEach scope directory can contain:\n\n```\nconfig.json                  # preset routing, feature toggles\ncompaction-prompt.md         # main compaction template (Liquid)\nbranch-summary-prompt.md     # branch summary template (Liquid)\n```\n\n### Custom templates\n\nDrop a `compaction-prompt.md` or `branch-summary-prompt.md` in the project or global scope directory. Templates are [LiquidJS](https://liquidjs.com/) with frontmatter knobs:\n\n```markdown\n---\npreset: deep\nthinking_level: high\n---\n{% include '_blocks' %}\n{%- if last_user_message | present %}\n\u003clatest-user-ask\u003e\n{{ last_user_message | truncate: 800 }}\n\u003c/latest-user-ask\u003e\n{% endif %}\n{% include '_contract' %}\n```\n\n### Settings panel\n\nRun `/live-compaction` to open the interactive settings panel:\n\n- Switch between global and project scope\n- Edit default preset and manage preset collection\n- Edit compaction and branch-summary prompts\n- Toggle session-model inheritance\n- Toggle files-touched manifests\n- Verify runtime status\n\n## Examples\n\nThe `examples/` directory contains 9 declarative golden-file examples covering the full feature set:\n\n| # | Example | What it demonstrates |\n|---|---|---|\n| 01 | minimal | Smallest possible composition |\n| 02 | full-blocks | Every block populated with `{% xml %}` auto-omit |\n| 03 | helpers-tour | All shipped filters/tags + Liquid built-ins |\n| 04 | tool-calls | Tool-call/tool-result loop with sibling partial |\n| 05 | pipeline-shaping | Declarative data shaping — `where`/`slice`/`size`/`truncate` |\n| 06 | layout-inheritance | `{% layout %}` + `{% block %}` inheritance |\n| 07 | files-touched-many | Multi-file manifest with every operation badge combo |\n| 08 | no-kept-tail | Empty kept-tail edge case |\n| 09 | task-continuity | Task-state snapshot and continuity guidance |\n\nRun `pnpm test` to verify all examples render to their golden expected output. See [`examples/AGENTS.md`](examples/AGENTS.md) for full details.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBuilt-in vs pi-live-compaction\u003c/strong\u003e — full comparison\u003c/summary\u003e\n\n| | Pi Built-in | pi-live-compaction |\n|---|---|---|\n| **Summary model** | Session model only | Preset routing — any model, per-preset thinking level |\n| **Prompt** | Hardcoded 5-section format | Liquid templates — fully customizable with layout inheritance and partials |\n| **Streaming** | No streaming | Live streaming with partial recovery on stream failure |\n| **Output sections** | 5 (Goal, Constraints, Progress, Decisions, Next Steps) | 11 (Brief, User intent trail, Constraints, Errors/dead ends, Key decisions, Status, Task continuity, Open issues, Next steps, Mandatory reading) |\n| **User intent** | Not preserved | Full chronological trail with quote fidelity |\n| **Task state** | Not included | `\u003ctask-state\u003e` snapshot injected and reconciled |\n| **Files touched** | Basic read/modified lists | Operation-badge manifest (R/W/E/M/D) with display paths |\n| **Focus directive** | Not supported | `/compact \u003cfocus\u003e` preserves exact operator goal |\n| **Branch summary** | 5 fixed sections | 10 sections — verbatim user messages, reusable vs branch-local split, dead ends |\n| **Settings** | None | Full TUI panel with scope switching, preset editor, prompt editor |\n| **Config** | None | Global/project scope cascade with JSON config + prompt overrides |\n\n\u003c/details\u003e\n\n## Related packages\n\n- [pi-template-kit](https://github.com/victor-software-house/pi-template-kit) — shared LiquidJS template engine, filters, and `{% xml %}` tag used by this package\n- [pi-prompt-composer](https://github.com/victor-software-house/pi-prompt-composer) — build multi-option slash commands from plain prompts with variable expansion and interactive selectors\n\n## Development\n\n```bash\npnpm install\npnpm run typecheck     # tsc --noEmit\npnpm test              # vitest (50 tests)\npnpm run preview       # render a compaction prompt to stdout\npnpm run examples:update  # regenerate golden expected files\n```\n\n## Roadmap\n\n- **Per-preset fallback chains** — each preset declares its own fallback model, enabling retry chains before falling back to the session model\n- **Per-preset prompt routing** — map preset tiers to prompt template variants so stronger models get richer contracts\n- **Context-aware model selection** — auto-select presets based on session length, available models, cost budget, and provider health\n- **Reusable TUI components** — adopt shared `SettingsPanel` / editor components for the settings panel\n\n## Inspiration\n\nThe architecture was informed by [pi-grounded-compaction](https://github.com/marcfargas/pi-grounded-compaction) — an early prototype that explored preset routing, template-driven prompts, and streaming compaction — and Pi's official [`custom-compaction.ts` example](https://github.com/earendil-works/pi-mono/blob/main/examples/extensions/custom-compaction.ts) for hooking into `session:beforeCompact`.\n\nThe compaction prompt contract, streaming engine, template system integration, TUI settings panel, files-touched manifest, task-state continuity, and branch-summary prompt are original work.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictor-software-house%2Fpi-live-compaction","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvictor-software-house%2Fpi-live-compaction","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictor-software-house%2Fpi-live-compaction/lists"}