Filo

Filo is a high-performance AI coding assistant written in modern C++.

It runs in multiple runtime modes:

• interactive terminal app (TUI)
• non-interactive prompter mode for scripts/CI
• MCP server over stdio
• HTTP daemon exposing MCP and/or OpenAI/Anthropic-compatible API endpoints

Why Filo

Filo focuses on speed, control, and local-first workflows without giving up multi-provider flexibility.

What Is Different In Filo

1) Local-first architecture

• Local providers are first-class: Ollama over localhost and embedded llama.cpp for in-process GGUF inference( FILO_ENABLE_LLAMACPP=ON).
• Router guardrails can exempt providers flagged as local (enforce_on_local: false), keeping embedded local backends available when remote limits are hit.
• The daemon listens on 127.0.0.1 by default.

2) Embedded smart routing

• In-process router engine with policy rules and strategies: smart, fallback, latency, load_balance.
• Automatic fallback chains with per-candidate retries.
• Guardrails for spend and quota reserves (max_session_cost_usd, token/request/window reserve ratios).
• Auto-classifier that scores prompt complexity and routes to fast/balanced/powerful tiers.

3) Embedded Python runtime

• Built-in python tool executes code inside an embedded interpreter.
• Interpreter state persists across calls (variables/imports/functions carry over).
• Optional venv isolation via FILO_PYTHON_VENV.

Feature Highlights

• C++26 core with streaming-first provider protocols
• TUI built with FTXUI
• Context mentions (@file, quoted paths, and escaped paths like @My\ Folder/file.txt)
• Agent Skills support with .filo/skills and on-demand activation
• Ctrl+V clipboard paste support (text paste and clipboard-image insertion as @"<path>")
• Session persistence and resume
• Global + workspace config layering
• MCP dispatcher shared across stdio and HTTP transports
• OAuth and API-key credentials

Prerequisites

• CMake >= 3.28
• C++26 compiler (GCC 15+ or Clang 17+ recommended)
• OpenSSL
• Python 3 (required when FILO_ENABLE_PYTHON=ON, which is the default)

Build And Run

Linux

cmake --preset linux-debug
cmake --build --preset linux-debug
ctest --preset linux-debug --output-on-failure
cmake --build --preset linux-debug --target run_integration_tests
./build/Linux/linux-debug/filo

macOS

cmake --preset xcode-debug
cmake --build --preset xcode-debug
ctest --preset xcode-debug --output-on-failure
cmake --build --preset xcode-debug --target run_integration_tests
./build/Darwin/xcode-debug/Debug/filo

Install

Install the configured build using CMake's standard prefix handling:

cmake --install build/Linux/linux-debug --prefix "$HOME/.local"

For the Xcode preset, select the configuration explicitly:

cmake --install build/Darwin/xcode-debug --config Debug --prefix "$HOME/.local"

The executable is installed to <prefix>/bin/filo. Verify it with filo --version.

Enable Embedded llama.cpp

Linux:

cmake --preset linux-debug -DFILO_ENABLE_LLAMACPP=ON
cmake --build --preset linux-debug

Minimal local provider example:

{
  "default_provider": "local",
  "providers": {
    "local": {
      "api_type": "llamacpp",
      "model": "qwen2.5-coder-7b",
      "model_path": "/absolute/path/to/model.gguf",
      "context_size": 8192,
      "gpu_layers": 35
    }
  }
}

Runtime Modes

Mode	Command
Interactive TUI	filo
Prompter (single-shot)	filo --prompt "Summarize this diff"
MCP over stdio	filo --mcp --headless or filo --mcp stdio --headless
MCP over TCP (HTTP /mcp endpoint)	filo --mcp tcp --headless --port 8080
API gateway only	filo --api --headless --port 8080
MCP + API gateway	filo --mcp tcp --headless --api --port 8080

Daemon transport notes:

• --mcp without a value defaults to stdio.
• --mcp tcp starts the HTTP daemon and exposes MCP on /mcp.
• --daemon is still accepted as a deprecated alias for --mcp tcp.
• Set FILO_MCP_BEARER_TOKEN to require Authorization: Bearer <token> on /mcp.
• For LAN worker deployments, use --host 0.0.0.0 only with a bearer token and network access controls.
• The API gateway is off by default to keep daemon startup minimal and local-first.
• --api starts the same HTTP daemon and exposes OpenAI/Anthropic-compatible proxy endpoints:
  • GET /v1/models
  • POST /v1/chat/completions (OpenAI-style)
  • POST /v1/messages (Anthropic-style)
• Combine --api with --mcp tcp if you want both /mcp and /v1/* on one port.
• Model routing in API gateway endpoints:
  • policy/<policy_name> routes via filo smart router policy.
  • <provider>/<model> routes directly to a configured provider/model.
  • <provider> routes to that provider's default configured model.

Useful CLI flags:

• --version print the Filo version and exit
• --mcp [stdio|tcp] run as MCP server (default transport: stdio)
• --daemon deprecated alias for --mcp tcp
• --api enable optional OpenAI/Anthropic-compatible proxy mode
• filo --auth <provider> [login|logout] authenticate or sign out and exit; the action defaults to login, so filo --auth openai starts ChatGPT OAuth. Tokens are revoked server-side on logout when the provider supports it (Google, OpenAI, Grok)
• --list-sessions list resumable sessions
• --model <MODEL|PROVIDER|PROVIDER/MODEL> select a model for this process only without changing saved defaults
• -r, --resume [id|index|name] resume a saved session (names are set with /rename)
• --prompter force non-interactive mode
• --prompt, -p prompt text
• --output-format, -o one of text, json, stream-json
• --input-format one of text, stream-json
• --include-partial-messages include deltas in stream-json
• -c, --continue continue the latest project-scoped session (TUI + prompter)
• --work-dir, -w add a workspace directory; the first one is primary and later ones are additional allowed directories
• --sandbox [read-only|workspace-write|off] controls landrun (default: off); bare --sandbox enables workspace-write. read-only blocks workspace mutations from both native file tools and child processes while preserving a writable private temp root. Normal permission prompts remain active, while shell commands retain ordinary filesystem and internet access when the sandbox is off. Opt-in secure modes use native Landlock + seccomp on Linux and the native Seatbelt SPI on macOS—never sandbox-exec—and deny child network access.

Prompter examples:

# Direct prompt
filo --prompt "Review this patch for regressions"

# Stdin only
git diff | filo

# Prompt + stdin context
cat README.md | filo --prompt "Summarize the key setup steps"

# JSON output for automation
filo -p "Generate release notes from these commits" -o json

# Stream JSON events
filo -p "Explain the architecture" -o stream-json --include-partial-messages

# Continue latest project-scoped session
filo --continue -p "Now apply the follow-up refactor"

# Multi-project workspace: ../Lampo is primary, ../filo is additional
filo -w ../Lampo -w ../filo

Provider Setup

Filo supports both API-key and OAuth-based providers.

Typical API-key setup:

export XAI_API_KEY="..."
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."
export MISTRAL_API_KEY="..."
export KIMI_API_KEY="..."
export ZAI_API_KEY="..."
export DASHSCOPE_API_KEY="..."

Grok supports the same account-based OAuth flow as Grok Build, while API-key authentication remains available:

# Browser-based OAuth with a local PKCE callback
filo --auth grok

# Clear the saved Grok OAuth session
filo --auth grok logout

Inside the interactive TUI, use /login grok and /logout grok. OAuth-backed Grok profiles use the Grok session proxy and expose the account's session-only models; XAI_API_KEY profiles continue to use the public xAI API.

For local Ollama, default endpoint is:

• http://localhost:11434

Configuration

Config files are layered in this order:

1. ~/.config/filo/config.json
2. ~/.config/filo/auth_defaults.json
3. ~/.config/filo/settings.json
4. ./.filo/config.json
5. ./.filo/settings.json
6. ~/.config/filo/profile_defaults.json
7. ~/.config/filo/model_defaults.json

Use config.json for providers/router/subagents. Use settings.json for managed UI/workflow preferences.

Concurrent instances

Filo supports multiple interactive processes with independent active models. The first running interactive process owns the saved model defaults for its lifetime. Model changes in that process are saved for future launches as usual; model changes in later concurrent processes are session-only and are labeled as such in the TUI. When the owner exits, another running process can take ownership on its next model switch.

Use --model when launching intentionally different processes without changing the saved default:

filo --model openai/gpt-5.4
filo --model claude/claude-sonnet-5

Prompt history and memory mutations are serialized across processes. Saved conversation files are written atomically, and Filo will not resume or delete a conversation that is already active in another process.

Optional context compression can be enabled in config.json:

{
  "context_compression": "light"
}

light keeps exact small tool results, but stores oversized read_file and shell outputs in the agent history as compact summaries with size, digest, signal lines, and head/tail excerpts. The default is off.

Use "full" for the native context-cache mode: first or changed read_file calls stay exact, repeated unchanged reads collapse to small path-based cache stubs, instruction files are always preserved, and common shell outputs such as git status, git diff, build, and test logs are retained as signal-focused summaries. Diff summaries preserve structural diff lines verbatim.

Use "ultra" when token pressure matters more than keeping broad excerpts: it applies the same native cache and command-family summaries as full, but with tighter budgets for read_file and shell output. Instruction files are still preserved exactly.

In the interactive TUI, use /compression to pick a mode from a menu, or /compression ultra / /compress ultra to switch directly.

Agent Ignore

Add a .agentignore file at the workspace root to keep sensitive or noisy files out of Filo-controlled context discovery. Patterns use gitignore-style matching. Filo applies .agentignore to direct file reads, file search, grep search, directory listings, path-aware file modification tools, @file context mentions, and mention autocomplete.

Profiles

Profiles let you keep multiple named configuration overlays and switch between them instantly. This is useful for context switching (for example: work, oss, local), without rewriting your main config each time.

What profiles support:

• Define named overlays under profiles in config.json
• Inherit from one or more parent profiles with extends_from
• Override normal config fields (provider/model selection, mode, approval mode, router, MCP servers, subagents, UI defaults)
• Switch in TUI with /profile <name> and apply changes live in the current session
• Persist the active profile in ~/.config/filo/profile_defaults.json for future launches

Example profile config:

{
  "profiles": {
    "work": {
      "description": "Company defaults",
      "default_provider": "openai",
      "default_mode": "BUILD"
    },
    "oss": {
      "extends_from": ["work"],
      "default_provider": "grok",
      "default_approval_mode": "prompt"
    }
  }
}

Quick usage:

1. Define profiles under profiles in ~/.config/filo/config.json or ./.filo/config.json.
2. In TUI, run /profile (or /profile list) to see active and available profiles.
3. Switch profile with /profile <name> (for example /profile work).
4. Remove the persisted profile with /profile clear.

Commands:

/profile
/profile list
/profile work
/profile oss
/profile clear

Precedence note: FILO_PROFILE=<name> forces a profile for that process and overrides the persisted selection until unset.

Agent Skills

Filo supports Agent Skills-style instruction packages. Each skill is a directory with a SKILL.md file containing YAML frontmatter with at least name and description, followed by Markdown instructions.

The official project-local location is ./.filo/skills/<name>/SKILL.md. Filo-native skill roots have precedence over compatibility roots such as .claude/skills and .agents/skills; project-local .filo/skills has the highest precedence. Use .filo/skills for skills that are specific to Filo or this repository.

Instruction skills are disclosed to the model as a compact catalog and loaded on demand through the activate_skill tool. Bundled scripts/, references/, and assets/ files are listed during activation and can be read by calling activate_skill again with resource_path.

To use the public Agent Skills collection in one project:

mkdir -p .filo
git clone https://github.com/addyosmani/agent-skills.git .filo/agent-skills
ln -s agent-skills/skills .filo/skills

To install it globally instead:

mkdir -p ~/.config/filo
git clone https://github.com/addyosmani/agent-skills.git ~/.config/filo/agent-skills
ln -s agent-skills/skills ~/.config/filo/skills

If .filo/skills or ~/.config/filo/skills already exists, copy individual skill directories into it instead of replacing the directory.

After installation, start Filo from the project. The model will see skill names such as using-agent-skills, code-review-and-quality, and frontend-ui-engineering in its system catalog and should call activate_skill before using the matching workflow. When a skill references a bundled resource, for example scripts/idea-refine.sh, the model can load it with activate_skill and the same resource_path.

Skills without entry_point are also available as slash commands in the TUI: /<skill-name> [arguments]. The body may use $ARGUMENTS as a placeholder. Filo-specific Python tool skills continue to use entry_point and the existing get_schema() / execute() Python contract.

Smart router with local-first policy example

{
  "router": {
    "enabled": true,
    "default_policy": "local-first",
    "scoring": {
      "mode": "hybrid",
      "weights": {
        "word_count": 3.0,
        "heading_count": 1.5,
        "max_heading_depth": 1.0,
        "list_item_count": 2.0,
        "link_count": 1.0,
        "code_block_count": 1.5,
        "table_row_count": 1.0,
        "reasoning_term_count": 0.0,
        "math_symbol_count": 0.0,
        "constraint_term_count": 0.0,
        "question_count": 0.0
      }
    },
    "guardrails": {
      "max_session_cost_usd": 5.0,
      "min_requests_remaining_ratio": 0.20,
      "min_tokens_remaining_ratio": 0.20,
      "min_window_remaining_ratio": 0.20,
      "enforce_on_local": false
    },
    "policies": {
      "local-first": {
        "strategy": "fallback",
        "defaults": [
          { "provider": "local", "model": "qwen2.5-coder-7b", "retries": 0 },
          { "provider": "ollama", "model": "llama3", "retries": 0 },
          { "provider": "grok", "model": "grok-code-fast-1", "retries": 1 }
        ],
        "rules": [
          {
            "name": "deep-reasoning",
            "priority": 10,
            "strategy": "fallback",
            "when": {
              "min_prompt_chars": 260,
              "any_keywords": ["debug", "root cause", "architecture", "migration"]
            },
            "candidates": [
              { "provider": "claude", "model": "claude-sonnet-5", "retries": 1 },
              { "provider": "grok-4-5", "model": "grok-4.5", "retries": 1 }
            ]
          }
        ]
      }
    }
  }
}

Architecture Snapshot

• src/core/llm/ provider abstraction, protocols, routing
• src/core/tools/ tool execution (shell/files/patch/search/python)
• src/core/mcp/ MCP dispatcher and client/session handling
• src/tui/ terminal UI components
• src/exec/ stdio MCP server, daemon, and prompter entrypoints
• src/core/auth/ API key and OAuth flows

License

Apache License 2.0. See LICENSE.