A keyboard-first control room for multi-agent software work.

Foolery helps you capture work, break it down, dispatch agents, review what they did, and keep the whole thing legible across repositories.

Foolery is a local orchestration app for agent-driven software work. It sits on top of memory-manager backends — primarily Knots, with Beads also supported — and gives you one place to stage work, run agents, and review outcomes across repos.

It is not trying to be just another chat box around a coding model. The point is to make multi-step work visible: what is queued, what is active, what is ready for review, and what happened in the session history.

Read the Substack post on why I built it.

Install

Prerequisites

You need:

• Node.js
• curl
• tar
• at least one supported memory manager CLI:
  • Knots (kno) — primary path
  • Beads (bd)

1. Install Foolery

curl -fsSL https://raw.githubusercontent.com/acartine/foolery/main/scripts/install.sh | bash

2. Make sure the launcher is on your PATH

If ~/.local/bin is not already on your PATH:

export PATH="$HOME/.local/bin:$PATH"

3. Run setup

foolery setup

foolery setup hands the foolery-configure skill to the first agent CLI it finds on your PATH (claude, codex, opencode, gemini, copilot; override with FOOLERY_SETUP_AGENT=<name>). The agent walks you through:

• discovering repos
• detecting available memory-manager backends
• scanning for installed agent CLIs
• writing a validated ~/.config/foolery/settings.toml and registry.json

If no supported agent CLI is installed, foolery setup exits with a clear error listing the expected CLIs and points you at the UI fallback: run foolery start && foolery open, then configure via Settings.

4. Start Foolery

foolery start

That launches the local server, opens the app in your browser, and leaves the backend running in the background.

Supported Agent CLIs

Foolery launches and monitors agent sessions through their CLIs. It auto-detects installed agents and adapts its command invocation, output parsing, and terminal display per dialect.

Foolery scans your $PATH for these CLIs during setup and in Settings > Agents. You can register additional agent commands or override defaults there.

Dispatch Modes

Foolery supports two dispatch modes for assigning agents to work, configurable under Settings > Dispatch.

Simple (One agent per action)

Map one registered agent to each action type: Take! (execute a single beat) and Scene! (multi-beat orchestration). If you want to change your default agent, the Swap Agent tool updates all matching mappings at once.

Advanced (Weighted pools per step)

Assign weighted agent pools to each workflow step: Planning, Plan Review, Implementation, Implementation Review, Shipment, and Ship Review. Foolery picks from each pool according to the weights, which makes it useful for A/B testing models, mixing agent strengths, or spreading work across different tools. The Swap Agent tool still works across the whole dispatch configuration.

Flow & Features

Queues

The default view. All beats queued and ready for action — filter by type, priority, or free-text search. Select rows with spacebar, bulk-update fields, drill into inline summaries, and trigger agent sessions on any beat. Create new beats with Shift+N.

Active

Beats currently in progress. See which agents are working, their model, version, and state at a glance. The Active view adds Agent, Model, and Version columns so you can monitor running work.

Retakes

The review lane for shipped beats. Browse handoff capsules from agent sessions, inspect what changed, and trigger follow-up passes when something needs another look.

History

A focused history feed for agent sessions. Browse recent beat activity, inspect beat metadata, and review app-to-agent and agent-to-app conversation logs in one timeline.

Diagnostics

The Diagnostics view splits into two tabs: Runtime for local perf telemetry such as heap churn, long tasks, render commits, and fetch timings, and Leases for lease analytics and agent throughput history.

Hot Keys

Need to stay in flow? Open the keyboard shortcut overlay (Shift+H) for a quick map of navigation, actions, editing, and panel controls across views.

Why Foolery?

• Keep software work legible. See what is queued, running, ready for review, and already discussed.
• Turn loose tasks into structured execution. Break work into beats, stage dependency-aware waves, and run agents without losing the plot.
• Review outcomes instead of trusting vibes. Finished work lands in a review lane before it counts as done.
• Stay fast without living in terminal tabs. Navigate, select, bulk-update, and launch work from a keyboard-first interface.
• Work across repos from one place. Keep the orchestration layer above any single repository.

How to Contribute

See the Developer Guide for architecture, conventions, testing, and contribution guidelines. For the project's shared vocabulary (Beats, Knots, Waves, Scenes, Takes, etc.) see TAXONOMY.md. For backend authors, see Foolery Agent Memory Contract. For Knots compatibility decisions, see Knots Compatibility ADR. For clones that use Dolt-native Beads sync hooks, run bash scripts/setup-beads-dolt-hooks.sh once and see docs/BEADS_DOLT_HOOKS.md.

Key Shortcuts

Shift+H to view at any time!

Commands

➜ ~ foolery --help
Usage: foolery <command>

Commands:
  start     Start Foolery in the background and open browser
  open      Open Foolery in your browser (skips if already open)
  setup     Configure repos and agents interactively
  prompt    Manage Foolery guidance prompt in AGENTS.md/CLAUDE.md
  update    Download and install the latest Foolery runtime
  stop      Stop the background Foolery process
  restart   Restart Foolery
  status    Show process/log status
  doctor    Run diagnostics (--fix to auto-fix issues)
  uninstall Remove Foolery runtime, logs/state, and launcher
  help      Show this help
➜ ~

Tech Stack

Next.js 16 / React 19 / TypeScript / Tailwind CSS 4 / Zustand / TanStack Query / xterm.js

License

MIT