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.

fifony executes each issue in an isolated git worktree. If you are starting from an empty folder, initialize git and create the first commit before execution. The onboarding Setup step can do this for you automatically.

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 approval fill:#fbbf24,color:#000,stroke:#f59e0b,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 --> PendingApproval: PLANNED
    PendingApproval --> Queued: QUEUE
    PendingApproval --> Planning: REPLAN
    Queued --> Running: RUN
    Running --> Reviewing: REVIEW
    Running --> Queued: REQUEUE
    Running --> Blocked: BLOCK
    Reviewing --> PendingDecision: REVIEWED
    Reviewing --> Queued: REQUEUE
    Reviewing --> Blocked: BLOCK
    PendingDecision --> Approved: APPROVE
    PendingDecision --> Queued: REQUEUE (rework)
    PendingDecision --> Planning: REPLAN
    Approved --> Merged: MERGE
    Approved --> Planning: REOPEN

    Blocked --> Queued: UNBLOCK
    Blocked --> Planning: REPLAN

    Merged --> Planning: REOPEN
    Merged --> Archived: ARCHIVE

    Planning --> Cancelled: CANCEL
    PendingApproval --> Cancelled: CANCEL
    PendingDecision --> Cancelled: CANCEL
    Blocked --> Cancelled: CANCEL
    Cancelled --> Planning: REOPEN
    Cancelled --> Archived: ARCHIVE

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

    class Planning planning
    class PendingApproval,PendingDecision approval
    class Queued queued
    class Running running
    class Reviewing review
    class Approved done
    class Merged merged
    class Blocked blocked
    class Cancelled cancelled
    class Archived cancelled

Retry operations are semantically distinct — each has its own command, FSM path, and prompt context:

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.

The Setup step blocks execution until the workspace is a git repository with at least one commit, because git worktree needs a base commit.

Dashboard

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

Managed Services — Environment Variables

Environment variables for managed services are stored via Vaulter (SQLite at .fifony/secrets.db) and injected at process startup.

• Global variables (Settings → Services → Global variables) — injected into every service.
• Per-service variables (Settings → Services → <service> → Variables) — injected only into that service and override global variables of the same key.

Variables are applied on the next start or restart of the service — a process already running does not receive changes automatically.

The injection order (last wins):

global vars  →  per-service vars  →  PORT (enforced, always wins)

Managed Services Port Contract

Managed services started by fifony must bind to the PORT environment variable.

• If you configure a service port manually, fifony injects that value as PORT.
• If you leave the port empty, fifony assigns a free local port above 12000, persists it, and injects it as PORT on startup.
• Reverse proxy routing by service and mesh topology resolution both depend on each managed service having a resolvable port.

Reverse Proxy — Local HTTPS Setup (Linux)

fifony includes a built-in HTTPS reverse proxy for routing .local domains (e.g. https://admin.tetis.local) to managed services. Two one-time host setup steps are required:

1. Allow binding to port 443 without root

By default, Linux only allows root processes to bind to ports below 1024. Lower the limit permanently:

echo "net.ipv4.ip_unprivileged_port_start=443" | sudo tee /etc/sysctl.d/99-local-dev.conf
sudo sysctl -p /etc/sysctl.d/99-local-dev.conf

Then set the HTTPS Port to 443 in Settings → Services.

2. Trust the local CA certificate

fifony generates a self-signed CA at .fifony/tls/ca.pem on first run. Install it so the browser accepts the certificates:

# System-wide (curl, etc.)
sudo cp .fifony/tls/ca.pem /usr/local/share/ca-certificates/fifony-ca.crt
sudo update-ca-certificates

# Chrome / Chromium on Linux (NSS)
certutil -d sql:$HOME/.pki/nssdb -A -t "CT,," -n "fifony Local CA" -i .fifony/tls/ca.pem

Restart Chrome after running certutil. After both steps, .local domains resolve and display the green padlock with no warnings.

macOS

Port 443 requires a pf redirect (no sysctl equivalent on macOS). Create /etc/pf.anchors/fifony:

rdr pass inet proto tcp from any to any port 443 -> 127.0.0.1 port 4433

Load it (survives reboots when added to /etc/pf.conf):

# One-time load
echo "rdr pass inet proto tcp from any to any port 443 -> 127.0.0.1 port 4433" | sudo pfctl -ef -

# Permanent — add to /etc/pf.conf then:
sudo pfctl -f /etc/pf.conf

Trust the CA via Keychain (Chrome uses the system keychain on macOS — no certutil needed):

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  .fifony/tls/ca.pem

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


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

Keyboard Shortcuts

Every frequent action is one or two keystrokes away. The full map is available via Shift+/ or at /settings/hotkeys.

Shortcuts are context-aware: drawer shortcuts only fire when an issue is open, kanban/issues shortcuts only on their page. Modifier combos (Ctrl/Cmd) work even inside input fields.

Voice Input (Speech-to-Text)

Dictate issue titles and descriptions by voice. Click the microphone button next to any text field in the New Issue drawer — recording starts in continuous mode with a live waveform visualizer and elapsed timer. Speech is inserted at the cursor position, so you can dictate into the middle of existing text.

• Browser-native — uses the Web Speech API via react-speech-recognition, no external service
• Cursor-aware — inserts at caret position, not just appending
• Visual feedback — pulsing mic, frequency waveform bars, recording timer, and a Stop button
• Graceful degradation — mic button only appears in supported browsers (Chrome, Edge, Safari)

PWA

Install as a desktop app. Offline app shell with update detection banner. Web push notifications for state transitions (works even with browser closed — enable in Settings > Notifications). Desktop notifications also available when tab is open. Service worker caches shell and static assets.

Agents, Skills & Reference Repositories

fifony pulls agents and skills from four 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/.

# 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: fifony://state/summary, fifony://issues, fifony://issue/{id}, fifony://issue/{id}/plan, fifony://issue/{id}/diff, fifony://issue/{id}/events, fifony://workflow/config, fifony://analytics, fifony://guide/overview, fifony://guide/runtime, fifony://guide/integration, fifony://integrations, fifony://agents/catalog, fifony://skills/catalog, fifony://events/recent

Tools: fifony.status, fifony.list_issues, fifony.create_issue, fifony.get_issue, fifony.update_issue_state, fifony.cancel_issue, fifony.retry_issue, fifony.plan, fifony.refine, fifony.approve, fifony.merge, fifony.get_diff, fifony.get_live, fifony.get_events, fifony.enhance, fifony.analytics, fifony.get_workflow, fifony.scan_project, fifony.install_agents, fifony.install_skills, fifony.integration_config, fifony.list_integrations, fifony.integration_snippet

Prompts: fifony-integrate-client, fifony-plan-issue, fifony-route-task, fifony-use-integration, fifony-diagnose-blocked, fifony-weekly-summary, fifony-refine-plan, fifony-code-review

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
• git installed, with the target workspace initialized as a repository before issue execution
• At least one of: claude CLI, codex CLI, gemini CLI

Credits

fifony is built on the shoulders of:

• raffel — Unified multi-protocol server runtime.
• cli-args-parser — CLI argument parsing.
• s3db.js — Filesystem persistence layer.
• Agency Agents — Inspiration for the agent catalog.
• Impeccable — Frontend design skill by Paul Bakaus.
• 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.