code-factory

An AI coding agent manager that automates as much of the software-building process as possible. code-factory runs a pool of Claude Code agents that automatically work through your project's tickets — writing code, refactoring, reviewing, and responding to change requests — while you supervise from a terminal UI.

Tickets live in a .code-factory/ directory inside your repository alongside your code. Each ticket gets its own git branch and worktree, so agent work is always isolated and reviewable before merging.

---

Ticket phases

Each ticket moves through three phases of work:

Phase	What the agent does
implement	Writes specs first, then implements the ticket
refactor	Refactors and cleans up the resulting code
review	Reviews the refactored changes and makes change requests

You approve each phase transition. After each phase, if any change requests are open on the ticket, a /cf-respond run is interleaved to apply them before the ticket can move on. When the final review phase is approved with no open change requests, the ticket's branch is rebased onto its parent project's worktree (or a top-level project branch) and the parent is fast-forwarded to the rebased tip, producing linear history with no merge commit. The worktree is then removed.

---

Getting started

Prerequisites

• Go 1.21+
• Claude Code installed and authenticated
• A git repository to work in

Install

$ git clone https://github.com/fimmtiu/code-factory
$ cd code-factory
$ make install

This builds and installs three binaries to ~/bin/ and installs the Claude Code skills to ~/.claude/skills/. To install the binaries to a different directory, specify INSTALL_DIR on the command line:

$ INSTALL_DIR=/usr/local/bin make install

Set up a repository

$ cd your-project
$ cf-tickets init

This creates .code-factory/ with a default settings.json. Edit settings.json to configure your editor and terminal:

{
  "editor": "cursor",
  "terminal": "iterm2",
  "terminal_theme": "tan",
  // ...
}

Currently supported editors are cursor and vscode, and supported terminals are iterm2, terminal (macOS Terminal.app), and cmux. PRs to add more are welcome! You can also set terminal_theme to "dark", "light", or "tan" to match your terminal background. (For more settings, see the code-factory README.)

Using code-factory

It's best to use Opus as the model when you're planning the work, so run /model opus in Claude's terminal UI before you start running any skills.

Step 1: Write a specification. Create a markdown document that describes in detail what you want your new program or feature to do.

Step 2: Revise the specification. Open a Claude agent and run the /cf-clarify skill on your specification to have it identify parts of your specification that are unclear or contradictory.

/cf-clarify @doc/design.md

You can address its comments manually, or just ask it to update the specification with its suggestions. When you're ready, proceed to...

Step 3: Make tickets. In your Claude agent, run the /cf-project skill on the specification to decompose it into projects, subprojects, and tickets.

/cf-project @doc/design.md

Step 4: Start code-factory.

$ code-factory

Workers will immediately start claiming and working on idle tickets.

Step 5: Keep a watchful eye on it. When a worker needs to ask you for permission to run a command, you'll get a macOS notification.

On the Commands view, that ticket will be at the top of the list in the needs-attention state. Hit Enter on the ticket to see what command it's trying to run, then choose whether to approve or deny it.

Whenever a worker completes a particular phase on a ticket, it will show up in the Commands view in the user-review state. Inspect the work:

• Hit Enter to see all the agent logs and change requests for the ticket
• Hit g to inspect the commits on that ticket's worktree
• Hit t to open a terminal in the ticket's worktree
• Hit e to open an editor window in the ticket's worktree

If you're satisfied with the changes, press a to approve the changes and push the ticket to the next phase.

---

Terminal UI

The TUI has five views (switch with F1–F5 or Shift+Tab):

• F1: Projects — Hierarchical tree of all work units, with a status pane and detail view. Press Enter on a ticket to see its change requests and logfiles.
• F2: Commands — Actionable tickets waiting for your input (needs-attention) or review (user-review). Press A to approve, R to respond to an agent question, D to open a debug prompt.
• F3: Workers — Live view of each agent worker: what it's doing, and a log of its work.
• F4: Diffs — Allows you to interactively look through a ticket's commit history and examine the code that's being generated.
• F5: Log — Timestamped history of all worker actions with access to raw agent logfiles.

Here are some screenshots, though the terminal UI is in flux and these will be out of date quickly.

Projects view	Agent logs	Change requests

Commands view	Workers view	Log view

Diffs view (commits)	Diffs view (diff)

---

Binaries

Binary	Purpose
code-factory	Terminal UI agent manager — the main program
cf-tickets	CLI for managing projects, tickets, and change requests
cf-testdata	Generates test data for UI development and testing

See each binary's README in cmd/ for full documentation.

---

Claude Code skills

The skills/ directory contains Claude Code skills that are installed to ~/.claude/skills/ by make install. These are used by agent workers during the refactor and review phases, and by /cf-respond runs interleaved between phases to apply change requests:

Skill	Trigger	Purpose
cf-clarify	/cf-clarify	Identify underspecified parts of a design document
cf-project	/cf-project	Decompose a large project into tickets
cf-refactor	/cf-refactor	Scan and refactor recent changes for code smells
cf-review	/cf-review	Thorough multi-perspective code review
cf-respond	/cf-respond	Apply change requests to a ticket's worktree

Even if you don't end up using this tool, there are a lot of good bits in the skills that I suggest you steal.

---

Development

$ make build    # Build all three binaries
$ make test     # Run the test suite
$ make lint     # Run go vet and gofmt
$ make clean    # Remove built binaries
$ make install  # Build, install to ~/bin/, and install skills

For UI testing without running real agents:

$ cf-testdata --reset       # Delete all existing tickets and generate test data
$ code-factory --mock       # Run with fake workers

---

Repository layout

cmd/
  code-factory/   Terminal UI agent manager
  cf-tickets/     CLI management tool
  cf-testdata/    Test data generator
internal/
  config/         Settings loading and validation
  db/             SQLite database layer
  gitutil/        Git worktree operations
  models/         Domain types (WorkUnit, ChangeRequest, etc.)
  storage/        Path utilities and .code-factory/ initialisation
  ui/             Bubbletea terminal UI
  util/           Shared utilities (editor, clipboard, terminal)
  worker/         Agent worker pool and ACP integration
  workflow/       Ticket approval and phase-transition logic
skills/           Claude Code skills for working with code-factory projects

TO DO

• Support for more editors. (Currently we only support VS Code and Cursor.)

• Fix the hard-coded file path for the terminal notifications' app icon image.

• Automatically attempt to use Claude to do merge conflict resolution before foisting it off on the user to fix.

• Create a tool for examining permissions requests and auto-approving them if they're safe.

• Find a smooth way to handle viewing multiple change requests on the same line.

• Markdown parsing & formatting for CR descriptions, log files.

• Make cf-refactor generate better commit messages.