Install Cogtrix

Cogtrix runs on Python 3.13.x and is managed with uv. The whole install takes ~60 seconds.

Requirements

• Python 3.13.x — Cogtrix requires the 3.13 line specifically.
• uv — the project’s package manager. If you don’t have it: curl -LsSf https://astral.sh/uv/install.sh | sh.
• A local LLM provider — usually Ollama, but optional if you supply a cloud key.

Standard install

git clone https://github.com/NorthlandPositronics/Cogtrix.git
cd Cogtrix
uv sync

uv sync reads pyproject.toml, creates a .venv/ inside the repo, and installs all dependencies pinned in uv.lock. The first run takes ~30–60 seconds; subsequent syncs are near-instant.

Local model (recommended for first run)

Pull a local model via Ollama so you can run Cogtrix without any API keys:

ollama pull qwen3:8b

Any GGUF model works. qwen3:8b is the default — small enough to run on a laptop, capable enough to use most of Cogtrix’s 67 tools.

Cloud provider (optional)

If you’d rather use a cloud LLM, set the matching env var. Cogtrix recognises:

You can mix and match — set multiple keys, and Cogtrix will let you switch with /model.

Verifying the install

uv run python cogtrix.py --check-config

Should print the resolved configuration and exit with code 0.

Next steps

→ Quickstart — three commands to your first session.