Felix

Key dependencies

Install

Build from source (Linux, Windows, or developers)

make build               # CLI binary -> ./felix
make build-app           # macOS menu bar app -> Felix.app  (also bundles felix and ollama)
make build-app-windows   # Windows system tray app -> felix-app.exe

Then run ./felix onboard to walk through provider setup. If you skip every cloud provider, the wizard configures the bundled Ollama with gemma4 so you have a working agent with zero credentials.

Per-provider setup

// Anthropic — get a key at https://console.anthropic.com
"anthropic": { "kind": "anthropic", "api_key": "sk-ant-..." }
// Models: claude-sonnet-4-5, claude-opus-4, claude-haiku-3-5

// OpenAI — get a key at https://platform.openai.com/api-keys
"openai": { "kind": "openai", "api_key": "sk-proj-..." }
// Models: gpt-5, gpt-5-mini, o3-mini

// Google Gemini — get a key at https://aistudio.google.com/apikey
"gemini": { "kind": "gemini", "api_key": "AIza..." }
// Models: gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash

// Qwen (Alibaba)
"qwen": { "kind": "qwen", "api_key": "sk-..." }
// Models: qwen-plus, qwen-max, qwen-turbo

// External Ollama (running outside Felix)
"ollama": { "kind": "openai-compatible", "base_url": "http://localhost:11434/v1" }
// Models: any tag pulled into Ollama (llama3.2, qwen2.5, mistral, llava, ...)

// LM Studio (default port 1234)
"lmstudio": { "kind": "openai-compatible", "base_url": "http://localhost:1234/v1" }

// DeepSeek — get a key at https://platform.deepseek.com
"deepseek": {
  "kind": "openai-compatible",
  "api_key": "sk-...",
  "base_url": "https://api.deepseek.com/v1"
}
// Models: deepseek-chat, deepseek-coder, deepseek-reasoner

// Bundled Ollama (wired up automatically by `felix onboard`)
"local": { "kind": "local", "base_url": "http://127.0.0.1:18790/v1" }

Example configurations

Configuration

~/.felix/felix.json5 (Windows: C:\Users\<you>\.felix\felix.json5). JSON5 means comments and trailing commas are allowed. Hot-reloaded — edits apply immediately, no restart needed.

Minimal config

{
  "providers": {
    "anthropic": { "kind": "anthropic", "api_key": "sk-ant-..." }
  },
  "agents": {
    "list": [
      { "id": "default", "name": "Felix", "model": "anthropic/claude-sonnet-4-5" }
    ]
  }
}

API keys via environment

Environment variables take precedence over config-file values. The convention is {PROVIDER}_API_KEY (or {PROVIDER}_AUTH_TOKEN) and {PROVIDER}_BASE_URL, where {PROVIDER} is the uppercased provider name from your config:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-proj-..."
export GEMINI_API_KEY="AIza..."
export DEEPSEEK_API_KEY="sk-..."

CLI commands

Model references

Agents reference models as provider/model-name where the provider name matches a key in the providers block:

anthropic/claude-sonnet-4-5    → uses the "anthropic" provider
openai/gpt-5                   → uses the "openai" provider
ollama/llama3.2                → uses the "ollama" provider
local/gemma4                   → uses the bundled local Ollama
deepseek/deepseek-chat         → uses the "deepseek" provider

You can override the model for one CLI session: felix chat -m openai/gpt-5.

WebSocket API

JSON-RPC 2.0 over WebSocket at ws://127.0.0.1:18789/ws.

HTTP endpoints: GET /health, /ws, /metrics (when enabled), /chat, /jobs, /settings, /logs (+ SSE), POST /api/mcp/reauth/{id}.

const ws = new WebSocket("ws://127.0.0.1:18789/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    method: "chat.send",
    params: { agentId: "default", text: "What files are in the current directory?" },
    id: 1
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.result.type is one of:
  //   "text_delta"      — streaming text chunk
  //   "tool_call_start" — agent is calling a tool
  //   "tool_result"     — tool execution result
  //   "compaction.start" / "compaction.done" / "compaction.skipped"
  //   "done"            — response complete
  //   "error" / "aborted"
};

If gateway.auth.token is set in felix.json5, include Authorization: Bearer <token> on the WebSocket upgrade.

Fully offline (bundled Ollama, no API keys)

{
  "providers": {
    "local": { "kind": "local", "base_url": "http://127.0.0.1:18790/v1" }
  },
  "agents": {
    "list": [
      { "id": "default", "model": "local/gemma4",
        "tools": { "allow": ["read_file", "write_file", "bash"] } }
    ]
  },
  "memory": { "enabled": true }
}

Git Workflow

- Always create feature branches from main - Use conventional commit messages: feat:, fix:, docs:, refactor: - Run tests before committing - Squash merge into main ```

Where they live: - ~/.felix/skills/ — shared across all agents - <agent-workspace>/skills/ — agent-specific

How they're matched. Felix injects only the index (name + description + tags) into every turn's system prompt. The model decides when it needs a skill body and calls the load_skill tool to fetch it on demand. This keeps the cached prompt prefix small and stable, which keeps prompt caches hitting.

Manage from the UI. Open /settings → Skills. Upload a .md file (256 KB max) and it's available on the next chat turn — no restart. View raw markdown, delete, or check for parse warnings inline. The same operations are exposed via REST at GET/POST/DELETE /settings/api/skills*.

The default install seeds cortex, ffmpeg, imagemagick, pandoc, and pdftotext so the agent arrives knowing how to reason about common command-line tools.