Installation¶

Requirements¶

Python 3.11 or later
pip

PyPI (recommended)¶

pip install rm-contextos

Verify:

contextos --version

From Source¶

git clone https://github.com/Rohithmatham12/ContextOS
cd ContextOS
pip install -e ".[dev]"

.[dev] includes pytest, ruff, and mypy. For production use only:

pip install -e .

Virtual Environment¶

Recommended for all installs:

python -m venv .venv
source .venv/bin/activate        # macOS / Linux
.venv\Scripts\activate           # Windows

pip install rm-contextos

Optional Feature Sets¶

Install optional extras with pip's bracket syntax:

pip install "rm-contextos[ast]"       # tree-sitter symbol extraction (better ranking)
pip install "rm-contextos[tokens]"    # tiktoken for accurate token counting
pip install "rm-contextos[headroom]"  # Headroom compression support
pip install "rm-contextos[all]"       # everything above

Optional Dependencies¶

tiktoken (accurate token counting)¶

Without tiktoken, ContextOS uses a regex approximation (~10–20% error for code). With tiktoken, token counts use the cl100k_base BPE encoding.

pip install tiktoken

No configuration needed — ContextOS detects and uses it automatically.

headroom-ai (local compression)¶

Required only if you use --compress headroom.

pip install headroom-ai

Then start the local proxy before running ContextOS:

headroom serve          # default: http://127.0.0.1:8787

See docs/HEADROOM.md for full setup instructions.

CI / Docker¶

FROM python:3.12-slim
RUN pip install rm-contextos

Or pin a version:

pip install "rm-contextos==0.1.0"

Upgrading¶

pip install --upgrade rm-contextos

Uninstall¶

pip uninstall contextos

ContextOS writes nothing outside .contextos/ directories in your project folders. No config files are created in your home directory.