fliiq 0.1.0

Developer-first AI agent that runs locally

Fliiq

Developer-first AI agent that runs locally. 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 local .fliiq/ for project memory, jobs, skills

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.

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
fliiq soul show                     # Display SOUL.md
fliiq playbook list                 # List available playbooks
fliiq playbook show coding          # Display coding playbook

# 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
    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/
  memory/       # Project-specific memory
  audit/        # Project audit trails
  jobs/         # Scheduled job definitions (YAML)
  skills/       # Project-specific skills
  SOUL.md       # Project identity override (optional)
  playbooks/    # Project playbook overrides (optional)

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

Agent Identity

SOUL.md defines the agent's personality, communication style, and behavioral rules. Bundled default ships with the package. Override by placing a custom SOUL.md at the project root or in .fliiq/SOUL.md.

Playbooks are domain-specific instructions loaded when the domain detector matches the user's prompt. Bundled coding.md playbook activates for coding tasks. Add custom playbooks in .fliiq/playbooks/.

Troubleshooting

fliiq doctor                # Verify setup, check API keys, diagnose issues

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