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

scripts/test_ctx.sh

View on GitHub
#!/bin/bash
#
# test_ctx.sh — Smoke-test script for context-management skill
#
# Verifies that all scripts can run successfully against synthetic input.
# Run this after installation to catch broken setups before a long session.
#
# Usage:
#   cd /path/to/context-management
#   ./scripts/test_ctx.sh
#
# Exit codes:
#   0 — all tests passed
#   1 — one or more tests failed
#

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
TEST_PROJECT="/tmp/ctx-test-$$"

# Create test content with a heredoc to avoid shell interpretation
create_test_content() {
cat <<'EOF'
# Test File

This is a test file with multiple lines.
It has some error-like content: ERROR: something went wrong.
And some warning content: WARNING: deprecated API.
And some structure: ## Section Heading

```python
def test_function():
    return 42
```

End of test content.
EOF
}

TEST_CONTENT=$(create_test_content)

echo "=== Context Management Smoke Test ==="
echo ""

# Cleanup function
cleanup() {
    echo ""
    echo "Cleaning up test directory..."
    rm -rf "$TEST_PROJECT"
}
trap cleanup EXIT

# Create test project directory
mkdir -p "$TEST_PROJECT"
cd "$TEST_PROJECT"

echo "Test project: $TEST_PROJECT"
echo ""

# Test 1: ctx_index.py from stdin
echo "Test 1: Indexing content from stdin..."
echo "$TEST_CONTENT" | python "$SCRIPT_DIR/ctx_index.py" \
    --source "test:stdin" \
    --project . \
    || { echo "  ✗ FAIL: ctx_index.py (stdin)"; exit 1; }
echo "  ✓ PASS: ctx_index.py (stdin)"

# Test 2: ctx_index.py from file
echo "$TEST_CONTENT" > test_file.txt
echo "Test 2: Indexing content from file..."
python "$SCRIPT_DIR/ctx_index.py" \
    --source "test:file" \
    --file test_file.txt \
    --project . \
    || { echo "  ✗ FAIL: ctx_index.py (file)"; exit 1; }
echo "  ✓ PASS: ctx_index.py (file)"

# Test 3: ctx_index.py with tags
echo "Test 3: Indexing content with tags..."
echo "$TEST_CONTENT" | python "$SCRIPT_DIR/ctx_index.py" \
    --source "test:tagged" \
    --tags "test,smoke,validation" \
    --project . \
    || { echo "  ✗ FAIL: ctx_index.py (with tags)"; exit 1; }
echo "  ✓ PASS: ctx_index.py (with tags)"

# Test 4: ctx_search.py basic query
echo "Test 4: Searching indexed content..."
RESULT=$(python "$SCRIPT_DIR/ctx_search.py" \
    --query "error" \
    --project .)
if echo "$RESULT" | grep -q "ERROR"; then
    echo "  ✓ PASS: ctx_search.py (basic query)"
else
    echo "  ✗ FAIL: ctx_search.py (basic query)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 5: ctx_search.py --list-sources
echo "Test 5: Listing indexed sources..."
RESULT=$(python "$SCRIPT_DIR/ctx_search.py" \
    --list-sources \
    --project .)
if echo "$RESULT" | grep -q "test:"; then
    echo "  ✓ PASS: ctx_search.py (list sources)"
else
    echo "  ✗ FAIL: ctx_search.py (list sources)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 6: ctx_search.py --stats
echo "Test 6: Showing database stats..."
RESULT=$(python "$SCRIPT_DIR/ctx_search.py" \
    --stats \
    --project .)
if echo "$RESULT" | grep -q "Total chunks"; then
    echo "  ✓ PASS: ctx_search.py (stats)"
else
    echo "  ✗ FAIL: ctx_search.py (stats)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 6b: Verify BM25 ranking is active
echo "Test 6b: Verifying BM25 ranking is active..."
RESULT=$(python "$SCRIPT_DIR/ctx_search.py" \
    --query "error" \
    --project .)
if echo "$RESULT" | grep -qE "^\[(-?[0-9]+\.[0-9]+)\]"; then
    echo "  ✓ PASS: ctx_search.py (BM25 rank active)"
elif echo "$RESULT" | grep -q "\[n/a\]"; then
    echo "  ⚠ WARN: BM25 unavailable (FTS4 fallback — SQLite < 3.9.0)"
    echo "    Search works; results in insertion order, not relevance ranked."
else
    echo "  ✗ FAIL: ctx_search.py (unexpected rank format)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 7: ctx_compress.py basic
echo "Test 7: Compressing content..."
RESULT=$(echo "$TEST_CONTENT" | python "$SCRIPT_DIR/ctx_compress.py" --lines 10)
if echo "$RESULT" | grep -q "compressed:"; then
    echo "  ✓ PASS: ctx_compress.py (basic)"
else
    echo "  ✗ FAIL: ctx_compress.py (basic)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 8: ctx_compress.py with --index
echo "Test 8: Compressing and indexing..."
RESULT=$(echo "$TEST_CONTENT" | python "$SCRIPT_DIR/ctx_compress.py" \
    --lines 10 \
    --index \
    --source "test:compressed" \
    --project .)
if echo "$RESULT" | grep -q "indexed as"; then
    echo "  ✓ PASS: ctx_compress.py (with --index)"
else
    echo "  ✗ FAIL: ctx_compress.py (with --index)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 9: ctx_checkpoint.py save
echo "Test 9: Saving checkpoint..."
python "$SCRIPT_DIR/ctx_checkpoint.py" save \
    --project . \
    --task "Test task with multiple clauses, including commas, in the description" \
    --completed "item1, item2, item3" \
    --in-progress "current work" \
    --next-steps "step1, step2" \
    --decisions "Decision A: use X, Decision B: avoid Y" \
    --context "Test context" \
    || { echo "  ✗ FAIL: ctx_checkpoint.py (save)"; exit 1; }
if [ -f .ctx/checkpoint.md ]; then
    echo "  ✓ PASS: ctx_checkpoint.py (save)"
else
    echo "  ✗ FAIL: ctx_checkpoint.py (save) - checkpoint file not created"
    exit 1
fi

# Test 10: ctx_checkpoint.py load
echo "Test 10: Loading checkpoint..."
RESULT=$(python "$SCRIPT_DIR/ctx_checkpoint.py" load --project .)
if echo "$RESULT" | grep -q "Test task"; then
    echo "  ✓ PASS: ctx_checkpoint.py (load)"
else
    echo "  ✗ FAIL: ctx_checkpoint.py (load)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 11: ctx_checkpoint.py load --json
echo "Test 11: Loading checkpoint as JSON..."
RESULT=$(python "$SCRIPT_DIR/ctx_checkpoint.py" load --project . --json)
if echo "$RESULT" | grep -q '"task"'; then
    echo "  ✓ PASS: ctx_checkpoint.py (load --json)"
else
    echo "  ✗ FAIL: ctx_checkpoint.py (load --json)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 12: ctx_checkpoint.py list
echo "Test 12: Listing checkpoints..."
RESULT=$(python "$SCRIPT_DIR/ctx_checkpoint.py" list --project .)
# Accept either archived checkpoints or no archived checkpoints
if echo "$RESULT" | grep -qE "(Archived|No archived)"; then
    echo "  ✓ PASS: ctx_checkpoint.py (list)"
else
    echo "  ✗ FAIL: ctx_checkpoint.py (list)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 13: ctx_stats.py
echo "Test 13: Showing compression stats..."
RESULT=$(python "$SCRIPT_DIR/ctx_stats.py" --project .)
if echo "$RESULT" | grep -q "Context Savings Report"; then
    echo "  ✓ PASS: ctx_stats.py"
else
    echo "  ✗ FAIL: ctx_stats.py"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 14: ctx_stats.py --brief
echo "Test 14: Brief stats output..."
RESULT=$(python "$SCRIPT_DIR/ctx_stats.py" --brief --project .)
if echo "$RESULT" | grep -q "ctx-stats:"; then
    echo "  ✓ PASS: ctx_stats.py (--brief)"
else
    echo "  ✗ FAIL: ctx_stats.py (--brief)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 15: ctx_search.py --delete-source
echo "Test 15: Deleting specific source..."
RESULT=$(python "$SCRIPT_DIR/ctx_search.py" \
    --delete-source "test:compressed" \
    --project .)
if echo "$RESULT" | grep -q "Deleted"; then
    echo "  ✓ PASS: ctx_search.py (--delete-source)"
else
    echo "  ✗ FAIL: ctx_search.py (--delete-source)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 16: ctx_search.py --clear-all
echo "Test 16: Clearing all content..."
RESULT=$(python "$SCRIPT_DIR/ctx_search.py" --clear-all --project .)
if echo "$RESULT" | grep -q "Cleared all"; then
    echo "  ✓ PASS: ctx_search.py (--clear-all)"
else
    echo "  ✗ FAIL: ctx_search.py (--clear-all)"
    echo "  Output: $RESULT"
    exit 1
fi

# Test 17: Verify .gitignore was auto-injected
echo "Test 17: Checking .gitignore auto-injection..."
if [ -f .gitignore ] && grep -q ".ctx/" .gitignore; then
    echo "  ✓ PASS: .gitignore auto-injection"
else
    echo "  ✗ FAIL: .gitignore auto-injection"; exit 1
fi

echo ""
echo "=== All Tests Passed ==="
echo ""
echo "Context management skill is ready for use."
exit 0
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