Configuration

Copy configs/programgen.toml to programgen.toml. The three main commands read that file by default; use --config PATH for another file.

Required settings

search uses GITHUB_TOKEN or GH_TOKEN. An explicit --token-file takes precedence and must exist. No credential is needed for configuration-only checks.

Non-Claude model names with an endpoint use the built-in Messages runner. Claude-prefixed names select the optional Claude Code SDK runner (pip install -e '.[sdk]'). Diagnostics at command startup report missing runtime requirements.

Paths and modes

Single-create paths follow the original API: they are relative to the current working directory. Search and produce paths are relative to their configuration file. The starter file explains both rules beside the affected fields.

The shared file loads the appropriate built-in quality defaults separately for each mode. Explicit fields override defaults and are checked against the production policy. A weakened configuration fails preflight rather than being silently fixed.

For advanced, different settings per mode, [produce].create_configs maps mode names to separate TOML files. create_config selects one explicit preset and rejects candidates of another mode. Those paths are relative to the producer file.

[produce]
candidates = "candidates.jsonl"
output = "tasks"
workers = 2
create_configs = {with-binary = "with-binary.toml", without-binary = "without-binary.toml"}

Inputs

A minimal row is {"repo":"owner/repository","commit":"FULL_40_CHARACTER_SHA"}. Optional mode and binary select a mode and executable build target. Aliases programbench, nl2repo, with_binary and without_binary are accepted. For Go programs a root package target is commonly binary=".".

The original repo_key/commit_sha inventory shape, JSONL gzip inputs and read-only HF inventories remain supported. HF manifests are checked against their recorded hashes and row counts. No shard claims or dataset publishing service is required for local production.

Optional overrides

Only add settings you need. Budget defaults include session time, turns and attempts. Runtime options include Docker image, CPU/memory limits and toolchain selection. Quality overrides may strengthen the documented floors; production rejects settings that weaken them.

programgen create --repo owner/repo --check inspects the effective single-task policy. programgen produce --check additionally validates every candidate's mode and preset. These commands do not generate tasks or call the model.

For Git-aware command-line programs, keep the task work directory and TMPDIR outside unrelated Git checkouts. Programs such as ripgrep can discover parent repository metadata independently of Git's environment settings. A clean writable directory under /var/tmp can be used when the host's usual temporary directory is itself inside a repository. Final Docker verification still checks every task.

Starter file

Generated directly from configs/programgen.toml. Download programgen.toml.

# Copy this file to programgen.toml in your working directory.
# One file works with search, create and produce. No settings below contain secrets.

[agent]
# Use an Anthropic Messages-compatible endpoint. A trailing /v1 is accepted.
# Alternatively remove this line and set ANTHROPIC_BASE_URL in your environment.
api_base_url = "https://your-api.example/v1"
# Replace this with the exact model identifier advertised by your service.
model = "your-model"
# Set the API key in your shell: export ANTHROPIC_API_KEY=...
# GitHub searches use GITHUB_TOKEN (or GH_TOKEN) from the environment.

[create]
# without-binary: reconstruct a repository from its generated specification.
# with-binary: reconstruct a program using documentation and a reference oracle.
# Override per invocation with --mode. Both modes include their quality defaults.
mode = "without-binary"
# Single-task output is relative to the directory where you run the command.
output = "tasks"

[search]
# GitHub repository search syntax; add language:, topic: or stars: filters.
query = "topic:developer-tools language:Python stars:>20"
limit = 20
# Search and produce paths are relative to this configuration file.
output = "candidates.jsonl"

[produce]
# Use the search output or a JSONL file of repo + full commit + optional mode/binary.
# A row's mode selects its own built-in preset. Rows without a mode use [create].mode.
candidates = "candidates.jsonl"
output = "tasks"
# Number of concurrent tasks on this machine. Start at 2; reduce for limited RAM/API capacity.
workers = 2
# Resume, bounded retries, timeouts, Docker isolation and quality floors are built in.
# See docs/configuration.md for optional overrides.