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.

Mouse tracking keeps BDFL chrome clickable and lets unmodified drags select structured diff excerpts in Review. Use Shift-drag for native terminal text selection everywhere.

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, and at least one supported agent CLI installed and authenticated.

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 the Codex CLI or Claude Code, run it once to sign in, then start BDFL in your Git repository.

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 paused ones from their saved session.

• Agents accept typing and terminal editing keys immediately. Click an open agent in the bottom rail to switch without stealing provider keystrokes.

• The top action rail opens New, Plans, Sessions, Reviews, or Close. Close pauses only the selected agent; selecting that agent in Sessions resumes its exact provider conversation in one action. Press Ctrl+C twice to quit BDFL.

• On a Sessions parent, press r to rename it or d to permanently delete that session and its agents; D separately deletes all sessions. On Plans, r renames the selected plan, d deletes it, and D deletes all plans. Deletions require Enter confirmation at the bottom; Esc cancels. Active plan executions block plan deletion.

  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 the execution agent from the bottom rail 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