Skip to content

opensite-ai/opensite-skills / context-management

context-management

Verified

Context virtualization skill for extending effective context window across all AI coding agents. Provides SQLite FTS5 indexing of large tool outputs, BM25 search for targeted snippet retrieval, deterministic output compression, and session checkpointing that survives context compaction. Use this skill when working in long sessions, when tool outputs are large (logs, diffs, snapshots), or when resuming after compaction. Essential for Codex CLI and other agents that lack hook-based automatic output interception.

FileKindSize
README.mdmarkdown3.3 KB
SKILL.mdskill md14.0 KB
agents/openai.yamlconfig1.1 KB
references/activation.mdmarkdown2.1 KB
scripts/ctx_checkpoint.pyexecutablescript10.5 KB
scripts/ctx_compress.pyexecutablescript12.0 KB
scripts/ctx_index.pyexecutablescript10.8 KB
scripts/ctx_search.pyexecutablescript10.3 KB
scripts/ctx_stats.pyexecutablescript7.1 KB
scripts/test_ctx.shexecutablescript7.9 KB
# Context Management Skill

> Extend effective context window across all AI coding agents with zero external dependencies.

## What It Does

Large tool outputs (file reads, git diffs, test runs, Playwright snapshots, log dumps)
burn through the context window rapidly. Agents with hook support (Claude Code) can
intercept these automatically. Agents without hooks (Codex CLI) cannot.

This skill provides the same "context virtualization" as a portable, agent-driven
workflow: the agent invokes these tools explicitly instead of hooks doing it implicitly.

### Core Features

- **SQLite FTS5 Indexing** — Store full outputs in a searchable database
- **BM25 Ranked Search** — Retrieve targeted snippets with relevance scores
- **Deterministic Compression** — Reduce large outputs to fixed line budgets
- **Session Checkpointing** — Survive context compaction with state persistence
- **Zero Dependencies** — Pure Python 3.8+, works everywhere

## Quick Start

> **Note**: Run commands from the `context-management/` directory, or use the full path to `scripts/` (e.g., `python /path/to/context-management/scripts/ctx_compress.py`).

```bash
# Index a large test output
cargo test 2>&1 | python scripts/ctx_compress.py \
  --lines 40 --index --source "test:cargo" --project .

# Later, search for specific failures
python scripts/ctx_search.py --query "FAILED assertion" --project .

# Save state before compaction
python scripts/ctx_checkpoint.py save --project . \
  --task "Implementing feature X" \
  --completed "item1, item2" \
  --next-steps "tests, docs"

# Reload after compaction
python scripts/ctx_checkpoint.py load --project .
```

## Installation

This skill is part of the [opensite-skills](https://github.com/opensite-ai/opensite-skills)
repository. Install via symlink:

```bash
cd /path/to/opensite-skills
./setup.sh  # Creates symlinks for Claude Code, Codex, Cursor
```

To run the smoke test:

```bash
chmod +x scripts/test_ctx.sh
./scripts/test_ctx.sh
```

Or copy the `context-management/` directory to your agent's skills directory.

## Verification

Run the smoke-test script after installation (no `chmod +x` needed):

```bash
cd /path/to/context-management
bash scripts/test_ctx.sh
```

This validates that all scripts work correctly on your platform.

## Documentation

- **Full documentation**: [SKILL.md](SKILL.md)
- **Activation guide**: [references/activation.md](references/activation.md)

## Platform Notes

### FTS5 Availability

Most platforms ship Python with SQLite FTS5 support (macOS, Windows, standard Linux).

On platforms without FTS5 (some Alpine-based Docker images, older Linux distros):
- The skill falls back to FTS4 automatically
- Search works, but results are unranked (BM25 unavailable)
- All other features work normally

### Concurrent Agents

Multiple agents working in the same project directory share the same `.ctx/context.db`.
SQLite WAL mode handles concurrent access safely for typical use cases.

For complete isolation, use separate project directories or the `CTX_SESSION_ID`
environment variable (see SKILL.md for details).

## Related Projects

This skill implements the same context virtualization pattern as
[mksglu/context-mode](https://github.com/mksglu/context-mode), but as a portable,
zero-dependency Python toolkit that works across all AI coding agents.

## License

MIT
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall