{"id":50683276,"url":"https://github.com/alpertarhan/pi-smart-compact","last_synced_at":"2026-06-08T21:00:34.551Z","repository":{"id":358354057,"uuid":"1241058151","full_name":"alpertarhan/pi-smart-compact","owner":"alpertarhan","description":"Verification-oriented smart compaction extension for the Pi Coding Agent.","archived":false,"fork":false,"pushed_at":"2026-05-25T01:47:34.000Z","size":7023,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T03:23:56.660Z","etag":null,"topics":["ai-agent","bun","context-compression","llm","pi","pi-coding-agent","pi-extension","smart-compaction","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/pi-smart-compact","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/alpertarhan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","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-05-16T22:57:07.000Z","updated_at":"2026-05-25T01:44:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alpertarhan/pi-smart-compact","commit_stats":null,"previous_names":["alpertarhan/pi-smart-compact"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/alpertarhan/pi-smart-compact","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpertarhan%2Fpi-smart-compact","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpertarhan%2Fpi-smart-compact/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpertarhan%2Fpi-smart-compact/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpertarhan%2Fpi-smart-compact/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alpertarhan","download_url":"https://codeload.github.com/alpertarhan/pi-smart-compact/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpertarhan%2Fpi-smart-compact/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34080026,"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","bun","context-compression","llm","pi","pi-coding-agent","pi-extension","smart-compaction","typescript"],"created_at":"2026-06-08T21:00:17.111Z","updated_at":"2026-06-08T21:00:34.536Z","avatar_url":"https://github.com/alpertarhan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-smart-compact\n\n[CI](https://github.com/alpertarhan/pi-smart-compact/actions/workflows/ci.yml) · [npm](https://www.npmjs.com/package/pi-smart-compact) · [MIT License](./LICENSE) · [Pi extension](https://github.com/earendil-works/pi)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/assets/pi-smart-compact.png\" alt=\"pi-smart-compact\" width=\"420\" /\u003e\n\u003c/p\u003e\n\n\u003e Verification-oriented smart compaction for the [Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent).\n\n`pi-smart-compact` replaces blind conversation trimming with a structured compaction pipeline that tries to preserve what an agent actually needs to continue working: the goal, modified files, unresolved errors, decisions, constraints, and open follow-up loops.\n\nIt uses an **EESV** pipeline:\n\n**Extract → Explore → Synthesize → Verify**\n\n## Highlights\n\n- **Pi-native integration** — `/smart-compact`, `smart_compact`, and `session_before_compact` support.\n- **Verification-oriented output** — deterministic extraction and repair before trusting LLM synthesis.\n- **Adaptive cost profile** — skips unnecessary work on small sessions and uses chunking only when useful.\n- **Operational safety** — pending summaries expire, backups are available, and metrics make regressions visible.\n- **Companion-friendly** — designed to coexist with context hygiene tools such as `pi-toolkit`.\n\nUnder the hood, the design is grounded in two core ideas:\n\n- **agentic compaction**: let the system inspect and reason about the session instead of collapsing everything into generic prose\n- **Kamradt-style chunking**: break large conversations into more coherent segments before synthesis\n\n---\n\n## What this project is\n\nThis package is a **Pi extension** with three integration surfaces:\n\n| Surface | Purpose |\n| --- | --- |\n| `/smart-compact` | manual compaction from the chat UI |\n| `session_before_compact` | auto-run before Pi's default compaction |\n| `smart_compact` tool | agent-callable compaction for long sessions |\n\nThe extension stages a short-lived pending summary in memory, then hands it back to Pi when compaction is applied.\n\n---\n\n## Project status\n\nThis is an actively maintained Pi extension. The public API is intentionally small, but the internals are still evolving as Pi's compaction lifecycle and extension APIs mature. Pin versions in production workflows if compaction behavior is mission-critical.\n\n## Compatibility note\n\n`pi-smart-compact` sits close to Pi's compaction path: it registers `session_before_compact`, reads the active branch and session log, stages a pending summary, and may call Pi's native compaction flow from `/smart-compact`.\n\nBecause of that, use extra care with extensions that also manipulate:\n\n- **compaction hooks** — especially extensions that return a custom result from `session_before_compact`\n- **session / branch history** — rewriting, pruning, reordering, or replacing entries before compaction\n- **message identity** — removing entry IDs, tool-call IDs, or tool-result metadata used to align log entries\n- **tool output content** — truncating or rewriting `toolResult` messages before extraction\n- **compaction boundaries** — moving the keep/discard split or splitting `toolCall` / `toolResult` pairs\n- **session log storage** — replacing or deleting Pi's `.jsonl` logs under `~/.pi/agent/sessions`\n\nIt is intentionally compatible with, and recommended alongside, [`pi-toolkit`](https://github.com/ersintarhan/pi-toolkit): pi-toolkit handles everyday context hygiene such as anchors, pivots, status lines, and old tool-output trimming; `pi-smart-compact` handles high-pressure verified compaction. The integration protects recent pi-toolkit anchors and can recover original tool outputs from the session log when older tool results were trimmed.\n\nIf you use another automatic compaction or context-rewriting extension, prefer enabling only one `session_before_compact` owner unless the hook order and returned values are explicitly coordinated.\n\n---\n\n## Why it exists\n\nDefault compaction often loses the parts that matter most during coding work:\n\n- which files were actually changed\n- which errors are still unresolved\n- what the user explicitly asked for\n- what decisions already won\n- what should happen next\n\n`pi-smart-compact` is built to preserve that operational context instead of producing a vague recap.\n\n---\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[Extract\u003cbr/\u003edeterministic facts] --\u003e B[Explore\u003cbr/\u003eoptional targeted analysis]\n    B --\u003e C[Synthesize\u003cbr/\u003esingle-pass or chunked summary]\n    C --\u003e D[Verify\u003cbr/\u003escore gaps and repair]\n    D --\u003e E[Return smart compaction to Pi]\n```\n\n### Pipeline summary\n\n1. **Extract**\n   - deterministically pulls files, errors, decisions, constraints, topics, and open loops from the session\n2. **Explore**\n   - optionally inspects the conversation more deeply when the session is complex\n3. **Synthesize**\n   - creates either a single-pass summary or a chunked hierarchical summary\n4. **Verify**\n   - checks the result against extracted facts and patches missing critical details\n\nIn short: **facts first, synthesis second, verification last**.\n\n---\n\n## What it tries to preserve\n\n- user goal\n- constraints and preferences\n- modified / read / deleted files\n- unresolved and resolved errors\n- key decisions\n- open follow-up work\n- critical context needed for the next turn\n- delta from the previous compaction\n\n---\n\n## Installation\n\n### npm / Pi package\n\n```bash\npi install npm:pi-smart-compact\n```\n\n### GitHub\n\n```bash\npi install git:github.com/alpertarhan/pi-smart-compact\n```\n\n### Local development\n\n```bash\ncd ~/.pi/agent/extensions\ngit clone https://github.com/alpertarhan/pi-smart-compact.git\ncd pi-smart-compact\nbun install\nbun run build\n```\n\n---\n\n## Quick start\n\n### Interactive\n\n```bash\n/smart-compact\n```\n\nWith no arguments, the extension opens a small picker for:\n\n1. model\n2. profile\n\n### Direct command examples\n\n```bash\n/smart-compact anthropic/claude-sonnet-4 balanced\n/smart-compact dry-run\n/smart-compact debug\n/smart-compact metrics\n/smart-compact dashboard\n/smart-compact \"focus on auth changes and unresolved follow-up work\"\n```\n\n### Tool usage\n\n```json\n{\n  \"name\": \"smart_compact\",\n  \"parameters\": {\n    \"profile\": \"balanced\",\n    \"verbose\": false,\n    \"dry_run\": false,\n    \"report\": false,\n    \"dashboard\": false\n  }\n}\n```\n\nThe tool prepares a pending smart summary and lets Pi consume it on the next natural compaction.\n\n---\n\n## Usage notes\n\n- auto/tool compaction is skipped when the context is still small enough (default: below 60% actual context usage)\n- explicit manual `/smart-compact` commands bypass the 60% adaptive gate because the user intentionally requested compaction\n- pi-toolkit `tool=XX%` status means tool-output ratio, **not** context fullness; smart-compact uses actual `context=XX%`\n- the tool path does **not** compact the conversation mid-turn\n- pending summaries are kept in memory for **5 minutes**\n- exploration is adaptive and may be skipped for simple sessions\n- use `/smart-compact metrics` for profile/provider comparisons\n- use `/smart-compact dashboard` to open the interactive TUI dashboard (overview, latest run, current session, recent runs, or write HTML)\n\nThis keeps the extension helpful without forcing extra work when it is not needed.\n\n---\n\n## Configuration\n\nAdd this to `~/.pi/agent/settings.json`:\n\n```json\n{\n  \"smartCompact\": {\n    \"profile\": \"balanced\",\n    \"summaryModel\": \"anthropic/claude-sonnet-4\",\n    \"segmentationModel\": \"anthropic/claude-haiku-3\",\n    \"autoTrigger\": true,\n    \"autoTriggerTimeoutMs\": 120000,\n    \"minContextPercent\": 60,\n    \"backupEnabled\": true,\n    \"profiles\": {\n      \"balanced\": {\n        \"summaryBudgetTokens\": 6000,\n        \"keepRecentTokens\": 20000\n      }\n    }\n  }\n}\n```\n\n### Supported keys\n\n| Key | Type | Default |\n| --- | --- | --- |\n| `profile` | `light \\| balanced \\| aggressive` | `balanced` |\n| `summaryModel` | `string \\| null` | `null` |\n| `segmentationModel` | `string \\| null` | `null` |\n| `autoTrigger` | `boolean` | `true` |\n| `autoTriggerTimeoutMs` | `number` | `120000` |\n| `minContextPercent` | `number` | `60` |\n| `backupEnabled` | `boolean` | `true` |\n| `backupDir` | `string` | `~/.pi/agent/compact-backups` |\n| `profiles` | partial per-profile overrides | built-ins |\n\n### Profiles\n\n| Profile | Summary budget | Keep recent | Typical use |\n| --- | ---: | ---: | --- |\n| `light` | 10000 | 30000 | preserve more detail |\n| `balanced` | 6000 | 20000 | default general use |\n| `aggressive` | 3000 | 10000 | tighter summaries |\n\n### Backward compatibility\n\nThe extension still accepts the old config key `semanticCompact`, but `smartCompact` is the current key.\n\n---\n\n## Output contract\n\nGenerated summaries are expected to use this structure:\n\n```markdown\n## Goal\n## Constraints \u0026 Preferences\n## Progress\n### Done\n### In Progress\n### Blocked\n## Key Decisions\n## Files Modified\n## Files Read\n## Open Loops\n## Changes Since Last Compaction\n## Next Steps\n## Critical Context\n## Topics Covered\n```\n\nThe extension also builds a structured `CompactionState` for reuse across later compactions.\n\n---\n\n## Safeguards\n\nThe current design includes:\n\n- deterministic extraction before summarization\n- adaptive exploration\n- chunked synthesis for larger sessions\n- deterministic verification scoring\n- deterministic patching before LLM patching\n- hallucinated file-reference detection\n- open-loop injection\n- project fingerprinting and delta tracking\n- provider-specific timeout and single-pass strategies\n- multimodal attachment metadata preservation\n- backup creation before compaction\n- metrics logging, profile/provider comparison, and damage detection\n\n---\n\n## Runtime artifacts\n\nAt runtime, the extension writes to paths under `~/.pi/agent/`, including:\n\n- `settings.json`\n- `compact-backups/`\n- `.cache/compact-extraction-\u003csession\u003e.json`\n- `.cache/compact-metrics.jsonl`\n- `.cache/smart-compact-report.html`\n- `.cache/smart-compact/projects/\u003cprojectId\u003e.json`\n- `.cache/smart-compact/states/\u003cprojectId\u003e.json`\n- `.cache/smart-compact/damage-reports.jsonl`\n\n---\n\n## Repository layout\n\n```text\n.\n├── src/\n│   ├── index.ts              # extension registration + command routing\n│   ├── constants.ts          # version, thresholds, prompts\n│   ├── types.ts              # shared types\n│   ├── app/                  # orchestration layer\n│   │   ├── run-smart-compact.ts   # pipeline orchestrator (was core.ts)\n│   │   ├── run-context.ts         # typed stage chain\n│   │   ├── explore-wrap.ts        # explore re-export shim\n│   │   └── steps/                 # 10 stage modules\n│   │       ├── prepare.ts   →   resolves config + auth\n│   │       ├── window.ts    →   picks compaction window\n│   │       ├── recover.ts   →   recovers truncated messages\n│   │       ├── tier.ts      →   chooses compaction tier\n│   │       ├── extract.ts   →   pruning + extraction + cache\n│   │       ├── synthesize.ts→   single-pass / EESV summarization\n│   │       ├── verify.ts    →   structural verify + repair\n│   │       ├── state.ts     →   state machine + open loops\n│   │       ├── persist.ts   →   apply compaction\n│   │       └── metrics.ts   →   success / failure metrics\n│   ├── domain/               # pure semantics (no I/O)\n│   │   ├── summary-schema.ts\n│   │   └── summary-parse.ts\n│   ├── phases/               # algorithms\n│   │   ├── explore.ts\n│   │   ├── synthesize.ts\n│   │   └── verify.ts\n│   ├── infra/                # external-world interaction\n│   │   ├── fs.ts                # atomic writes, advisory locks\n│   │   ├── paths.ts             # canonical paths\n│   │   ├── git.ts               # git-root discovery (cached)\n│   │   ├── clock.ts             # injectable clock\n│   │   ├── llm-client.ts        # LLM client seam\n│   │   ├── llm-retry.ts         # 429/5xx backoff\n│   │   └── services.ts          # per-run services container\n│   ├── ui/                   # TUI overlays + dashboard\n│   │   ├── overlays.ts\n│   │   └── dashboard-format.ts\n│   └── utils/                # 13 focused utility modules\n├── test/                     # 280+ tests across 28 files\n├── docs/\n├── dist/\n└── package.json\n```\n\nSee `ARCHITECTURE.md` for the full responsibility breakdown of each layer.\n\n---\n\n## Development\n\n```bash\nbun install\nbun test\nbun run build\nbun run typecheck\n```\n\nBuild output is published from `dist/`. Pull requests are expected to pass the same verification in GitHub Actions before merge.\n\n---\n\n## Project docs\n\n- [`CHANGELOG.md`](./CHANGELOG.md) — release history\n- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — system design and execution model\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contributor workflow and expectations\n- [`SECURITY.md`](./SECURITY.md) — vulnerability reporting and data-handling notes\n- [`SUPPORT.md`](./SUPPORT.md) — where to ask for help\n- [`docs/RELEASE.md`](./docs/RELEASE.md) — release checklist\n\n---\n\n## License\n\nMIT © [Alper Tarhan](https://github.com/alpertarhan)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpertarhan%2Fpi-smart-compact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falpertarhan%2Fpi-smart-compact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpertarhan%2Fpi-smart-compact/lists"}