Bach

CLI-first personal agentic development session launcher: turns daily tasks into clarified Claude Code or Codex work sessions.

macOS · Python 3.12+ · Claude Code & Codex · MIT

---

Why Bach?

Prompt engineering is becoming loop management. You don't run one AI coding agent anymore — you run several Claude Code and Codex sessions at once, and the bottleneck is no longer wording a prompt, it's keeping track of every loop: what each one is doing, which is stuck, which is done. Bach is that layer. Think of it as the conductor for an orchestra of agents.

What it gives you, day to day:

• Clarity before code. Bach grills a task into a clear contract before anything launches, and in Mode 1 writes no code until you approve. Better inputs are the cheapest way to get better agent output.
• One board, not twenty tabs. /board shows every task across stages with live session indicators, so you stop losing the five things you started this morning.
• Every session, visible and controllable. bach sessions list discovers all Claude Code and Codex sessions on the machine — even ones Bach didn't start — and lets you adopt, resume, watch, or close any of them.
• Supervision that runs itself. An LLM observer reads each session's transcript, advances its kanban card, and flags the ones that genuinely need you — so the board stays true and points you at the loop that's stuck instead of making you poll all of them.
• Walk away, come back. A background daemon keeps supervising after you close the terminal; cheap scheduled sweeps (a few times a day, daytime only) make it affordable to leave on. SSH back from another machine and the board is already current.
• Yours and inspectable. Tasks are plain YAML + Markdown under <project>/.bach/, versionable with your repo. Both Claude Code and Codex are first-class, and every bit of automation prints a manual fallback.

Who it's for: anyone running multiple agentic coding loops a day who's tired of juggling terminal tabs. If you run one agent occasionally, you don't need Bach. If you've got three sessions going while you context-switch between them, Bach is the difference between an orchestra and noise.

Supervision is pull, not push by design: Bach keeps your board accurate, it doesn't ping you.

---

Requirements

Read this before cloning. Bach has hard runtime dependencies that are not installable via pip.

Requirement	Notes
macOS only	iTerm2 automation uses osascript. Linux / Windows are not supported today.
iTerm2	Must be the active terminal emulator.
Claude Code and/or Codex CLI	At least one must be installed and on $PATH.
Python 3.12+	Required.
uv	Package manager. brew install uv or see uv docs.

---

What It Does

Bach sits between you and an AI coding agent and enforces a discipline around task clarification before any code is written.

1. Register projects — Bach tracks your local projects in ~/.bach/projects.yaml.
2. Create task artifacts — each task becomes a YAML + Markdown file in <project>/.bach/runs/<date>/.
3. Launch grilled agent sessions — Bach opens iTerm2, starts Claude Code or Codex, and pre-loads a grilling skill that forces clarification before implementation.
4. Mode 1 gate — no code is written until you explicitly approve execution after the grilling phase. The task contract is saved to the project's .bach/ folder first.
5. Resume deterministically — launch/resume/restart shell commands are persisted in the artifact before iTerm is touched, so manual recovery always works.

---

Quickstart

# 1. Clone and install
git clone https://github.com/Catafal/bach.git
cd bach
uv sync                          # core CLI only
uv pip install -e ".[repl]"      # add the interactive REPL (recommended)

# 2. Register your first project
bach project add myproject /path/to/your/project

# 3. Initialise the project-local .bach/ folder
bach project init myproject

# 4. Create a task
bach task add

# 5. Open the interactive REPL
bach

Inside the REPL, type /help for a full command list. Tab-complete works at every prompt; drag a folder from Finder into any path prompt.

---

Feature Overview

• Interactive REPL (prompt_toolkit + rich) — cross-project task list, slash commands, stable tN task IDs, tab-complete, drag-and-drop paths.
• Kanban board — /board renders a Pocock-style column-per-status kanban across all registered projects. Oldest tasks surface first in each column.
• Two first-class runtimes — Claude Code and Codex are both supported; runtime is set per-task and can be configured as a global default.
• Deterministic resume — launch, resume, and restart commands are written to the artifact before iTerm automation runs, so a failed osascript never loses your session command.
• 11 workflow stages — research → prototype → grill → prd → ready → in-progress → review → paused → done → skip → archive, wired across the board, status setters, and the Pocock cheatsheet (/workflow).
• Issue DAG per task — parent_task + blocked_by relationships in frontmatter; GitHub Issues import/sync for child issues.
• Session modes — grill (clarify first), research (read/gather), free (open session) selectable at launch time.
• Daily cross-project index — ~/.bach/runs/YYYY-MM-DD.md derived from all registered project artifacts; rebuilt automatically on task add.
• Optional SessionEnd hook — when wired up, Claude Code's SessionEnd event auto-sets the task status to paused and appends an audit log entry.
• Fallback safety — if osascript fails, Bach prints the exact shell command to run manually.
• Session radar & observer — discover live/idle/ended agent sessions, link them to tasks, and let the observer automatically suggest or apply status transitions based on transcript analysis (see below).
• AFK loop control — headless multi-turn task runner with loop-gate verification and judge-driven status management.

---

Session radar & observer

Bach can discover running and ended Claude Code and Codex sessions across your machine, join them with your task artifacts, and let an observer process apply status transitions automatically.

# See all current sessions with task linkage
bach sessions list

# Filter by state
bach sessions list --state running

# Link an orphan session to a task artifact
bach sessions adopt <session-prefix> t47

# Resume a session in iTerm
bach sessions resume <session-prefix>

# Run the foreground observer for a task
bach sessions watch t47

Example output from bach sessions list:

Session ID	Runtime	State	Task	Project	Preview
a3f9c2e1...	claude-code	running	t47	myapp	"refactoring the auth…"
b81d04f7...	codex	idle	t12	backend	"added retry logic"
cc4e9101...	claude-code	ended	—	—	—

Observer authority

The observer watches a session transcript, calls the LLM judge on a schedule, and may apply status transitions with conservative authority:

Allowed move	Trigger
executing → qa	Judge confidence ≥ threshold, task complete
* → hitl_queue	Judge says needs_human=true

The observer never sets done, never moves backward, and never touches pre-execution stages (inbox, prd, kanban_issues). All observer actions are appended to the artifact log.

Set observer_moves: false in ~/.bach/config.yaml to make the observer log-only (suggestions only, no writes).

Hook installation

Wire up Bach hooks for automatic session tracking:

# Claude Code: installs SessionEnd + Stop + PostToolUse hooks
bach hooks install claude-code

# Codex: installs sessionStop hook in ~/.codex/hooks.json
bach hooks install codex

# Check what's installed
bach hooks status

See docs/how-to/wire-up-session-hook.md for full setup instructions.

---

Docs

docs/
  ARCHITECTURE.md          System structure, data flows, module boundaries
  how-to/                  Step-by-step guides (REPL, hooks, config, …)
  explanation/             Concept deep-dives (Mode 1, iTerm hardening, …)
  reference/               Schemas and format specs
  adr/                     Architecture Decision Records (ADR-001 → ADR-011)
  internal/                Full planning history — PRD, discovery, app flow,
                           implementation plan, progress log, lessons learned.
                           This project is built largely via agentic coding
                           sessions; the planning docs are published as part
                           of the story.

• CONTRIBUTING.md
• LICENSE — MIT

---

Honest Caveats

Bach is a personal tool at version 0.x. It is opinionated, macOS-only, and the artifact schema may change between minor versions without a migration path. If it fits your workflow, great — but it was built for one person's setup and published so the implementation story is visible.

Pull requests are welcome for bug fixes and documentation. Large feature additions should open an issue first.