BDFL - Benevolent Delegator for LLMs

Plan deliberately. Build in parallel. Stay in control.

BDFL is a terminal supervisor for Codex, Claude Code, and Ollama-backed Codex sessions. Work with a planning agent, compare and approve versioned plans or individual sections, then let isolated worker agents implement the approved work while BDFL handles scheduling, checks, review, verification, integration, and recovery.

BDFL's agent and session labels are clickable. Hold Shift while dragging for native terminal text selection, or use C-b [ for reliable scrollback and keyboard copy mode. Review excerpts use v, the arrow keys, and Enter.

BDFL also stands for Benevolent Dictator for Life. In this project, BDFL delegates the work to LLMs. Hence the name!

Index

• Quick start
• Features
• Workflow
• Commands
• Project docs
• Roadmap
• Contributing

⚡ Quick start

You need macOS or Linux (Windows support is planned), Node.js 20+, Git, tmux 3.2+, and at least one supported agent CLI installed and authenticated.

# macOS: brew install tmux
# Debian/Ubuntu: sudo apt install tmux
npm install --global @thisisnsh/bdfl
cd your-git-repository
bdfl

Next, choose a session type. Plan and delegate configures separate planning and worker agents plus worker capacity. Work directly configures one editable agent without BDFL planning or worker tools. BDFL remembers the most recently used repository and keeps separate last-used presets for both session types.

Want to use the main branch build?

Every successful main build is published under the npm staging tag without moving latest.

npm install --global @thisisnsh/bdfl@staging

Use with Codex or Claude Code

Install tmux 3.2 or newer (brew install tmux on macOS or sudo apt install tmux on Debian/Ubuntu), then install the Codex CLI or Claude Code, run it once to sign in, and start BDFL in your Git repository. BDFL uses a private tmux socket and never modifies your normal tmux server.

Choose Codex or Claude Code for the planning agent, worker agent, or both. Each role can use a different model and effort level. You can also mix Codex with Claude Code or Ollama.

Use open models with Ollama

Install and start Ollama, install Codex, and sign in to Ollama Cloud if you want to use a cloud model:

ollama signin
# Pull a local model if you want to use one
ollama pull <model>
bdfl

Choose Ollama and select an installed model, or enter a model ID such as gpt-oss:120b-cloud. BDFL uses Ollama's Codex integration, so a current Codex CLI is required.

Run ollama ps in another terminal to see which models are currently loaded.

✨ Features

Multiple agents & parallel sessions

Use Codex, Claude Code, or Ollama independently for planning, worker, or direct-agent roles.

• Create a planning session with a read-only planning agent and isolated managed workers, or a direct session with one editable agent in the repository.

• Each repository remembers planning and direct settings independently.

• Manage running agents or reopen any saved agent with its exact provider conversation and editable permissions.

• Each live session remains a tmux window internally, but one focused agent fills the terminal by default. The global agent rail contains every open agent, grouped and labeled by session. Click a tab or press C-b then Left/Right (or h/l) to cycle through all agents. C-b o toggles a tiled overview of the current session; prefixed arrows move spatially there, and Enter returns to the selected full-screen agent. C-b [ enters copy mode. Hold Shift while dragging to select native terminal text.

• The two compact status rows keep workflow controls and global agent tabs visible. The controls and C-b n/p/s/r open New, Plans, Sessions, or Reviews; uppercase aliases also work. Esc returns to the agents, C-b x pauses the active agent and chooses a fallback, C-b q opens shutdown confirmation, and C-b ? shows the complete controls. Unprefixed keys always go directly to the active provider.

• Workflow surfaces use near-full-screen native overlays. Use arrows or j/k, Enter, Esc, Page Up/Down, the mouse wheel, and convenient row clicking throughout. Sessions exposes the grouped agent tree, live task context, resume, rename, and scoped cleanup. Plans provides version and section navigation, reading, diffs, approvals, naming, cleanup, and guarded execution. Reviews provides complete diff scrolling and excerpt selection plus accept, feedback, remedy, override, and integration flows.

• In Sessions, d deletes one managed agent; deleting the primary or pressing D cascades through that session. In Plans, d deletes one plan and D deletes plans belonging to the selected session. There are no global delete-all shortcuts. Deletions require Enter confirmation, and active executions block affected deletions.

  Plan cleanup removes only BDFL plan lineage and versions. It does not cascade to executions, sessions, Git history, worktrees, or provider-retained transcripts.

Deliberate & versioned planning

Plans use immutable versions with individually managed sections.

• Browse durable plan versions, compare adjacent versions, and inspect exact changes.
• Approve individual sections while preserving approvals for unchanged sections.
• Execute any fully approved plan version.

DAG-based isolated execution

Each implementation worker receives an isolated worktree plus the complete frozen plan and an explicit assignment. One durable execution agent owns combined verification and reconciliation; accepted verification fixes return to the affected original workers in fresh isolated worktrees.

• Navigate to any worker or execution-agent pane to follow its progress or respond when it needs attention.
• Independent chunks can run in parallel within the configured worker limit.
• Prerequisites and named locks keep dependent or conflicting work in the correct order.

Review before integration

Inspect each worker’s summary, diff, changed paths, checks, and commit metadata.

• Accept the result or send feedback to the same worker for revision.
• Review the consolidated result after global checks and an explicit verification phase.
• If verification fails, accept its recorded remedy or add repair guidance through the confirmation modal. Affected original workers resume in repair worktrees from the verified combined head. Every repair diff returns to Review for explicit re-acceptance before BDFL combines it, reruns global checks, and continues the same verifier conversation.
• Integration requests enter a durable per-repository queue, so only one verified result at a time can reconcile with and advance the target branch.
• If other work has committed meanwhile, BDFL reconciles the verified result in a disposable worktree. The execution agent retains its verification and repair context while resolving conflicts or validation failures. Bounded global checks run in the background so the supervisor stays responsive, and a passing combined tree receives another verification phase in that same conversation before BDFL adds one commit on top. Interrupted checks and legacy reconciliation failures resume from durable state. Uncommitted target changes and rewritten history still stop integration without touching the target.

After worker review, BDFL runs global checks and a fresh verification pass before presenting the consolidated result for integration.

Constrained roles with skills and MCP

BDFL gives managed planning and execution roles session-scoped bdfl MCP tools, while planning agents also receive the bdfl-plan skill. Direct agents are deliberately outside this bridge.

• A session-scoped MCP bridge exposes only the tools permitted for each role.
• Planning and verification agents are instructed not to edit; Claude defaults to manual, while Codex and Ollama default to a read-only sandbox.
• Workers can edit only their isolated worktrees.
• Direct agents run with workspace-write access in the selected repository and receive no BDFL capability descriptor, MCP configuration, Claude plugin, planning skill, role prompt, managed worktree, or execution lifecycle.

Local state and safety

BDFL does not publish its local runtime state, metrics, analytics, or logs. Provider traffic still follows the agent and model you choose; use Ollama with a local model for a fully local setup.

• Each repository owns its .bdfl/ runtime state, which stores session metadata, plans, snapshots, diffs, and worktrees. Never commit it.
• A parent launch aggregates repository-owned state; it does not move plans or worktrees into the parent directory.
• Coordinator and repository locks prevent two supervisors from mutating the same durable state.
• Custom profile commands cannot use arbitrary executables, shell operators, environment prefixes, headless flags, or BDFL-owned lifecycle flags. Safe provider permission options may override BDFL's role defaults; dangerous access requires bdfl --dangerous.

See Model providers, Permissions, and Recovery for the complete contracts.

Workflow

Talk → Plan → Review → Approve → Build → Review → Verify → Integrate

1. Talk with a planning agent that can inspect the repository but cannot edit it.
2. Plan shared decisions, owned paths, dependencies, locks, local checks, and global validation.
3. Review plan versions, compare diffs, and request revisions where needed.
4. Approve exact sections you want to lock. Execution remains blocked until every section in the chosen version is approved.
5. Build eligible chunks in isolated branches and worktrees, in parallel where the approved dependency graph allows it.
6. Review each worker's actual diff and checks. Accept it or send feedback to that worker.
7. Verify the consolidated result with global checks and a fresh non-implementing agent.
8. Integrate only after final review and only while the frozen target remains unchanged and clean.

Commands

bdfl                 # open the foreground supervisor
bdfl --dangerous     # open with provider approvals and sandboxes bypassed
bdfl status          # count saved sessions and active agents
bdfl --version       # print the installed version
bdfl help            # show usage and terminal controls

--dangerous applies to every Claude, Codex, and Ollama-backed Codex agent launched or restored during that supervisor run. It passes the provider's native bypass flag, is not persisted, and should be used only in an externally isolated environment. Dangerous provider flags and full-access permission values are rejected from per-agent options.

Project docs

• Installation
• Architecture
• Model providers
• Permissions
• Recovery
• Release guide
• Security policy

Roadmap

Planned providers, platform support, measurement work, and UX improvements live in TODO.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, testing, documentation, and pull request guidance.

Support · Code of Conduct · MIT License