# Fliiq

Developer-first AI agent that runs locally. One command to plan, build, and automate — with persistent memory and self-generating skills.

## Quick Start

```bash
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)

```bash
cd my-project
fliiq init --project        # Creates local .fliiq/ for project memory, jobs, skills
```

### Development install

```bash
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

```bash
# 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

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

## Development

```bash
# 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
