Installation Guide

CtxSift is written in Python and is designed to run locally or integrate with remote model providers. Depending on your model targets (local CPU, local GPU, or remote APIs), CtxSift separates its dependencies into target packaging extras to keep your environment footprint lightweight.

---

Hardware requirements matrix

Review the table below to choose the right installation path based on your machine’s hardware capabilities:

Mode	Target Hardware	Min. RAM	Min. VRAM	Active Components	Packages to Install
Local CPU	Standard Laptop/PC	8 GB	N/A	Local llama.cpp + local Embeddings	ctxsift (Base package)
Local GPU	CUDA-supported GPU	2 GB	8 GB	Transformers (PyTorch) + local Embeddings	ctxsift[gpu] plus a CUDA-aligned PyTorch wheel index
Local GPU (Quant)	VRAM-constrained GPU	2 GB	4-6 GB	Transformers + bitsandbytes + local Embeddings	ctxsift[gpu,quant] plus a CUDA-aligned PyTorch wheel index
Remote (CPU)	Cloud/API-focused	4 GB	N/A	Remote API + local CPU Embeddings	ctxsift[remote]
Remote (GPU)	Hybrid Cloud + GPU	2 GB	4 GB	Remote API + local GPU Embeddings	ctxsift[remote,gpu] plus a CUDA-aligned PyTorch wheel index

---

Prerequisites

Before running the install commands, ensure your environment meets these system requirements:

1. Python >= 3.12: CtxSift uses Python 3.12 features (advanced typing, modern async APIs) and relies on packages built for Python 3.12+.
2. uv Package Manager: We strongly recommend installing CtxSift via uv. It is a blazingly fast alternative to pip and handles isolated binary tool environments automatically.
   • Install uv: Follow the Astral uv Installation Guide.
3. C Compiler Toolchain: Local CPU compression relies on llama-cpp-python, which may compile bindings during installation if pre-built wheels are not available for your platform.
   • Linux: Install GCC or Clang (sudo apt install build-essential).
   • macOS: Install Xcode Command Line Tools (xcode-select --install).
   • Windows: Install the Visual Studio Build Tools (ensure Desktop development with C++ is checked).

Python 3.13 support

On Linux with Python 3.13, llama-cpp-python often falls back to a local build and often fails when CC or CXX points at a compiler that is not actually present.

1. Check the current compiler env vars: echo "cc=${CC} cxx=${CXX}"

2. If they do not resolve cleanly to your host compiler setup, install the toolchain and clear the overrides before install:

   sudo apt update
   sudo apt install build-essential cmake pkg-config python3-dev
   unset CC
   unset CXX

   If you prefer explicit compiler settings instead of clearing them:

   export CC=gcc
   export CXX=g++

---

Choose your installation path

You can use standalone installer scripts given below or let your agent install CtxSift for you by using the installation skill. When installing manually, use uv tool install to install CtxSift in an your environment that is globally accessible on your terminal path.

Automated Installation

Install with standalone scripts or let your agent install it with the install skill. The Linux and Windows scripts now ask for extras and, on GPU installs, the CUDA wheel defaults from the current docs.

Download for Linux Install with Agent

Linux macOS Windows

The standalone install scripts are meant to remove the friction of the manual GPU install flow. They ask for:

• the version to install
• the extras set you want, using the allowed values remote, gpu, quant, or all
• on Linux GPU installs, the CUDA wheel index, defaulting to the current docs recommendation
• on Windows GPU installs, both the CUDA wheel index and the exact torch wheel URL, again defaulting to the current docs recommendation

If you just press Enter, the script uses the same defaults shown later in this page.

See the CUDA alignment section for more details.

---

Manual installation

Local (CPU)

Use this if you do not have a dedicated GPU. CtxSift will run compression locally using GGUF-quantized models via an embedded llama.cpp runtime.

uv tool install ctxsift

Local (GPU)

Use this if you have an NVIDIA GPU supporting CUDA. CtxSift will run local compression using PyTorch and Hugging Face Transformers.

uv tool install "ctxsift[gpu]" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

# Windows
uv tool install "ctxsift[gpu]" --with "torch @ https://download.pytorch.org/whl/cu124/torch-2.6.0%2Bcu124-cp312-cp312-win_amd64.whl" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

ctxsift[gpu] adds the Python-side GPU extras, but it does not install NVIDIA drivers or guarantee that uv will swap the default CPU-oriented PyTorch wheel for a CUDA wheel. You still need a working host GPU stack and a CUDA-aligned PyTorch index. Keep PyPI explicit and use --index-strategy unsafe-best-match, because the PyTorch index also serves some generic packages and uv’s default first-index strategy can otherwise reject compatible versions from PyPI. After install, verify the resolved torch build instead of checking for split nvidia-* Python packages, which are often absent on Windows.

GPU with Quantization

For machines with limited VRAM (e.g., under 8 GB) that still want to run local GPU compression. This includes bitsandbytes to load models in 8-bit or 4-bit NormalFloat modes.

uv tool install "ctxsift[gpu,quant]" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

# Windows
uv tool install "ctxsift[gpu,quant]" --with "torch @ https://download.pytorch.org/whl/cu124/torch-2.6.0%2Bcu124-cp312-cp312-win_amd64.whl" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

Remote Only

Select this to offload all compression tasks to hosted model providers (such as OpenAI, Anthropic, Gemini, or a local vLLM/Ollama network proxy) using LiteLLM. Recall embeddings will still run locally on CPU.

uv tool install "ctxsift[remote]"

Remote + GPU Embeddings

Use this when compression should stay remote, but you still want recall embeddings to run locally on CUDA instead of CPU.

uv tool install "ctxsift[remote,gpu]" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

# Windows
uv tool install "ctxsift[remote,gpu]" --with "torch @ https://download.pytorch.org/whl/cu124/torch-2.6.0%2Bcu124-cp312-cp312-win_amd64.whl" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

Remote mode does not make the hosted provider use your GPU. The GPU here applies only to the local embedding runtime.

All Extras

Installs every optional Python dependency, including remote proxy integrations and quantization libraries. This still does not install NVIDIA drivers or host CUDA toolkits, and it still needs a CUDA-aligned PyTorch wheel index if you want local GPU execution.

uv tool install "ctxsift[all]" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

# Windows
uv tool install "ctxsift[all]" --with "torch @ https://download.pytorch.org/whl/cu124/torch-2.6.0%2Bcu124-cp312-cp312-win_amd64.whl" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

Install the agent skill

After installing the CLI, the recommended way to install the CtxSift agent skill is through guided setup:

ctxsift configure

The configure command can install the skill for a much wider host list now, including copilot, antigravity, claude-code, codex, cursor, windsurf-cascade, cline, roo-code, kilo-code, continue, aider, opencode, gemini-cli, qwen-code, kiro, jetbrains-junie, openhands, zed-agent, sourcegraph-amp, augment-auggie, factory-droid, amazon-q-developer, replit-agent, devin, codegen, google-jules, and other.

Instead of typing host names manually, configure now shows a numbered multi-select list and then asks for global/workspace scope and target-path details only where needed.

For the full prompt flow, supported targets, and scope details, see Configure.

If you prefer manual installation, download the packaged skill file from here

Supported agents

CtxSift ships with first-class install support for a broad set of coding-agent hosts. The supported host decides two things during setup:

• whether installation is available at global, workspace, or both scopes
• whether CtxSift writes a dedicated SKILL.md file or updates a shared instruction surface such as AGENTS.md, GEMINI.md, or a rules/workflows folder

The current support matrix is:

Agent	Global	Workspace	Typical target shape
copilot	Yes	Yes	Dedicated SKILL.md
antigravity	Yes	Yes	Dedicated plugin skill
claude-code	Yes	Yes	Dedicated SKILL.md
codex	Yes	No	Dedicated SKILL.md
cursor	Yes	Yes	Dedicated SKILL.md
windsurf-cascade	Yes	Yes	Workflow or rules file
cline	Yes	Yes	Dedicated SKILL.md
roo-code	Yes	Yes	Dedicated SKILL.md
kilo-code	Yes	Yes	Dedicated SKILL.md
continue	Yes	Yes	Rules file
aider	Yes	Yes	Instruction file referenced from config
opencode	Yes	Yes	Dedicated SKILL.md
gemini-cli	Yes	Yes	Shared GEMINI.md
qwen-code	Yes	Yes	Dedicated SKILL.md
kiro	Yes	Yes	Dedicated SKILL.md
jetbrains-junie	No	Yes	Shared AGENTS.md-style file
openhands	No	Yes	Dedicated SKILL.md
zed-agent	Yes	Yes	Rules file
sourcegraph-amp	Yes	Yes	Dedicated SKILL.md
augment-auggie	Yes	Yes	Dedicated SKILL.md
factory-droid	Yes	Yes	Dedicated SKILL.md
amazon-q-developer	No	Yes	Rules file
replit-agent	No	Yes	Shared replit.md
devin	No	Yes	Shared AGENTS.md
codegen	No	Yes	Shared AGENTS.md
google-jules	No	Yes	Shared AGENTS.md
other	Custom	Custom	Any path you choose

other is the fallback when your agent is not on the built-in list or when you want to install the skill into a different instruction file or folder than the suggested default.

Hosts that use shared instruction files are handled conservatively. CtxSift writes only its own managed block so that the rest of your existing project or user instructions stay intact.

---

If ctxsift is not found after installation, update your shell integration and reopen the terminal:

uv tool update-shell

---

PyTorch and CUDA version alignment

Caution

uv tool install installs CtxSift inside a standalone virtual environment. By default, it retrieves the standard PyTorch wheel index. If your local system requires a specific CUDA version (e.g., CUDA 11.8 or CUDA 12.4), PyTorch may fall back to CPU mode or crash if the wheel and host drivers mismatch.

Python extras cannot install kernel-level NVIDIA drivers for you. To make CUDA-aligned PyTorch wheels available to uv, keep PyPI as the explicit default index, add the matching PyTorch wheel index alongside it, and use --index-strategy unsafe-best-match so uv can still choose compatible generic packages from PyPI.

On Windows, if the normal GPU install still resolves torch ... +cpu, force the CUDA wheel explicitly with --with:

uv tool install "ctxsift[gpu]" --with "torch @ https://download.pytorch.org/whl/cu124/torch-2.6.0%2Bcu124-cp312-cp312-win_amd64.whl" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

On Linux with Python 3.13, if install still fails while building llama-cpp-python, double-check that CC and CXX are either unset or pointed at real host compilers instead of missing names such as x86_64-linux-gnu-gcc.

Examples:

For CUDA 12.4 (Standard default):

uv tool install "ctxsift[gpu]" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu124 --index-strategy unsafe-best-match

For CUDA 11.8 (Older GPU rigs):

uv tool install "ctxsift[gpu]" --default-index https://pypi.org/simple --index https://download.pytorch.org/whl/cu118 --index-strategy unsafe-best-match

Check the final PyTorch build directly:

uv tool run --from "ctxsift[gpu]" python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

---

Post-installation verification

Once the installation is complete, verify that the ctxsift command is available in your PATH and configured correctly.

1. Run the system diagnostics probe

Run ctxsift doctor to check the status of your drivers, databases, and dependencies.

ctxsift doctor

A healthy environment should output positive signals for SQLite, Git, and your selected execution engine:

[PASS] Python version: 3.12.3
[PASS] SQLite version: 3.45.0
[PASS] sqlite-vec extension: Loaded successfully
[PASS] Git executable: Found
[PASS] Local inference device: CUDA detected (RTX 3060 Ti)

2. Test a basic compression pipeline

Confirm the CLI can execute compression pipelines by running a mock string through a dry-run compression call:

echo "Line 1: critical error occurred
Line 2: debug trace details
Line 3: closing process" | ctxsift compress --intent summary "extract error details"

The model should spin up, compress the input, and return the summary.

---

Next steps

Now that CtxSift is installed, proceed to Configuration & Guided Setup to define model backends and initialize your first workspace.