Dabbler AI Orchestration

Starting from a clone? Follow docs/clone-setup.md for the .venv bootstrap, extension dependencies, provider access, and the tracked-versus-machine-local setup boundary.

An AI-led coding-session workflow for VS Code. Structured AI sessions with mandatory cross-provider verification, automatic cost tracking, git- worktree-aware session-set state, and a Work Explorer in the activity bar.

What this repo is for

The framework treats AI coding work as a sequence of sessions — bounded slices that run to completion in one orchestrator conversation, end with a verification + commit, and stop. A session set is an ordered chain of sessions that delivers one feature, refactor, or aspect of the solution. Each set lives at docs/session-sets/<slug>/ with a small predictable shape (spec.md, session-state.json, activity-log.json, change-log.md).

Inside each session, the orchestrator (Claude Code, Codex, GitHub Copilot, or Gemini Code Assist) does mechanics — file edits, shell, git — and dispatches every reasoning task (code review, security review, analysis, architecture, documentation, test generation, end-of-session verification) through ai_router.route(). The router picks the cheapest capable model per task type, escalates on poor responses, and runs cross-provider verification by a different provider to catch provider-specific blind spots.

Every routed call is appended to ai_router/router-metrics.jsonl, so per-set, per-task, and per-model spend is fully auditable. The Work Explorer extension view is the at-a-glance companion: it reads the same files the router writes and renders three groups in the activity bar (In Progress, Not Started, Done), with worktree auto-discovery so parallel sessions surface across sibling workspaces. Full execution mechanics live at docs/ai-led-session-workflow.md; deeper feature descriptions live at docs/repository-reference.md.

Highlights

• Session sets and sessions — Work is organized into bounded sessions inside ordered session sets, each with its own folder of artifacts the extension reads to render the activity-bar inventory. Deep dive.

• Cost-minded orchestration — The router routes each task to the cheapest capable tier, escalates on poor responses, and uses a per-task-type effort overrides. Real metrics from contrasting projects show 73% savings vs Opus-only on a CLI/library project (990 calls) and 32% savings on a full-stack UI app with UAT/E2E gates (370 calls) — see docs/sample-reports/ for the full reports. Deep dive.

• Cross-provider verification — Every session ends with verify_session, which sends the work to an independent model from a different provider (mandatory — the close gate refuses an unverified close; see the one disclosed same-provider exception under Highlights). The verifier returns structured JSON ({"verdict": "VERIFIED" | "ISSUES_FOUND", "issues": [...]}); the orchestrator surfaces disagreements for human adjudication rather than self-resolving. Deep dive.

• Git integration + parallel session sets — Every session ends with git add -A && git commit && git push. Multiple session sets can run in parallel via isolated git worktrees on session-set/<slug> branches, with the last session merging back into main cleanly. Deep dive.

• Robust fallbacks — Tier escalation on empty/truncated/refused responses; two-attempt verifier fallback when a provider's HTTPS layer fails; documented escalation ladder if both verifier attempts fail. The work is preserved in git for human review either way. Deep dive.

• UAT + E2E support (tri-state, opt-in). Specs declare requiresUAT and requiresE2E as true | false | "suggested". true enforces a UAT checklist + matching Playwright coverage as a close-out gate; false skips both surfaces; "suggested" asks you at session start whether you want E2E tests, UAT checklist, both, or neither, records your choice, and gates close-out accordingly. No-UI repos default to the universal core (build, test, verify, commit) with no UAT/E2E surface area. Deep dive.

• Mandatory cross-provider verification. Every session runs the router's Step 6 verification command before it closes, and the close-out gate corroborates the result against a stamped cross-provider metrics row — there is no per-session skip. The verifier is chosen by excluding the orchestrator's own effective provider, so work is never reviewed by the model that did it. If no different-provider verifier is reachable, the outcome is a blocked verification_unavailable, resolvable only by the operator-attested manual path — never a silent same-provider pass.

  One disclosed exception (Set 123 S2, operator ruling 2026-08-11). A DIRECT_API project on a machine whose only usable key is the orchestrator's own provider runs session verification same-provider instead of stopping. It warns on stderr, and every record the verdict lands on carries verification_qualification: same-provider, so an uncorroborated verdict is labelled as one rather than passing for an independent review. The exception covers session verification only — code review and security review still fail closed — and does not apply to a Copilot seat, which keeps the unqualified fail-closed contract.

Quick start

1. Install the extension from the VS Code Marketplace:
   • VS Code → Extensions view (Ctrl+Shift+X) → search Dabbler AI Orchestration → Install.
   • Or from a terminal: code --install-extension DarndestDabbler.dabbler-ai-orchestration.
   • Or directly from the Marketplace listing.
   • Offline / firewall fallback: each tagged release attaches the .vsix as a downloadable asset on the GitHub Releases page; pick the latest, then Extensions → ... → Install from VSIX....
2. Open your workspace. Any folder with — or destined for — a docs/session-sets/ directory. The activity-bar AI Work Explorer icon appears automatically once that path is present.
3. Run Dabbler: Install ai-router from the command palette (Ctrl+Shift+P). The command auto-detects (or offers to create) a workspace .venv/, runs pip install dabbler-ai-router inside it, and materializes ai_router/router-config.yaml for tuning.

Then give the router a provider to call (one-time). Either set provider API keys as environment variables — DABBLER_ANTHROPIC_API_KEY, DABBLER_GEMINI_API_KEY, DABBLER_OPENAI_API_KEY — or use an authenticated GitHub Copilot CLI seat and no keys at all. Which one this project uses is recorded by python -m ai_router.verify_type (see For new projects below); the Prerequisites section has the sign-up links.

Subsequent updates: Dabbler: Update ai-router from the command palette.

CLI fallback — python -m venv .venv && .venv/Scripts/pip install dabbler-ai-router, then from ai_router import route from your orchestrator script.

For new projects: set up in two commands

If you're starting a new project — greenfield, or an existing local project that hasn't yet adopted the workflow — run Dabbler: Set Up New Project from the command palette. It is non-interactive: it scaffolds the .venv with the router package, the AI-agent instruction files, and the docs/session-sets/ home, checking prerequisites before any write so a missing one fails with a friendly explainer and leaves nothing behind.

Then answer the one setup question — what verifies this project — in the terminal, once per machine:

python -m ai_router.verify_type --set DIRECT_API     # or COPILOT_CLI
python -m ai_router.verify_type --set-env            # the second half

DIRECT_API means direct DABBLER_* provider API keys; COPILOT_CLI means a GitHub Copilot CLI seat that routes calls through your Copilot subscription with no provider keys. The answer lands in project-verify-type.txt at the repo root, and the router derives transport.profile from it — so there is no second place for that fact to be recorded differently. The file is gitignored (the command adds the rule itself): what verifies a project is machine/project state, so one checkout can honestly answer COPILOT_CLI on a Copilot seat and DIRECT_API on a machine holding provider keys. Setup is finished when BOTH that file and AI_ORCHESTRATION_VERIFY_TYPE carry the same value — --set-env derives the variable from the file rather than asking again, persisting it at USER scope on Windows and printing the export line for your shell profile on macOS/Linux. python -m ai_router.verify_type with no flags prints what the project currently resolves to, or the guided setup if this machine has not answered yet.

On the Copilot path, Dabbler: Set Up Copilot Seat runs the seat's catalog check and enables the seat profile only when the seat confirms two distinct provider families — validated so far only on a single personal seat (the same seat Set 078's evidence came from); multi-seat and enterprise-seat model availability are not yet validated, and an enterprise-managed seat may expose only one provider family and fail the two-provider check even when the guided flow itself succeeds — it reports that honestly instead of leaving a silently broken router. (Running the Copilot seat also needs a one-time per-machine setup — install the copilot CLI, log in to your tenant, run the auth-preflight — walked through in docs/copilot-seat-setup-checklist.md; an unauthenticated seat is blocked at session start rather than silently faking verification.) Dabbler: Open modules.yaml creates docs/modules.yaml on demand (explicit action only) so the Work Explorer can group session sets by module — with a copyable AI prompt (Dabbler: Copy Module Decomposition Prompt) that fills it in. Drafting docs/planning/project-plan.md and decomposing it into session sets now happen from the per-module row actions in the tree (and the Command Palette), one click from the module they belong to. The four-tier budget mapping is documented in docs/ai-led-session-workflow.md → Cost-budgeted verification modes.

Never used Dabbler before? Start with docs/tutorials/hello-world.md — a 15-minute first run on a local sample project, with no git host, no existing repository, and no git commands for you to type. You watch an AI session change real code and prove it worked.

Ready to put Dabbler into a repository you keep? The hands-on tutorial docs/tutorials/adopt-dabbler.md walks you through the whole flow end to end for one person and one module — scaffold, the module, its plan and session sets, worktrees, CI, and a gated pull request.

Then docs/tutorials/three-module-pipeline.md takes it to the shape the product was designed around: three modules, built independently and composed over an agreed contract. You build all three — solo or alongside teammates — and finish by repointing your service at somebody else's implementation with two configuration values and no code change. Release, hotfix, and rollback operations live in docs/tutorials/release-and-recovery.md.

Setting up without VS Code? See the manual-setup note in docs/quick-start.md. (The former conversational "adoption bootstrap" path was retired in extension 0.32.0 once the form gained its budget step; docs/adoption-bootstrap.md remains as a redirect stub for older clients.)

Prerequisites: tools and accounts

You need VS Code, at least one orchestrator agent installed as a VS Code extension, and a provider for the router to call. That last one has two answers, and you only need one of them:

• Provider API keys (DIRECT_API) — accounts with Anthropic, Google and/or OpenAI. Two of the three is the working minimum; cross-provider verification only needs somewhere different to route to than the model that did the work.
• A GitHub Copilot CLI seat (COPILOT_CLI) — no provider API keys at all, and none expected. A seat measured on 2026-08-05 exposed three provider families, which is why this path exists: it is the one for shops whose staff hold a Copilot seat and cannot get provider keys.

Which answer a machine gives is recorded once by python -m ai_router.verify_type — see For new projects.

VS Code

• Download: code.visualstudio.com
• Getting-started docs: code.visualstudio.com/docs — the Extensions view (Ctrl+Shift+X) is what you'll use to install the Work Explorer in the Quick start above.

Orchestrator agents (install at least one)

Pick whichever AI agent you want to drive sessions; the framework is provider-agnostic and you can switch mid-set.

• Claude Code (Anthropic) — reads CLAUDE.md. Install via claude.com/product/claude-code; docs at docs.claude.com/en/docs/claude-code/overview.
• Codex (OpenAI) — reads AGENTS.md. See openai.com/codex and the open-source CLI repo at github.com/openai/codex.
• GitHub Copilot — reads AGENTS.md. See github.com/features/copilot; Marketplace listing at GitHub.copilot.
• Gemini Code Assist (Google) — reads GEMINI.md. See codeassist.google (free tier available); docs at cloud.google.com/gemini/docs/codeassist/overview.

API keys (the DIRECT_API path — skip this on a Copilot seat)

Cross-provider verification needs at least two provider families live to be meaningful, so two of these three is the working minimum; setting all three gives the router more to choose from and is what this repo itself runs on. On the COPILOT_CLI path you set none of them — the seat carries no provider keys by design, and nothing warns about their absence.

• DABBLER_ANTHROPIC_API_KEY — console.anthropic.com (Settings → API Keys, requires billing).
• DABBLER_GEMINI_API_KEY — aistudio.google.com (Get API key in the left rail; free tier is generous).
• DABBLER_OPENAI_API_KEY — platform.openai.com (create a project, add a payment method, mint a key).

Set each provider-issued key as a Windows User environment variable; macOS / Linux users can export them in their shell profile. Dabbler does not issue separate API keys: use the same keys you get from Anthropic, Google, and OpenAI, just under the DABBLER_ environment variable names so the router does not collide with provider-owned tools that auto-detect generic API-key names. Optionally, pushover.net's PUSHOVER_API_KEY and PUSHOVER_USER_KEY enable end-of-session phone notifications — if unset, the orchestrator skips the notify and prints to console as usual.

More

For technical reference (deep feature descriptions, the UAT/E2E flag matrix, a worked end-of-session output example, and the repository file map), see docs/repository-reference.md.

For runtime mechanics (trigger phrases, the 10-step procedure, the authoritative rule list every orchestrator obeys), see docs/ai-led-session-workflow.md.

For sample manager-report output from real projects at scale, see docs/sample-reports/.

For worked examples of cross-provider AI consultation in practice — what each provider explored, where they agreed and meaningfully differed, and what makes the pattern worth using — see docs/case-studies/.

License

This repo is released under the MIT License. See LICENSE for the full text. Copyright © 2026 darndestdabbler.

A duplicate LICENSE lives at tools/dabbler-ai-orchestration/LICENSE alongside the extension's package.json. The duplication is required: vsce package expects the file beside the manifest and has no flag to point elsewhere. Both files must be kept in sync.