Quick Start

npx -y fifony

Open http://localhost:4000. The first run launches the onboarding wizard — it detects your CLIs, scans your project, and configures everything in six steps. State lives in .fifony/. No accounts, no cloud, no external database.

How It Works

fifony auto-detects your installed CLI tools (Claude, Codex, Gemini) and routes each pipeline stage to the best available provider. Configure per-stage provider, model, and reasoning effort in the Settings UI or drop a WORKFLOW.md in your project root.

Issue Lifecycle

stateDiagram-v2
    [*] --> Planning
    Planning --> Planned: PLANNED
    Planned --> Queued: QUEUE
    Queued --> Running: RUN
    Running --> Reviewing: REVIEW
    Reviewing --> Reviewed: REVIEWED
    Reviewed --> Done: DONE
    Done --> Merged: MERGE

    Running --> Blocked: BLOCK
    Reviewing --> Blocked: BLOCK
    Blocked --> Queued: UNBLOCK
    Blocked --> Planning: REPLAN

    Reviewed --> Queued: REQUEUE (rework)
    Reviewed --> Planning: REPLAN

    Done --> Planning: REOPEN
    Merged --> Planning: REOPEN

    Planning --> Cancelled: CANCEL
    Planned --> Cancelled: CANCEL
    Reviewed --> Cancelled: CANCEL
    Blocked --> Cancelled: CANCEL
    Cancelled --> Planning: REOPEN

    Merged --> [*]
    Cancelled --> [*]

Agents run as detached child processes, tracked by PID. If the server restarts mid-run, fifony recovers on the next boot.

Onboarding Wizard

The first run walks you through six steps:

Settings are saved progressively and can be re-run from Settings at any time.

Dashboard

The Issue Detail Drawer shows the full plan (phases and steps), all execution sessions, the workspace diff, and a per-phase token breakdown — Plan / Execute / Review — with input and output counts per model.

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 15 specialist agents:

And 5 skills: commit, review-pr, debug, testing, impeccable (frontend design system).

Agents install to .claude/agents/ and .codex/agents/ during onboarding. Skills load from SKILL.md files in .claude/skills/, .codex/skills/, or your home directory. fifony infers the right agent from the issue description and target file paths — capability routing is automatic.

CLI Reference

# Dashboard + API (default port 4000)
npx -y fifony

# Custom port
npx -y fifony --port 8080

# With Vite HMR for frontend development
npx -y fifony --dev

# MCP server (stdio)
npx -y fifony mcp

# Different workspace
npx -y fifony --workspace /path/to/repo

# Run one scheduler cycle and exit
npx -y fifony --once

# Fine-grained control
npx -y fifony --concurrency 2 --attempts 3 --poll 500

# Onboarding reference repositories
fifony onboarding list
fifony onboarding sync
fifony onboarding sync --repository ring
fifony onboarding import ring --kind skills
fifony onboarding import agency-agents --kind agents --overwrite

MCP Server

Use fifony as tools inside your editor:

npx -y fifony mcp --workspace /path/to/repo

Add to claude_desktop_config.json or VS Code settings:

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

Resources: state summary, all issues, workflow config, runtime guide, per-issue detail

Tools: fifony.status, fifony.list_issues, fifony.create_issue, fifony.update_issue_state, fifony.integration_config

Prompts: fifony-integrate-client, fifony-plan-issue, fifony-review-workflow

REST API

Interactive docs at http://localhost:4000/docs.

Configuration

fifony reads a WORKFLOW.md in your project root if present. Front matter configures the pipeline; the Markdown body defines the execution contract. Settings from the UI write to .fifony/s3db/.

Environment variables (all optional when using the UI or WORKFLOW.md):

FIFONY_WORKSPACE_ROOT=/path/to/repo
FIFONY_PERSISTENCE=/path/to/state     # defaults to $FIFONY_WORKSPACE_ROOT
FIFONY_AGENT_PROVIDER=codex           # codex | claude
FIFONY_WORKER_CONCURRENCY=2
FIFONY_MAX_ATTEMPTS=3
FIFONY_AGENT_MAX_TURNS=4
FIFONY_LOG_FILE=0                     # set to 1 to also write .fifony/fifony-local.log

Architecture

.fifony/
  s3db/           ← durable database (issues, events, sessions, settings)
  source/         ← project snapshot used for workspace seeding
  workspaces/     ← isolated per-issue execution directories (git worktrees)

• State machine (single source of truth): States, guarded transitions, actions, and triggers are centralized in issue-state-machine.ts. All side effects (events, field mutations, EC tracking) happen in FSM entry actions.
• Persistence (s3db.js): Issues, events, sessions, and settings are first-class resources. No external DB required.
• Eventual consistency analytics: EventualConsistencyPlugin tracks linesAdded, linesRemoved, filesChanged, token usage, and event counts with daily cohort rollups.
• Queue workers: S3QueuePlugin dispatches planning/execution/review jobs to concurrent workers.
• Agent abstraction: Wraps local CLIs (Claude, Codex, Gemini), not proprietary model logic. Per-stage provider/model/effort configuration.
• Per-issue isolation: Each issue gets its own git worktree branch. No file conflicts, safe parallel work.
• Capability routing: Issue labels derived from text and file paths drive automatic provider/agent selection.

Requirements

• Node.js 23 or newer
• At least one of: claude CLI, codex CLI, gemini CLI

Credits

fifony is built on the shoulders of:

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

License

Apache License 2.0 — see LICENSE for details.

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