Getting Started

Install Dark Factory, configure your first project, and let autonomous agents handle your GitHub issues.

Installation

Prerequisites

• Claude Code — installed and available on your PATH (Dark Factory is built specifically for Claude Code)
• Docker — agents run in sandboxed containers
• GitHub CLI (gh) — authenticated with your account
• Anthropic API key or Claude Code OAuth token
• Go 1.22+ — for building from source

Install from source

go install github.com/peter-stratton/dark-factory/cmd/godark@latest

Verify installation

godark version
godark doctor

The doctor command checks that all dependencies are in place — Docker running, gh authenticated, API key set, and toolchain available.

Project Setup

Initialize an existing project

cd your-project
godark init --repo owner/your-project

This writes:

• godark.yaml — project configuration (only if it doesn't exist)
• .claude/skills/ — all nine godark skill files (always overwritten)

Create a new project

godark new my-project --repo owner/my-project

Creates the directory, initializes git, and scaffolds all harness files including CLAUDE.md, .gitignore, and documentation structure.

Configure the project

Use the /godark-configure-project skill to auto-detect your build commands, environment variables, CI checks, and Docker configuration:

# In Claude Code:
/godark-configure-project

Or edit godark.yaml manually. See the Configuration guide for all options.

Tutorial: Your First Autonomous Run

1. Clone the demo repository

git clone https://github.com/peter-stratton/dark-factory-demo
cd dark-factory-demo

The demo repo comes pre-configured with godark.yaml, a roadmap, planning docs, and scenario specs for a small Go project.

2. Create the roadmap and issues

The demo repo already has a milestone with issues ready to process. Verify with:

godark vet issues --tag phase-1
godark vet scenarios --tag phase-1

3. Dry run

See what Dark Factory would do without actually running agents:

godark run --tag phase-1 --dry-run

This prints the execution plan — resolved dependencies, issue order, and configuration.

4. Run it

godark run --tag phase-1 --auto-merge-feature low_risk

Dark Factory will:

• Fetch all issues from the Phase 1 milestone
• Resolve dependency chains
• For each unblocked issue: implement → quality review → functional review → merge
• Auto-merge PRs classified as low risk

5. Monitor progress

Open the dashboard in another terminal:

godark status

Navigate to http://localhost:8374 to watch the run in real time.

6. Review results

godark analyze --repo owner/dark-factory-demo

See outcome distribution, retry stats, costs, and any detected prompt gaps.

Next Steps

• CLI Reference — all commands and flags
• Configuration — deep dive into godark.yaml
• Skills — scaffold roadmaps, planning docs, and more