95 lines
4.5 KiB
Markdown
95 lines
4.5 KiB
Markdown
# AirContext
|
||
|
||
A Claude Code plugin that **replaces auto-compact with rule-driven, automated, externally-summarised compaction**, then **auto-resumes** the session so long-running agent loops never break.
|
||
|
||
## Why
|
||
|
||
Claude Code's built-in auto-compact triggers on context pressure and uses a generic strategy. In a large project, frequent generic compaction degrades subsequent generation quality. AirContext lets you:
|
||
|
||
1. Disable Claude's auto-compact (via PreCompact hook).
|
||
2. Trigger compaction on **your** schedule (token-ratio threshold + cooldown).
|
||
3. Run compaction in **your** LLM (any OpenAI-compatible endpoint — DeepSeek, Ollama, vLLM, LM Studio, etc.) using **your** rules (`AirContext/rules.md`).
|
||
4. Apply the result by appending an isolated summary chain (`parentUuid: null`) to the session JSONL, then automatically restart `claude --resume <id>` and inject a continuation prompt so an in-flight agent loop picks back up unattended.
|
||
|
||
## How it works
|
||
|
||
```
|
||
$ aircontext # wrapper around `claude`
|
||
│
|
||
▼
|
||
(loops) ← spawns claude → user works as normal
|
||
│
|
||
│ PostToolUse hook (every tool call):
|
||
│ • estimate active-chain tokens
|
||
│ • if > threshold and cooldown elapsed:
|
||
│ fork compactor.py (background, non-blocking)
|
||
│
|
||
│ compactor.py:
|
||
│ • read JSONL → render head as plain text
|
||
│ • call LLM with rules.md as system prompt
|
||
│ • backup JSONL → snapshots/<ts>-<sid>.jsonl
|
||
│ • append [summary, continuation] with parentUuid=null
|
||
│ • set state.compaction_ready = true
|
||
│
|
||
◄──────────┘
|
||
wrapper watcher sees ready → SIGTERM claude → spawn `claude --resume <id>`
|
||
│
|
||
▼
|
||
new claude loads JSONL: latest leaf is the continuation prompt → auto-replies
|
||
the in-flight task continues with ~10× smaller context.
|
||
```
|
||
|
||
## Install
|
||
|
||
```bash
|
||
# from the marketplace once published
|
||
/plugin install aircontext@<your-marketplace>
|
||
|
||
# or directly via settings.json
|
||
{
|
||
"extraKnownMarketplaces": {
|
||
"aircontext-mkt": { "source": { "source": "github", "repo": "<you>/aircontext-plugin" } }
|
||
},
|
||
"enabledPlugins": { "aircontext@aircontext-mkt": true }
|
||
}
|
||
```
|
||
|
||
Requires Python ≥ 3.10 and `pyyaml`. The wrapper assumes `claude` is on PATH.
|
||
|
||
## Use
|
||
|
||
```bash
|
||
cd <your-project>
|
||
aircontext # instead of `claude`
|
||
```
|
||
|
||
First run creates `<project>/AirContext/` with `config.yaml`, `rules.md`, and a per-project README. Edit `config.yaml` (especially `backend.api_key`), then re-run.
|
||
|
||
## Per-project files (`AirContext/`)
|
||
|
||
| File | Purpose |
|
||
| ----------------- | ------------------------------------------------------------- |
|
||
| `config.yaml` | Backend, trigger threshold, cooldown, continuation prompt |
|
||
| `rules.md` | What to keep / drop — sent to LLM as system prompt |
|
||
| `state.json` | Runtime state (managed by plugin, do not edit by hand) |
|
||
| `snapshots/` | JSONL backup before each compaction (rotate via `max_snapshots`) |
|
||
|
||
## Slash commands
|
||
|
||
| Command | Purpose |
|
||
| ---------------------- | -------------------------------------------------------- |
|
||
| `/aircontext-init` | (Re)install templates into the current project |
|
||
| `/aircontext-now` | Force a compaction immediately (bypasses cooldown) |
|
||
| `/aircontext-status` | Show config, last compaction, snapshot count |
|
||
| `/aircontext-pause` | Toggle (or `on`/`off`) automatic compaction |
|
||
|
||
## Caveats
|
||
|
||
- **You must launch via `aircontext`, not `claude`, for auto-resume to work.** Without the wrapper, the compactor still prepares the snapshot but you must `claude --resume <id>` manually for it to take effect.
|
||
- The JSONL transcript format is **not a stable public API**. AirContext logs the observed `version` field; if it sees an unfamiliar version, it warns and you may want to enable `safety.dry_run: true` until you've verified compatibility on your side.
|
||
- A small fixed cost (system prompt, CLAUDE.md, tool definitions, skills) is reloaded into context every session — this is a Claude Code property, not something AirContext can shrink.
|
||
|
||
## License
|
||
|
||
MIT
|