Quick Start

npx -y fifony --port 4040

Open http://localhost:4040. First run launches the onboarding wizard — it detects your CLIs, scans your project, and configures everything.

State lives in .fifony/. No accounts, no cloud, no setup.

What Makes Fifony Different

Mixed-Agent Pipeline

The core idea: different AI providers handle different stages of a single task.

  Plan          Execute        Review
┌─────────┐   ┌─────────┐   ┌─────────┐
│ Claude   │──▶│ Codex   │──▶│ Claude  │
│ Opus 4.6 │   │         │   │ Sonnet  │
│ high     │   │ medium  │   │ medium  │
└─────────┘   └─────────┘   └─────────┘

Claude plans. Codex executes. Claude reviews. Each stage gets its own provider, model, and reasoning effort — configurable per-project in Settings → Workflow.

Onboarding Wizard

First run detects your environment and walks you through setup:

1. Pipeline — Choose which CLI runs each stage (planner, executor, reviewer)
2. Project Scan — AI analyzes your codebase to detect language, stack, and domains
3. Domains — Pre-selected by AI, 21 options across Technical/Industry/Role
4. Agents & Skills — Curated catalog of 15 agents and 5 skills, auto-recommended by domain
5. Effort — Per-stage reasoning effort, reactive to which CLI is selected
6. Workers & Theme — Parallel worker count + visual theme

Settings saved progressively. Re-run anytime from Settings.

Language Agnostic

The project scanner works with any codebase — it detects build files for 18+ ecosystems:

package.json · Cargo.toml · pyproject.toml · go.mod · build.gradle · Gemfile · mix.exs · pubspec.yaml · CMakeLists.txt · composer.json · Package.swift · deno.json · pom.xml · Dockerfile · and more

Uses the detected CLI with --reasoning-effort low for fast, accurate analysis.

How It Works

Planning → Todo → Queued → Running → In Review → Done
    ↑                                      ↓
    └──── Blocked ←── Rework ──────────────┘

1. Create an Issue — Click "+", describe what you want done
2. AI Plans It — Structured execution plan with steps, risks, file paths, complexity
3. You Approve — Review the plan, approve → agents pick it up
4. Agents Execute — Isolated workspace, live output streaming, PID tracking
5. Automated Review — Diff inspection, approve/rework/block decision
6. You Ship — Review the diff, merge

Dashboard

Kanban Drag & Drop

Drag issues between columns to change state. Works on desktop (click + drag) and mobile (long-press). Valid drop targets highlight green, invalid ones dim. State machine enforces valid transitions only.

Micro-interactions

Every interaction has visual feedback:

• Cards lift on hover with state-colored left border
• Running cards pulse with a breathing border glow
• Buttons scale on press, hover lift
• Toasts slide in with progress bar, typed as success/error/info
• Drawers slide in/out with backdrop fade
• View transitions fade between routes
• Theme changes cross-fade in 300ms
• Counters bounce when values change
• Skeleton loaders shimmer during initial load
• Empty states animate in with helpful guidance
• Confetti bursts on issue creation

PWA

Install as a desktop app. Works offline. Desktop notifications when issues change state. Service worker with stale-while-revalidate caching.

Agent & Skill Catalog

Fifony ships with a curated catalog of specialist agents:

Skills: commit, review-pr, debug, testing, impeccable (frontend design).

Agents are installed to .claude/agents/ during onboarding. Compatible with both Claude Code and Codex CLI.

MCP Server

Use Fifony as tools inside your editor:

npx -y fifony mcp

{
  "mcpServers": {
    "fifony": {
      "command": "npx",
      "args": ["-y", "fifony", "mcp", "--workspace", "/path/to/repo"]
    }
  }
}

Create issues, check status, review workflows — without leaving the editor.

API

REST + WebSocket API with auto-generated OpenAPI docs:

http://localhost:4040/docs

Run Modes

# Full experience — dashboard + API + scheduler
npx -y fifony --port 4040

# Dev mode — Vite HMR on port+1
npx -y fifony --port 4040 --dev

# Headless — scheduler only, no UI
npx -y fifony

# MCP server — stdio for editor integration
npx -y fifony mcp

# Custom workspace
npx -y fifony --workspace /path/to/repo --port 4040

Architecture

.fifony/                ← all state (gitignore it)
  s3db/                     ← durable database (issues, events, sessions, settings)
  source/                   ← codebase snapshot
  workspaces/               ← isolated per-issue agent workspaces

Persistence: s3db.js — filesystem-backed database. Issues, events, settings, agent sessions — all persisted and recoverable across restarts.

State Machine: Planning → Todo → Queued → Running → Interrupted → In Review → Blocked → Done → Cancelled

Agent Protection: Detached child processes survive server restarts. PID tracking for recovery. Graceful shutdown marks running issues as Interrupted.

Token Tracking: Per-model token usage with daily/weekly rollups and cost estimates.

Credits

Fifony is built on the shoulders of:

• OpenAI Codex CLI — Original foundation (Apache 2.0). See NOTICE and THIRD-PARTY-NOTICES.
• Agency Agents — Inspiration for the agent catalog.
• Impeccable — Frontend design skill system by Paul Bakaus.
• s3db.js — Filesystem-backed persistence layer.
• DaisyUI — Component library for the dashboard.

License

Apache License 2.0 — see LICENSE for details.

This project includes code from OpenAI Codex CLI. See NOTICE for attribution.