JSPM

fifony

AI agents that actually ship code. You just watch.

Point at a repo. Open the dashboard. AI plans, builds, and reviews — you approve and merge.

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
    direction LR

    classDef planning fill:#38bdf8,color:#fff,stroke:#0ea5e9,stroke-width:2px
    classDef queued fill:#a78bfa,color:#fff,stroke:#8b5cf6,stroke-width:2px
    classDef running fill:#818cf8,color:#fff,stroke:#6366f1,stroke-width:2px
    classDef review fill:#f59e0b,color:#fff,stroke:#d97706,stroke-width:2px
    classDef done fill:#34d399,color:#fff,stroke:#10b981,stroke-width:2px
    classDef merged fill:#22c55e,color:#fff,stroke:#16a34a,stroke-width:3px
    classDef blocked fill:#f87171,color:#fff,stroke:#ef4444,stroke-width:2px
    classDef cancelled fill:#9ca3af,color:#fff,stroke:#6b7280,stroke-width:2px

    [*] --> 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: 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 --> [*]

    class Planning,Planned planning
    class Queued queued
    class Running running
    class Reviewing,Reviewed review
    class Done done
    class Merged merged
    class Blocked blocked
    class Cancelled cancelled

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

<sub>Create an issue and hit Enhance — AI writes a full spec


Review the AI-generated plan, refine it, then approve to start execution</sub>

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.

<sub>Agents cockpit — live output, worker slots, token usage


Analytics — token trends, code churn, engineering KPIs, model breakdown</sub>

PWA

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

Agents, Skills & Reference Repositories

fifony pulls agents and skills from three open-source reference repositories during onboarding:

Repositories are cloned to ~/.fifony/repositories/ and synced on demand. During onboarding, fifony scans them and recommends agents/skills matching your project's domain. You pick what to install.

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

# Manage reference repositories from the CLI
fifony onboarding list                                    # list repos and sync status
fifony onboarding sync                                    # sync all
fifony onboarding sync --repository ring                  # sync one
fifony onboarding import ring --kind agents               # import agents
fifony onboarding import impeccable --kind skills          # import skills
fifony onboarding import agency-agents --kind agents --overwrite  # overwrite existing

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

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

All endpoints are auto-documented via the s3db.js ApiPlugin. Open http://localhost:4000/docs for the interactive OpenAPI explorer with request/response schemas, try-it-out forms, and WebSocket details.

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 for diff reference
  workspaces/     ← per-issue git worktrees

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.