FAQ

General

Is Cogtrix free?

The source is available under the Cogtrix License v1.0. You can clone, run, and self-host without any account or fee. The license is source-available, not open-source — modification and redistribution have restrictions. Read the license file for the full terms.

Does Cogtrix phone home?

No. There is no telemetry, no analytics, no usage tracking. The agent connects to whichever LLM provider you configure (Ollama by default, on localhost). Network calls happen only when a tool you invoke needs them — web_search, http_get, git push, etc.

What’s the minimum hardware?

• For local LLM (Ollama with qwen3:8b): a recent laptop with 16 GB RAM is comfortable. 8 GB works but is tight.
• For cloud LLM only: anything that runs Python 3.13.
• GPU is not required but speeds up local inference dramatically.

Models and providers

Which model should I use?

For local everyday work: qwen3:8b — small, fast, capable enough for most tool use.

For heavy reasoning or coding: gpt-4.1, claude-opus-4-7, or deepseek-reasoner via API keys.

You can configure both and switch with /model or via the auto_route_fast_model config setting.

Can I use a custom OpenAI-compatible endpoint?

Yes. Set base_url in a provider config block. Cogtrix has been tested against vLLM, Groq, Together, OpenRouter, and self-hosted Llama-cpp servers.

Can I run multiple models in one session?

Yes. The /think command can engage a designated smart model for reasoning while keeping local as the default. The /delegate command spawns sub-agents that can each use a different model. See Providers.

Tools

How do I disable a tool I don’t trust?

Two ways:

1. In a session: /tools disable <tool_name>
2. Permanently: in .cogtrix.yml, set tools.disabled: [tool_name_1, tool_name_2].

How do I add my own tool?

See Custom tools. Two patterns: drop a file in src/tools/ (in-tree), or register via a plugin entry point (out-of-tree).

Can I sandbox file access?

Yes. Use --allow-read-path and --allow-write-path (both repeatable) to restrict the filesystem surface. See Tool safety.

Memory

What’s a “memory mode”?

Cogtrix has three memory modes:

• conversation — default, casual chat.
• code — tracks files touched, errors seen, decisions made. Optimised for programming tasks.
• reasoning — tracks goals, plans, decisions. Pairs with /think.

Switch with /mode <name> or set -M <mode> on startup. See Memory modes.

Where is memory stored?

Per session, in JSON files at data/history/<session-id>.json. Vector embeddings for semantic recall live at data/vectordb/. Nothing leaves your disk.

Web UI

Do I need the Web UI?

No. The CLI is the canonical interface. The Web UI is a sibling project (Cogtrix-WebUI) for users who prefer a browser. Both talk to the same backend.

Why is my browser asking for a login?

The Web UI uses JWT auth. Register a user via POST /api/v1/auth/register once — the first user gets admin role automatically.

Configuration

Where does Cogtrix look for the config file?

In order:

1. --config-file CLI flag
2. COGTRIX_CONFIG_FILE env var
3. ./.cogtrix.yml, ./.cogtrix.yml, ./.cogtrix.json
4. ~/.cogtrix.yml, ~/.cogtrix.yml, ~/.cogtrix.json
5. $XDG_CONFIG_HOME/cogtrix/cogtrix.yml

If nothing is found, Cogtrix runs with a default config that assumes Ollama on localhost. The setup wizard (--setup) writes a starter config to ~/.cogtrix.yml.

How do I validate my config?

uv run python cogtrix.py --check-config

Exits 0 if valid, 2 if not. The error message points at the offending field.

Trouble

→ See Troubleshooting for common runtime issues.