# disler/self-compact-pi-agent architecture

> Architecture diagram of the GitHub repository disler/self-compact-pi-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/disler/self-compact-pi-agent
- Repository: https://github.com/disler/self-compact-pi-agent

## Overview

Self Compact is a Pi coding-agent extension for autonomous agents that monitor context usage, write a handoff note, trigger compaction, and resume without a human prompt. The main path runs from Pi lifecycle and usage events through threshold guidance and forced tool gating to the self_compact handoff, summary generation, and note restoration. It also exposes live context data and a footer gauge. README capabilities are included; wiring details not established by the sampled excerpts are omitted.

Main entry points: [`apps/self-compact/extensions/self-compact/self-compact.ts`](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts) (Extension Entry), [`apps/self-compact/extensions/self-compact/summary.ts`](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/summary.ts) (Summary Generator), [`apps/self-compact/extensions/self-compact/state.ts`](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/state.ts) (Handoff State), [`apps/self-compact/extensions/self-compact/thresholds.ts`](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/thresholds.ts) (Threshold Resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension Runtime"]
  node_extension["Extension Entry<br/>[self-compact.ts]"]
  node_usage["Context Usage"]
  node_tool_gate["Forced Tool Gate<br/>[self-compact.ts]"]
end

subgraph group_handoff["Compaction Handoff"]
  node_state["Handoff State<br/>[state.ts]"]
  node_session[("Pi Session")]
  node_summary["Summary Generator<br/>[summary.ts]"]
  node_note["Returned Note"]
end

subgraph group_interface["Agent Interface"]
  node_context_tool["view_context Tool<br/>[self-compact.ts]"]
  node_footer["Context Footer<br/>[context-bar.ts]"]
  node_compact_tool["self_compact Tool<br/>[self-compact.ts]"]
end

subgraph group_configuration["Thresholds And Prompts"]
  node_thresholds["Threshold Resolver<br/>[thresholds.ts]"]
  node_defaults["Threshold Defaults<br/>[defaults.ts]"]
  node_prompts["Prompt Loader<br/>[prompts.ts]"]
  node_prompt_files["Editable Prompts"]
end

node_agent(("Autonomous Agent"))
node_pi["Pi Host"]
node_model["Model Provider"]

node_agent -->|"sends prompts"| node_pi
node_pi -->|"dispatches events"| node_extension
node_pi -->|"reports usage"| node_extension
node_extension -->|"resolves limits"| node_thresholds
node_thresholds -->|"uses defaults"| node_defaults
node_extension -->|"loads guidance"| node_prompts
node_prompts -->|"reads files"| node_prompt_files
node_extension -->|"enforces cutoff"| node_tool_gate
node_extension -->|"registers tool"| node_context_tool
node_context_tool -->|"returns numbers"| node_usage
node_extension -->|"renders gauge"| node_footer
node_extension -->|"registers tool"| node_compact_tool
node_compact_tool -->|"saves note"| node_state
node_extension -->|"journals state"| node_session
node_extension -->|"requests summary"| node_summary
node_summary -->|"calls compaction"| node_pi
node_summary -->|"requests completion"| node_model
node_pi -->|"stores compaction"| node_session
node_extension -->|"recovers handoff"| node_state
node_state -->|"reads entries"| node_session
node_extension -->|"returns verbatim"| node_note
node_note -->|"resumes work"| node_agent

click node_extension "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts"
click node_thresholds "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/thresholds.ts"
click node_defaults "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/defaults.ts"
click node_prompts "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/prompts.ts"
click node_prompt_files "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/.pi/self-compact/USER_PROMPT_SOFT_SELF_COMPACT.md"
click node_context_tool "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts"
click node_footer "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/context-bar.ts"
click node_tool_gate "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts"
click node_compact_tool "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts"
click node_state "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/state.ts"
click node_summary "https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/summary.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_usage,node_tool_gate toneBlue
class node_state,node_session,node_summary,node_note toneAmber
class node_context_tool,node_footer,node_compact_tool toneMint
class node_thresholds,node_defaults,node_prompts,node_prompt_files toneRose
class node_agent,node_pi,node_model toneIndigo
```

## Components

### Extension Runtime

- [Extension Entry](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts): `apps/self-compact/extensions/self-compact/self-compact.ts`
- **Context Usage**
- [Forced Tool Gate](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts): `apps/self-compact/extensions/self-compact/self-compact.ts`

### Compaction Handoff

- [Handoff State](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/state.ts): `apps/self-compact/extensions/self-compact/state.ts`
- **Pi Session**
- [Summary Generator](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/summary.ts): `apps/self-compact/extensions/self-compact/summary.ts`
- **Returned Note**

### Agent Interface

- [view_context Tool](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts): `apps/self-compact/extensions/self-compact/self-compact.ts`
- [Context Footer](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/context-bar.ts): `apps/self-compact/extensions/self-compact/context-bar.ts`
- [self_compact Tool](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/self-compact.ts): `apps/self-compact/extensions/self-compact/self-compact.ts`

### Thresholds And Prompts

- [Threshold Resolver](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/thresholds.ts): `apps/self-compact/extensions/self-compact/thresholds.ts`
- [Threshold Defaults](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/defaults.ts): `apps/self-compact/extensions/self-compact/defaults.ts`
- [Prompt Loader](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/extensions/self-compact/prompts.ts): `apps/self-compact/extensions/self-compact/prompts.ts`
- [Editable Prompts](https://github.com/disler/self-compact-pi-agent/blob/main/apps/self-compact/.pi/self-compact/USER_PROMPT_SOFT_SELF_COMPACT.md): `apps/self-compact/.pi/self-compact/USER_PROMPT_SOFT_SELF_COMPACT.md`

### Other components

- **Autonomous Agent**
- **Pi Host**
- **Model Provider**

## Connections

- Autonomous Agent → Pi Host: sends prompts
- Pi Host → Extension Entry: dispatches events
- Pi Host → Extension Entry: reports usage
- Extension Entry → Threshold Resolver: resolves limits
- Threshold Resolver → Threshold Defaults: uses defaults
- Extension Entry → Prompt Loader: loads guidance
- Prompt Loader → Editable Prompts: reads files
- Extension Entry → Forced Tool Gate: enforces cutoff
- Extension Entry → view_context Tool: registers tool
- view_context Tool → Context Usage: returns numbers
- Extension Entry → Context Footer: renders gauge
- Extension Entry → self_compact Tool: registers tool
- self_compact Tool → Handoff State: saves note
- Extension Entry → Pi Session: journals state
- Extension Entry → Summary Generator: requests summary
- Summary Generator → Pi Host: calls compaction
- Summary Generator → Model Provider: requests completion
- Pi Host → Pi Session: stores compaction
- Extension Entry → Handoff State: recovers handoff
- Handoff State → Pi Session: reads entries
- Extension Entry → Returned Note: returns verbatim
- Returned Note → Autonomous Agent: resumes work