Foolery

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.

Queues	Active	Retakes
History	Hot Keys

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 helps you:

• discover repos
• detect available memory-manager backends
• scan for installed agent CLIs
• configure the app for first use

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.

Agent	CLI Command	Notes
Claude Code	claude	Default dialect. Streams JSONL via --output-format stream-json.
Codex	codex	Uses exec subcommand with --json output. ChatGPT CLI variants also supported.
OpenCode	opencode	Uses run subcommand with --format json output.
Gemini CLI	gemini	Auto-detected and displayed in agent identity.

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), Scene! (multi-beat orchestration), and Breakdown (decompose work into sub-beats). 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.

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 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!

Shortcut	Action
↑ / ↓	Navigate rows
Space	Select row & advance
Shift+] / Shift+[	Next / previous view
Shift+R / ⌘+Shift+R	Next / previous repository
Shift+S	Take! (start agent session)
Shift+C	Close focused beat
Shift+< / Shift+>	Fold / unfold parent
Shift+O	Open notes dialog
Shift+L	Add label to focused beat
Shift+N	Create new beat
Shift+T	Toggle terminal panel
Shift+H	Toggle shortcut help

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