Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt

Use this file to discover all available pages before exploring further.

The failproofai dashboard is a local web application for monitoring your AI agent sessions and managing policies. See what your agents did while you were away.

​
Starting the dashboard

failproofai
Opens at http://localhost:8020. The dashboard reads directly from the filesystem - your Claude Code project folders and the failproofai config files. Nothing is written to a remote service.

​
Pages

​
Projects

Lists all Claude Code, OpenAI Codex, GitHub Copilot CLI (beta), Cursor Agent (beta), OpenCode (beta), Pi (beta), and Gemini CLI (beta) projects found on your machine. Claude projects are discovered from ~/.claude/projects/ (or the path set by CLAUDE_PROJECTS_PATH); Codex projects are discovered by scanning every transcript under ~/.codex/sessions/<YYYY>/<MM>/<DD>/*.jsonl and grouping by the cwd recorded in each session’s first record; Copilot CLI projects are discovered by scanning each ~/.copilot/session-state/<sessionId>/workspace.yaml (configurable via COPILOT_HOME) and grouping by its cwd field; Cursor Agent projects are discovered by scanning per-session metadata under ~/.cursor/agent-sessions/<sessionId>/ (configurable via CURSOR_HOME, with conversations/ and sessions/ probed as fallbacks) for a cwd scalar in meta.json / session.json / workspace.yaml; OpenCode projects are discovered by querying its SQLite DB at ~/.local/share/opencode/opencode.db via opencode db --format json (we read the session and project tables and group by project_id); Pi projects are discovered by scanning per-session JSONL transcripts under ~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl (configurable via PI_SESSIONS_DIR) and pulling the cwd from each session’s first record; Gemini CLI projects are discovered by scanning ~/.gemini/tmp/<basename>/chats/session-<timestamp>-<uuid-prefix>.jsonl (configurable via GEMINI_SESSIONS_DIR) and recovering the canonical cwd from the sibling .project_root text marker. A project that has been used by multiple CLIs renders as a single row with all matching badges. Use the CLI dropdown above the table to filter by a specific agent CLI; the URL preserves your selection as ?cli=claude|codex|copilot|cursor|opencode|pi|gemini. Each project shows:
  • Project name (derived from the folder path)
  • A CLI badge — Claude Code (orange), OpenAI Codex (purple), GitHub Copilot (blue), Cursor Agent (emerald), OpenCode (amber), Pi (pink), and/or Gemini CLI (sky)
  • Date of most recent session activity
Click a project to see its sessions.

​
Sessions

Lists all sessions within a project. Each session shows:
  • Session ID
  • Start and end timestamps
  • Number of tool calls
  • Hook activity count (policies that fired)
Use the date range filter and session ID search to narrow the list. Sessions are paginated. Click a session to open the session viewer.

​
Session viewer

The session viewer answers the key question for autonomous agents: what did the agent do, and did it stay on track? A CLI badge beside the header indicates whether the session is a Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, or Gemini CLI transcript. It shows a timeline of everything that happened in a session:
  • Messages - Claude’s text responses and user prompts
  • Tool calls - Every tool Claude invoked, with its input and output
  • Policy activity - For each tool call, which policies fired and what decision they returned
The stats bar at the top shows session duration, total tool calls, and a summary of hook decisions (allow / deny / instruct counts). Click the Download Logs button to export the session. For Claude Code, Codex, Copilot, Cursor, Pi, and Gemini sessions you get the original on-disk JSONL transcript byte-for-byte; for OpenCode (whose sessions live in SQLite, not on disk) you get a JSON document mirroring the underlying session / messages / parts tables.

​
Policies

A two-tab page for managing policies and reviewing activity.
  • Multi-select which agent CLIs failproofai protects from a single panel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, and Gemini CLI all have a row with install status (Active / Detected / Inactive), the user-scope settings path, and a brand-colored accent. Check or uncheck the CLIs you want and click Apply changes to install/uninstall the diff in one step. CLIs whose binary is detected on PATH are pre-checked.
  • Toggle individual policies on or off with a single click (writes to ~/.failproofai/policies-config.json — shared across every installed CLI)
  • Expand a policy to configure its parameters (for policies that support policyParams)
  • Set a custom policies file path

​
Auto-refresh

The dashboard has an auto-refresh toggle in the top navigation. When enabled, the current page refreshes periodically to show new sessions and policy activity as they appear. Essential for monitoring long-running autonomous agent sessions.

​
Disabling pages

If you only need some parts of the dashboard, set FAILPROOFAI_DISABLE_PAGES to a comma-separated list of page names: 
FAILPROOFAI_DISABLE_PAGES=policies failproofai
Valid values: policies, projects.

​
Configuring the projects path

By default, the dashboard reads from the standard Claude Code projects directory. Override it for custom setups: 
CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai

​
Accessing from a non-localhost host

When running the dashboard in dev mode (npm run dev) and accessing it from a hostname other than localhost - for example, a custom domain, a remote IP, or a tunneled URL - you may see a warning like: 
⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
This is Next.js blocking cross-origin access to its HMR (hot module reload) websocket, which is a dev-only feature. To allow your host, use the --allowed-origins flag: 
npm run dev -- --allowed-origins dashboard.example.com
For multiple hosts or IPs, pass a comma-separated list: 
npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
You can also set the FAILPROOFAI_ALLOWED_DEV_ORIGINS environment variable instead: 
FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
This only applies to dev mode. When running failproofai (production mode), there is no HMR websocket and no cross-origin dev resource issue.