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]`
Local GPU (Quant)	VRAM-constrained GPU	2 GB	4-6 GB	`Transformers` + `bitsandbytes` + local Embeddings	`ctxsift[gpu,quant]`
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]`

Prerequisites

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

Python >= 3.12: CtxSift uses Python 3.12 features (advanced typing, modern async APIs) and relies on packages built for Python 3.12+.
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.
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).

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.

Download for Linux Install with Agent

Linux macOS Windows

Manual installation

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

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]"

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]"

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]"

Installs every dependency, including GPU drivers, quantization libraries, and remote proxy integrations.

uv tool install "ctxsift[all]"

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

Advanced: PyTorch & CUDA version alignment

To force uv to compile or install CtxSift with a specific PyTorch index aligning with your CUDA toolkit version, pass the --index or --with overrides during installation.

Examples:

For CUDA 12.1 (Standard default):

uv tool install "ctxsift[gpu]" --index https://download.pytorch.org/whl/cu121

For CUDA 11.8 (Older GPU rigs):

uv tool install "ctxsift[gpu]" --index https://download.pytorch.org/whl/cu118

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.