contextos

ContextOS

Intelligent context window management for Claude Code.

What is ContextOS?

ContextOS is a Claude Code plugin that optimizes context window usage through:

• Compression: Content-aware compression of shell output, file reads, and search results
• Caching: SQLite-based L2 cache for fast re-access of previously seen content
• Adaptive Eviction: ARC (Adaptive Replacement Cache) policy that self-tunes between recency and frequency
• Working Set Tracking: Preserves actively-used content through compaction cycles
• Cooperative Memory: Claude participates in memory management for cleaner context

Security & Privacy 🛡️

ContextOS is built with a local-first, zero-telemetry architecture. We understand that your context window often contains sensitive code and data.

How We Protect Your Data

• No External Calls: ContextOS never makes external network requests. All data stays on your machine.
• Local SQLite Storage: Session data is stored in a local SQLite database in ~/.claude/contextos/.
• Transparency: The entire project is open-source. You can audit the build process and source code at any time.

Audit the Package

To verify that no local environment data is included in the package, you can run:

npm pack --dry-run

This will show you the exact list of files bundled in the distribution.

Installation

# From npm (recommended)
claude plugin install contextos

# From source
git clone https://github.com/johnnyhliang/contextos
cd contextos
npm install && npm run build
claude plugin add ./contextos

Features

• File Map Generation: Project-wide overview injected at session start (~30 tokens per file vs. reading all files)
• Differential Updates: Re-reads serve only the diff since last read (80-95% savings)
• Shell Compression: 60-90% reduction on common dev commands (git, npm, test runners)
• Cache Serving: Re-reads skip disk I/O when file unchanged
• Thrashing Detection: Automatically switches to compression-only mode when fault rate spikes
• Cross-Session Memory: L3 persistent store carries knowledge between sessions

Architecture

Five engines working together:
1. Input Gate     — Content-aware compression
2. Context Ledger — Tracks what's in the context window
3. Eviction       — ARC policy + pin table + working set
4. Fault Handler  — Serves cached content on demand
5. L2 Cache       — SQLite with full content + compressed summaries

How It Works

ContextOS uses Claude Code's hook system:

• SessionStart: Injects file map + session summary
• PreToolUse: Serves cached content, rewrites commands
• PostToolUse: Compresses output, caches in SQLite
• PreCompact: Preserves working set before compaction
• PostCompact: Re-injects critical context after compaction

All hooks run transparently — no user intervention needed.

Development

# Install dependencies
npm install

# Build (TypeScript + MCP server bundle)
npm run build

# Run tests
npm test

# Type-check only
npm run typecheck

# Watch mode
npm run dev

# Bump version (syncs package.json and plugin.json)
npm run bump-version

Contributing

See CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.