Running on GitHub Pages?

This page documents Live Mode setup. The hosted site is Analyse Mode only (mock demos). Clone the repo and run locally to activate Live Mode.

Setup Guide

How to Set Up & Test Your Agent

Complete instructions to install the platform locally, connect Cursor, Claude Code, Codex, or any AI agent, and run a real performance crash test with live chaos tests and scoring.

Running on GitHub Pages?

This hosted site is UI-only. Real agent testing requires cloning the repo and running npm run dev:all on your machine. Follow the steps below.

Prerequisites

Before you begin, make sure you have:

Requirement	Version	Check
Node.js	18+ (20+ recommended)	node --version
npm	9+	npm --version
Git	Any recent version	git --version
AI coding agent	Cursor, Claude Code, Codex, etc.	See agent section

Optional: Docker (sandbox isolation), empty project folder for agent code

Installation

Clone the repository

git clone https://github.com/shubhransh-gupta/failfast-ai.git
cd failfast-ai

Install frontend dependencies

npm install

Install backend dependencies

cd backend
npm install
cd ..

Build the CLI bridge

Connects your terminal agent to FailFast AI. Compiles to cli/dist/index.js.

npm run cli:build

(Optional) Build backend for production(optional)

Only needed if running API with npm run start:backend instead of dev mode.

npm run build:backend

First-Time Setup

Create a project folder

Your agent will build code here. It can be empty.

mkdir -p ~/my-crash-test-project

Start the platform (Terminal 1)

Keep this terminal running.

npm run dev:all

[web]  ▲ Next.js — Local: http://localhost:3000
[api]  FAILFAST AI — API SERVER
       HTTP:  http://localhost:4000/api
       WS:    ws://localhost:4000/ws?runId=<id>

Verify the API is online

curl http://localhost:4000/api/health

{"status":"ok","service":"failfast-ai-api"}

Open the Launch Pad

You should see: "FailFast API online — ready for live agent testing"

http://localhost:3000/run/

How to Run a Crash Test

Follow these steps every time you want to test an agent's performance.

Configure the session (Browser)

Open http://localhost:3000/run/
Choose a challenge (e.g. Stopwatch — 7 levels)
Select your agent (Cursor, Claude Code, Codex…)
Enter your project path (e.g. ~/my-crash-test-project)
(Optional) Enter a GitHub repo URL
Click Launch Crash Test

You receive a Session ID, CLI command, and Live Monitor link.

Connect the CLI bridge (Terminal 2)

Connect to the API
Press ENTER when your agent is ready
Crash test starts automatically

cd ~/my-crash-test-project
node /path/to/failfast-ai/cli/dist/index.js connect \
  --session <SESSION_ID> \
  --api http://localhost:4000

Open the Live Monitor (Browser)

Real-time terminal feed
Current level and system status
CLI connection status

http://localhost:3000/monitor/?session=<SESSION_ID>

Run your agent for each level

Copy the requirement from the CLI
Paste it into your agent (Cursor, Codex, Claude Code…)
Let the agent write code in your project folder
Press ENTER in the CLI when the agent finishes
Platform runs chaos tests automatically
Repeat for the next level

┌──────────────────────────────────────────────────┐
│  LEVEL 1: Happy Path                             │
├──────────────────────────────────────────────────┤
│  Build a stopwatch with Start, Stop, Reset...    │
└──────────────────────────────────────────────────┘

View your performance report

Live Monitor shows score and verdict when complete
Click View Detailed Report
Or open http://localhost:3000/results/<SESSION_ID>/

Agent-Specific Instructions

⌘

Cursor

Open project: cursor ~/my-crash-test-project
Open Agent or Composer mode
Paste each level requirement from the CLI
Let Cursor build/modify files
Press ENTER in CLI when done

◆

Claude Code

Run: cd ~/my-crash-test-project && claude
Paste each level requirement
Let Claude Code implement changes
Press ENTER in CLI when done

◇

OpenAI Codex

Run: cd ~/my-crash-test-project && codex
Paste each level requirement
Let Codex write the code
Press ENTER in CLI when done

🐙

GitHub Copilot

Open project in VS Code
Use Copilot Chat with each requirement
Apply suggested changes
Press ENTER in CLI when done

✦

Google Gemini

Run: cd ~/my-crash-test-project && gemini
Paste each level requirement
Press ENTER in CLI when done

⚡

Custom Agent

Use any AI coding agent you prefer
Paste CLI requirements into your agent
Implement in the project folder
Press ENTER in CLI after each level

What Happens During a Test

Each challenge has 7 progressive levels:

Level	Name	What It Tests
L1	Happy Path	Basic correctness
L2	Persistence	State survives restarts
L3	Offline	Works without network
L4	Kill Test	Recovery after termination
L5	Race Condition	Concurrent operations
L6	Corrupted State	Recovery from bad data
L7	Requirement Mutation	Adapts when requirements change

After each level, the Chaos Engine runs adversarial tests (process kill, state corruption, network failure, race conditions, requirement mutation). The Evaluation Engine scores correctness, robustness, architecture, recovery, security, and more.

Reading Your Performance Report

After completion, open /results/<SESSION_ID>/

Score	Meaning
80–100	Strong — survived most chaos levels
60–79	Moderate — some failures under pressure
40–59	Weak — broke under adversarial conditions
0–39	Critical — failed early levels

Demo Mode vs Real Testing

Feature	GitHub Pages	Local
View UI	✅	✅
Simulated crash test	✅	✅
Connect your agent	❌	✅
CLI bridge	❌	✅
Live WebSocket monitor	❌	✅
Chaos tests on your code	❌	✅
Real performance report	❌	✅

Available Commands

Run from the repo root unless noted.

npm installInstall frontend dependencies

cd backend && npm installInstall backend dependencies

npm run cli:buildBuild the CLI bridge

npm run dev:allStart web dashboard + API (recommended)

npm run devStart web dashboard only (port 3000)

npm run dev:backendStart API only (port 4000)

npm run buildProduction build for web

npm run build:backendCompile backend TypeScript

npm run start:backendRun compiled backend

npm run cli:connect -- --session <id> --api http://localhost:4000Connect CLI to session

npm run lintRun ESLint

CLI usage

npx failfast-ai connect --session <SESSION_ID> --api http://localhost:4000

Troubleshooting

"API offline" on Launch Pad

Cause: Backend is not running.

Fix: Run npm run dev:all and refresh http://localhost:3000/run/

"Cannot reach API" in CLI

Cause: CLI cannot connect to port 4000.

Fix: Ensure npm run dev:all is running. Verify with curl http://localhost:4000/api/health

"Session not found" on Live Monitor

Cause: Session expired or API was restarted.

Fix: Create a new session from Launch Pad.

CLI shows no level requirements

Cause: Session not started yet.

Fix: Press ENTER after 'agent is ready' and wait a few seconds.

Agent finished but tests didn't run

Cause: Forgot to press ENTER in the CLI.

Fix: Always press ENTER in CLI after each level to trigger chaos tests.

Port 3000 or 4000 already in use

Cause: Another process is using the port.

Fix: lsof -ti:4000 | xargs kill -9 OR PORT=4001 npm run dev:backend

cli/dist/index.js not found

Cause: CLI not built.

Fix: npm run cli:build

Quick Reference

Terminal 1 (repo root):     npm run dev:all
Browser:                    http://localhost:3000/run/
Terminal 2 (project):       npx failfast-ai connect --session <ID> --api http://localhost:4000
Monitor:                    http://localhost:3000/monitor/?session=<ID>
Report:                     http://localhost:3000/results/<ID>/

Ready to crash test your agent?

Once setup is complete, open the Launch Pad to pick a challenge, select your agent, and start a live session.

Open Launch Pad Watch Demo First