fliiq 0.2.0

The AI agent you actually own

Fliiq

The AI agent you actually own. One command to plan, build, and automate — with persistent memory and self-generating skills.

Quick Start

pip install fliiq
fliiq init                  # Creates ~/.fliiq/ + .env template
# Edit ~/.fliiq/.env with your API key (Anthropic, OpenAI, or Gemini)
fliiq chat                  # Works from any terminal

Project-specific setup (optional)

cd my-project
fliiq init --project        # Creates .fliiq/ with SOUL.md, playbooks/, mcp.json, etc.

Development install

git clone <repo-url> && cd Fliiq
pip install -e ".[dev]"
fliiq init

Features

Agent loop — Claude Code-style architecture where the model plans, executes, and evaluates in a single loop. Three modes: autonomous (full control), supervised (approve each tool call), and plan (plan only, then approve to execute).

16 core skills — File I/O (read_file, write_file, edit_file, list_directory), search (grep, find), system (shell, deps, dev_server), web (web_search, web_fetch), memory (memory_read, memory_write, memory_search), time (get_current_time), and music (spotify).

Persistent memory — Curated MEMORY.md loaded every session. Daily logs, skill-specific memories, and keyword search across all memory files. The agent reads and updates memory naturally.

Self-generating skills — When the agent detects a capability gap, it researches the API, generates a complete skill (SKILL.md + fliiq.yaml + main.py), installs it, and uses it immediately. Skills persist across sessions in .fliiq/skills/.

Daemon and jobs — Background process that runs scheduled tasks. Cron, interval, one-shot, and webhook triggers. Each job gets its own memory file and audit trail. Create jobs via CLI or let the agent create them mid-conversation.

Customizable identity — SOUL.md defines the agent's personality. Playbooks add domain-specific instructions. Both are scaffolded from templates and fully editable per-project.

MCP support — Connect any MCP server (stdio or streamable-http) and its tools are available to the agent alongside built-in skills. One command to add, test, and manage servers.

Full-screen TUI — Textual-based interface with message scrolling, mode indicator, thinking timer, and keyboard shortcuts. Legacy Rich REPL also available.

Usage

# Interactive chat (default)
fliiq chat                          # Full-screen TUI
fliiq chat --legacy                 # Rich REPL
fliiq chat --mode plan              # Start in plan mode

# Single-shot
fliiq run "build a Flask todo app"
fliiq run "what time is it" --mode autonomous
fliiq plan "refactor the auth module"

# Skills
fliiq skill-list                    # Show all skills with source (core/local)
fliiq skill-promote <name>          # Promote local skill to core

# Identity and customization
fliiq soul show                     # Display SOUL.md (default + overrides)
fliiq soul edit                     # Open .fliiq/SOUL.md in $EDITOR
fliiq soul reset                    # Remove overrides, revert to defaults
fliiq playbook list                 # List playbooks with source (custom/bundled)
fliiq playbook show coding          # Display a playbook
fliiq playbook create devops        # Scaffold a new custom playbook

# MCP servers
fliiq mcp add github --command npx --args "@modelcontextprotocol/server-github"
fliiq mcp add my-api --url https://mcp.example.com/mcp
fliiq mcp list                      # Show configured servers
fliiq mcp test                      # Validate connections
fliiq mcp remove github             # Remove a server

# Daemon and jobs
fliiq daemon start                  # Start background daemon
fliiq daemon start --detach         # Detach to background
fliiq daemon status                 # Check if running
fliiq daemon stop                   # Stop daemon

fliiq job list                      # List all jobs
fliiq job create                    # Create a job interactively
fliiq job run <name>                # Manual trigger
fliiq job logs <name>               # View run history
fliiq job delete <name>             # Remove a job

Chat Commands

Inside fliiq chat:

Command	Action
/mode	Cycle mode (plan -> supervised -> autonomous)
/status	Show session info
/clear	Reset conversation history
/help	Show available commands
/exit	Exit chat

Architecture

fliiq/
  cli/          # Typer CLI, Rich display, Textual TUI, REPL
  runtime/
    agent/      # Agent loop, tool registry, prompt assembly, audit
    llm/        # LLM providers (Anthropic, OpenAI, Gemini) + failover
    skills/     # Skill loader, base class, installer
    mcp/        # MCP client, server connections, tool forwarding
    planning/   # Domain detection, playbook loading, reflection
    memory/     # Memory manager, keyword retrieval
    scheduler/  # Job executor, scheduler, run logging
  api/          # FastAPI daemon, webhook receiver
  data/         # Bundled skills, SOUL.md, playbooks, templates

Agent loop (runtime/agent/loop.py): Model calls tools, tools return results, loop continues until the model stops or hits max iterations. Mode enforcement filters available tools and gates execution.

Skill system (runtime/skills/): Each skill is a directory with SKILL.md (metadata), fliiq.yaml (schema), and main.py (async handler). Discovery scans bundled skills first, then project-level overrides, then user-local .fliiq/skills/.

Memory (runtime/memory/): Files in .fliiq/memory/. MEMORY.md (curated, always in prompt), daily logs (YYYY-MM-DD.md), skill memories (skills/*.md). Agent reads/writes via memory skills.

Configuration

API Keys (.env)

At least one required:

ANTHROPIC_API_KEY=your-key
OPENAI_API_KEY=your-key
GEMINI_API_KEY=your-key

Priority: Anthropic > OpenAI > Gemini.

Global Directory (~/.fliiq/)

Created by fliiq init — used from any terminal:

~/.fliiq/
  .env          # API keys (Anthropic, OpenAI, Gemini, Gmail, Twilio, etc.)
  memory/       # Persistent memory files
  audit/        # Audit trails from agent runs
  skills/       # User-generated skills (available everywhere)

Project Directory (.fliiq/) — optional

Created by fliiq init --project — overrides global for this project:

.fliiq/
  SOUL.md       # Agent personality overrides (scaffolded from template)
  playbooks/    # Custom domain playbooks
  mcp.json      # MCP server connections
  memory/       # Project-specific memory
  audit/        # Project audit trails
  jobs/         # Scheduled job definitions (YAML)
  skills/       # Project-specific skills

Resolution: local .fliiq/ > global ~/.fliiq/ > bundled defaults.

Agent Identity (SOUL.md)

SOUL.md defines the agent's personality, communication style, and behavioral rules. A bundled default ships with the package. To customize for your project:

fliiq soul edit             # Opens .fliiq/SOUL.md in $EDITOR (creates from template if missing)
fliiq soul show             # See default + your overrides
fliiq soul reset            # Delete overrides, revert to bundled default

Your .fliiq/SOUL.md is appended to the default as "User Overrides" — you only need to specify what you want to change. The bundled default is never modified.

Custom Playbooks

Playbooks are domain-specific instructions loaded when the domain detector matches keywords in your prompt. A bundled coding playbook activates for coding tasks.

fliiq playbook create devops    # Scaffold .fliiq/playbooks/devops.md from template

Edit the playbook and add trigger keywords on the # Keywords: line:

# Keywords: devops, deploy, kubernetes, terraform, infrastructure, ci/cd

Fliiq matches keywords in your prompt against these. When 2+ keywords match, the playbook loads into the agent's system prompt. fliiq playbook list shows all playbooks with their source (custom/bundled).

MCP Servers

Connect external tools via the Model Context Protocol. Fliiq supports stdio and streamable-http transports.

# Add a stdio server (e.g. from npm)
fliiq mcp add github --command npx --args "@modelcontextprotocol/server-github"

# Add a streamable-http server
fliiq mcp add my-api --url https://mcp.example.com/mcp

# Verify it works
fliiq mcp test github

# List / remove
fliiq mcp list
fliiq mcp remove github

MCP tools are auto-discovered at startup and registered alongside built-in skills. The agent sees them as regular tools (prefixed with mcp_{server}_{tool}). Connection failures are non-fatal — other servers and skills still work.

Config is stored in .fliiq/mcp.json (scaffolded by fliiq init --project). You can also edit it directly:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "transport": "stdio"
    }
  }
}

Troubleshooting

fliiq doctor                # Verify setup: API keys, SOUL.md, playbooks, MCP, skills

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check fliiq/

# Tests
pytest tests/

# Run specific test file
pytest tests/test_agent_loop.py -v

Tech Stack

• Python 3.12+, Typer (CLI), Rich (display), Textual (TUI)
• FastAPI + uvicorn (daemon), croniter (scheduling)
• Anthropic / OpenAI / Gemini SDKs (LLM providers)
• structlog (logging), pytest (testing), ruff (linting)

License

TBD