BacklogSmith

A local-first, repository-aware task planner and coding-agent dispatcher built with Electrobun.

BacklogSmith is built for the messy middle of vibe coding: the changes you want to make rarely arrive as a clean backlog — they're fragmented, out of order, and easy to forget, especially the small product and UX details you notice along the way. Drop rough requirements into an Inbox attached to a Git repository, and BacklogSmith preserves your original entries, checks a bounded snapshot of the repository, and keeps a live plan of commit-sized work packages.

A small change gets the smallest safe adjustment to that plan; overlapping, cross-cutting, or stale requirements trigger a larger reorganization instead. Each package carries a precise implementation prompt and its own acceptance criteria — editable before you approve anything — and every approved package runs in an isolated Git worktree, is independently reviewed against those same criteria, and is committed and merged only on your confirmation, never pushed on the agent's behalf.

BacklogSmith was created as an OpenAI Build Week project and as a real vibe-coding experiment: the entire project was built end-to-end in ChatGPT with GPT-5.6 Sol through an iterative loop of prompting, reviewing, revising, and committing. Inside the app, planning and review use GPT-5.3 Codex Spark; package execution uses the Codex model and reasoning effort selected by the user at dispatch time.

Demo

• Devpost: https://devpost.com/software/backlog-smith
• Demo video: https://youtu.be/U_et6GXmBsw

Workflow

Capture rough requirements, let BacklogSmith compile them into work packages, approve the package you want to run, dispatch it to Codex in an isolated worktree, review the result against the package acceptance criteria, request changes if needed, then accept and merge when the work is ready.

Capture -> Plan -> Approve -> Dispatch -> Review -> Request changes or Accept -> Merge

What works today

• Project discovery from recent Codex task history, with a native folder chooser fallback.
• A repository-owned Inbox that preserves raw, messy requirements.
• Automatic planning that splits, merges, groups, and orders the Inbox into commit-sized packages.
• Incremental replanning for small additions, with full reconciliation when requirements overlap or the repository context changes.
• Editable implementation prompts and acceptance criteria for every package.
• Isolated Git worktrees and branches for approved package execution.
• Parallel dispatch for independent packages, with dependency blocking for ordered work.
• Independent review, follow-up changes, one verified local commit, and user-confirmed merge.

Current limitations

• BacklogSmith currently supports Codex as the execution provider.
• Real-agent failure scenarios and packaged UI automation still need broader coverage.
• Production distribution still needs platform signing, notarization, updater validation, and multi-platform release checks.
• The macOS ChatGPT-bundled Codex binary is a development fallback only; production should use a supported user-installed CLI or an approved distribution strategy.

Next

• Expand real-agent failure validation and packaged UI automation.
• Add an in-app diff and stronger acceptance-criteria validation before human review.
• Add provider adapters for Claude Code and other coding agents after the Codex lifecycle contract is fully exercised.

How compilation works

BacklogSmith treats the Inbox as source and the plan as its compiled output. Each Inbox change is debounced and coalesced, then compiled against a bounded snapshot of the repository (Git metadata, a tracked-file path inventory, and an allowlist of architecture/configuration files — source contents are never scanned). The compiler runs on GPT-5.3 Codex Spark in an ephemeral, read-only sandbox with no tool use, using ChatGPT-backed authentication only.

Compilation runs in one of two modes, chosen automatically:

• Incremental patch (default). When the repository context fingerprint still matches the base plan and the change is additive and shallow, new entries are compiled as a bounded patch against a compact catalog of the existing packages. Package, requirement, and task identities are reused, so partial completion and dispatch history survive. Patch depth is capped.
• Full reconciliation (fallback). When requirements overlap or cross-cut existing packages, the context has changed, prior entries were edited, or the patch depth is exceeded, BacklogSmith recompiles the complete active Inbox from scratch.

Every compilation emits commit-sized work packages with a dependency graph. Each package carries concrete tasks, a precise implementation prompt, its own acceptance criteria, the likely files, and a proposed commit message — the prompt and acceptance criteria are editable before you approve anything, and the same criteria later drive the independent review.

Output is validated fail-closed before it is stored: every Inbox requirement must be covered, package and task IDs must be unique, dependencies must resolve, and the dependency graph must be acyclic. A plan that fails any check is rejected rather than persisted. Accepted plans are immutable revisions linked to their parent, so replanning never mutates or loses an already-approved package.

Requirements

• macOS 14+, Windows 11+, or Ubuntu 22.04+
• Bun 1.3+
• A working Codex CLI installation, or CODEX_PATH pointing to one
• Git for repository probing

Run locally for development

bun install
bun run start

bun run start launches the development watch workflow.

For a headless protocol check:

bun run validate:headless /absolute/path/to/a/git/repository

For a read-only Codex-history discovery check (no model turn):

bun run validate:discovery /absolute/path/to/a/git/repository

For a real, non-mutating planning check using two temporary in-memory tasks:

bun run validate:planning /absolute/path/to/a/git/repository

For a real dispatch check in a disposable temporary Git repository:

bun run validate:dispatch

Validate

bun run check
bun run build:canary

bun run build:canary builds an unsigned local artifact. Production distribution still requires platform signing, notarization, and updater validation.

Package for macOS and Windows

bun run package

The packaging command validates the project, builds a stable installer for the current host, verifies required artifacts, and writes SHA-256 checksums. Use bun run package:canary for a test channel. Electrobun builds host-native artifacts, so the GitHub Actions Build desktop artifacts workflow runs the same command on macOS ARM64, macOS Intel, and Windows x64 runners.

On Windows x64, use bun run package:windows for stable or bun run package:windows:canary for canary. These commands deliberately produce unsigned trusted-test artifacts, emit a SmartScreen warning, and fail fast on macOS or Linux instead of pretending to cross-compile.

Unsigned artifacts remain test-only. Trusted testers can build from source to avoid downloaded-binary quarantine, but public distribution still requires Developer ID signing/notarization on macOS and trusted Authenticode signing on Windows. See docs/building.md for commands, CI behavior, and the unsigned-build limitations.

Boundaries

• The Bun main process is the only owner of SQLite, Git subprocesses, and Codex App Server.
• The webview receives a small allowlisted typed RPC surface; it cannot execute arbitrary commands.
• Planning context is limited to Git metadata, a bounded tracked-file path inventory, and a small allowlist of architecture/configuration files. Source contents are not scanned.
• Matching repository-context fingerprints reuse the context saved with the latest plan. New Inbox entries are first compiled as bounded patches against a compact plan catalog; ambiguous, cross-cutting, stale, or over-deep changes fall back to a full reconciliation.
• Plans are immutable revisions. Stable requirement, package, and planned-task identities preserve partial completion and dispatch history without mutating an approved package.
• Planning turns are ephemeral and run in a fresh empty temporary directory with a read-only sandbox; the planning instructions prohibit tool use.
• Dispatch turns are persistent, run only inside an app-managed worktree with a workspace-write sandbox, and leave validated changes uncommitted; BacklogSmith creates the single local package commit without pushing or merging.
• Planning and dispatch are enabled only for ChatGPT-backed Codex authentication, so BacklogSmith will not silently fall back to API-billed credentials.
• A persisted dispatch record is separate from its immutable source plan; BacklogSmith records cancellation, shutdown, recovery, worktree, and merge state without rewriting the approved package.
• App Server owns Codex authentication. BacklogSmith does not read or persist OAuth tokens.
• The macOS ChatGPT-bundled Codex binary is a development fallback only. Production should use a supported user-installed CLI or an approved distribution strategy.

See docs/validation.md for current evidence and remaining release gates.

See docs/mcp-workflow.md for the project MCP configuration, runtime prerequisites, and Bun-specific Wallaby fallback.

See docs/roadmap.md for the worktree-aware V1 ownership model, milestones, acceptance criteria, and revised completion assessment.