fliiq 0.3.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).

26 core skills — File I/O (read_file, write_file, edit_file, list_directory), search (grep, find), system (shell, deps, dev_server), web (web_search, fetch_html), memory (memory_read, memory_write, memory_search), email (send_email, receive_emails, mark_email_read, delete_email, archive_email), SMS (send_sms, receive_sms), messaging (send_telegram), calendar (google_calendar), contacts (find_email), 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.

Email, SMS, and Telegram — Send and receive email (Gmail OAuth or app password), SMS (Twilio), and Telegram messages. Two modes: Fliiq's own channels (people message the bot) and managing your accounts (the agent reads your inbox, sends on your behalf).

Google Calendar — Full calendar management via OAuth. List calendars, create/update/delete events, check availability. Multi-account support — authorize multiple Google accounts.

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

# Google accounts
fliiq google auth                   # Authorize a Google account (Calendar + Gmail)
fliiq google accounts               # List authorized accounts

# 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 + Fliiq channel credentials
  user.yaml     # Your identity (name, emails, timezone)
  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"
    }
  }
}

User Profile (~/.fliiq/user.yaml)

Your identity file — loaded into every agent session so the agent knows who you are. When you say "my email" or "my calendar," the agent uses these accounts.

name: John Doe
emails:
  - address: [e-mail]
    label: personal
  - address: [e-mail]
    label: work
timezone: America/New_York

Created by fliiq init. Emails are auto-added when you run fliiq google auth.

Google Account Integration

Authorize your Google accounts so the agent can manage your Gmail and Calendar:

fliiq google auth           # Opens browser for OAuth consent (Calendar + Gmail)
fliiq google accounts       # List authorized accounts

Run fliiq google auth once per Google account. Each gets OAuth tokens stored in ~/.fliiq/google_tokens.json. After auth, you'll be prompted to add the email to your user profile.

Prerequisites:

1. Create a project at Google Cloud Console
2. Enable Google Calendar API and Gmail API
3. Create OAuth 2.0 credentials (Desktop app, redirect URI http://localhost:8080/callback)
4. Add these to your .env:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Then ask the agent things like "check my email," "book a meeting tomorrow at 3pm," or "find my availability this week."

Communication Channels

Fliiq supports two distinct use cases for email, SMS, and messaging:

Use Case 1: Fliiq's own channels (talk TO Fliiq)

Give Fliiq its own email, phone number, and Telegram bot so people can message it directly — like texting an assistant.

# Fliiq's bot email (receives messages on behalf of Fliiq)
FLIIQ_GMAIL_ADDRESS=[e-mail]
FLIIQ_GMAIL_APP_PASSWORD=your-app-password

# Fliiq's phone number (Twilio)
TWILIO_ACCOUNT_SID=your-sid
TWILIO_AUTH_TOKEN=your-token
TWILIO_PHONE_NUMBER=[phone]

# Fliiq's Telegram bot
TELEGRAM_BOT_TOKEN=your-bot-token

These are Fliiq's OWN inboxes. The daemon monitors them for inbound messages and responds automatically.

Use Case 2: Your accounts (Fliiq manages FOR you)

Authorize your personal/work Google accounts so Fliiq can read your email, send on your behalf, and manage your calendar.

fliiq google auth           # Authorize each Google account via OAuth

Emails go in ~/.fliiq/user.yaml, and the agent uses OAuth (not app passwords) to access them. This is what powers "check my email" and "schedule a meeting."

The two use cases are independent. You can set up one, both, or neither. The agent's system prompt distinguishes between "Fliiq's email" (from .env) and "the user's email" (from user.yaml).

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