# 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