Quick Start

npx -y fifony --port 4040

Open http://localhost:4040. 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 breaks every task into three stages, each independently configurable:

  Plan             Execute          Review
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Claude       │─▶│ Codex        │─▶│ Claude       │
│ Opus 4.5     │  │              │  │ Sonnet 4.5   │
│ effort: high │  │ effort: med  │  │ effort: med  │
└──────────────┘  └──────────────┘  └──────────────┘

You set the provider, model, and reasoning effort for each stage. Claude plans, Codex executes, Claude reviews — or any combination you prefer. Configure it in the Settings UI or drop a WORKFLOW.md in your project root.

Issue Lifecycle

Planning → Todo → Queued → Running → In Review → Done
                                ↓            ↓
                           Interrupted    Blocked → (retry with backoff)

1. Create — Describe what you want done. fifony AI-enhances the title and description before planning.
2. Plan — The planner agent generates a structured execution plan: phases, steps, target files, complexity, risks.
3. Approve — You review the plan. Optionally chat with the AI to refine it before approving.
4. Execute — Agents run in an isolated workspace (a copy of your project). Live output streams to the dashboard.
5. Review — The reviewer agent inspects the diff and either approves, requests rework, or blocks.
6. Merge — You review the diff and merge the workspace back to your project root.

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.

Supported build files include: 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.

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 + scheduler
npx -y fifony --port 4040

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

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

# MCP server (stdio)
npx -y fifony mcp

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

# 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:4040/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

Architecture

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

fifony is split into an explicit runtime contract:

• Persistence layer (s3db.js + resource config):
  • Issues, events, sessions, states, and settings are first-class resources under .fifony/s3db/.
  • No external DB is required in normal mode.
• Eventual consistency analytics:
  • EventualConsistencyPlugin is enabled for issue metrics and supports counters, incremental updates, and analytics rollups.
  • Metrics tracked include:
    • usage.tokens and tokenUsage by phase/model,
    • eventsCount,
    • linesAdded, linesRemoved, filesChanged.
  • We query this through getLastNDays/getLastNHours to feed /api/analytics/lines and /api/analytics/tokens.
• Issue lifecycle in StateMachinePlugin (single source of truth):
  • States, guarded transitions, actions, and triggers are centralized in issue-state-machine.ts.
  • Public commands (approve, execute, queue, retry, merge) only emit transitions; the workflow behavior is not duplicated in route handlers.
  • The machine also owns interruption recovery, retry delays, terminal transitions, and rollback edges.
• Queue and execution pool:
  • s3queue is the runtime queue adapter with polling workers.
  • Workers consume planning/execution/review jobs and run concurrently respecting configured concurrency.
• Agent abstraction:
  • fifony wraps local CLIs, not proprietary model logic.
  • Per stage we configure cli, model, and reasoningEffort independently (planning, execute, review).
  • This lets you swap providers by issue without changing core orchestration.
• Per-issue isolation:
  • Each issue has its own execution workspace and Git worktree branch.
  • That avoids file conflicts and enables parallel work on the same repo safely.
• Review and execution observability:
  • Diff stats are computed from git --stat output (linesAdded, linesRemoved, filesChanged).
  • Runtime events are emitted for state transitions, review path decisions, and merge outcomes.
  • CLI output and audit trails are stored to make mid-run interruptions recoverable.
• Capability routing:
  • Routing derives issue labels (capability:<category>, overlay:<name>) from issue text and inferred file paths.
  • This improves queue triage and worker assignment.

Requirements

• Node.js 23 or newer
• At least one of: claude CLI, codex 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.