AirCoding/AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/README.md

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

# 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

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