{"id":45021874,"url":"https://github.com/alexander-akhmetov/programmator","last_synced_at":"2026-02-27T22:29:02.723Z","repository":{"id":336031024,"uuid":"1137420587","full_name":"alexander-akhmetov/programmator","owner":"alexander-akhmetov","description":"Autonomous Claude Code orchestrator that executes multi-task plans without supervision.","archived":false,"fork":false,"pushed_at":"2026-02-03T00:15:46.000Z","size":7555,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T01:33:12.267Z","etag":null,"topics":["ai-agents","ai-orchestration","claude-code","codex","ralph","ralph-loop","ralph-wiggum"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexander-akhmetov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-19T10:49:49.000Z","updated_at":"2026-02-02T23:10:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alexander-akhmetov/programmator","commit_stats":null,"previous_names":["alexander-akhmetov/programmator"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/alexander-akhmetov/programmator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexander-akhmetov%2Fprogrammator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexander-akhmetov%2Fprogrammator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexander-akhmetov%2Fprogrammator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexander-akhmetov%2Fprogrammator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexander-akhmetov","download_url":"https://codeload.github.com/alexander-akhmetov/programmator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexander-akhmetov%2Fprogrammator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29601108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T00:59:38.239Z","status":"online","status_checked_at":"2026-02-19T02:00:07.702Z","response_time":117,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-orchestration","claude-code","codex","ralph","ralph-loop","ralph-wiggum"],"created_at":"2026-02-19T02:35:04.679Z","updated_at":"2026-02-27T22:29:02.718Z","avatar_url":"https://github.com/alexander-akhmetov.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Programmator\n\n[![CI](https://github.com/alexander-akhmetov/programmator/actions/workflows/ci.yml/badge.svg)](https://github.com/alexander-akhmetov/programmator/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/alexander-akhmetov/programmator)](https://goreportcard.com/report/github.com/alexander-akhmetov/programmator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nAutonomous coding agent orchestrator that executes multi-task plans without supervision. Supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [pi coding agent](https://github.com/badlogic/pi-mono) as executors.\n\nCoding agents are interactive — they require you to watch, approve, and guide each step. For complex features spanning multiple tasks, this means hours of babysitting. As context fills up during long sessions, the model starts making mistakes and producing worse code.\n\nProgrammator splits work into isolated sessions with fresh context windows. Each task runs independently, gets reviewed by parallel agents, and can be auto-committed on completion with no supervision needed.\n\n## Install with Claude Code\n\nThe plugin can help you install and configure programmator. For manual installation without the plugin, see [Manual Install](#manual-install).\n\n**1. Install the plugin:**\n\n```bash\nclaude plugin marketplace add alexander-akhmetov/programmator\nclaude plugin install -s user programmator\n```\n\n**2. Ask Claude to install and configure programmator:**\n\nClaude will help you install the binary, verify your executor is available, and optionally create a config file. Just ask — for example: *\"install and configure programmator\"*.\n\n**3. Use it:**\n\nCreate plans manually or use `/plan-to-file` to convert Claude Code plans. Then run `programmator start ./plan.md`.\n\n## Manual Install\n\nDownload a binary from [GitHub Releases](https://github.com/alexander-akhmetov/programmator/releases), or install with Go (requires 1.26+):\n\n```bash\ngo install github.com/alexander-akhmetov/programmator/cmd/programmator@latest\n```\n\nYou'll also need at least one executor: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [pi coding agent](https://github.com/badlogic/pi-mono).\n\n## Quick Start\n\nWrite a plan file (`plan.md`):\n```markdown\n# Plan: Fix calculator bugs\n\n## Validation Commands\n- `go test ./...`\n\n## Tasks\n- [ ] Fix add() to return a + b instead of a - b\n- [ ] Fix off-by-one error in loop\n- [ ] Add missing nil check in User handler\n```\n\nRun it:\n```bash\nprogrammator start ./plan.md\n```\n\nProgrammator picks up the first unchecked task, invokes Claude Code to complete it, marks it done, and moves to the next. After all tasks complete, it runs a multi-agent code review. When everything passes (or safety limits are hit), it stops.\n\n## Examples\n\n### Use pi coding agent instead of Claude Code\n\nCreate `~/.config/programmator/config.yaml`:\n\n```yaml\nexecutor: pi\npi:\n  provider: anthropic # optional\n  model: sonnet       # optional\n```\n\nThen `programmator start ./plan.md` uses pi for all tasks instead of Claude Code.\n\n### Minimal config: your own executor + one custom review agent\n\nBy default, programmator runs 9 review agents after task completion. You can replace them all with a single custom one:\n\n```yaml\nexecutor: pi\n\nreview:\n  agents:\n    - name: code-review\n      focus:\n        - correctness\n        - error handling\n        - test coverage\n```\n\nThis runs pi for coding and a single `code-review` agent for the final review pass. You can also point to a full custom prompt file:\n\n```yaml\nreview:\n  agents:\n    - name: code-review\n      prompt_file: \".programmator/prompts/review/code-review.md\"\n```\n\nAnd in `.programmator/prompts/review/code-review.md`:\n\n``` markdown\nDo a good code review please.\n```\n\n### Code with pi, review with Claude Opus\n\n```yaml\nexecutor: pi\n\nreview:\n  executor:\n    name: claude\n    claude:\n      flags: \"--model opus\"\n```\n\n## How It Works\n\nEach iteration:\n1. Reads the plan file and finds the first uncompleted task\n2. Builds a prompt with the task context and instructions\n3. Invokes the configured executor in a fresh session\n4. Parses the executor's `PROGRAMMATOR_STATUS` output block (YAML with status, files changed, summary)\n5. Updates the task checkbox and logs progress\n6. Checks safety limits, then loops back\n\nAfter all tasks are done, a [multi-agent review](#review) runs automatically.\n\n## Plan\n\nWhen you run `programmator start \u003cthing\u003e`, the source type is auto-detected from the argument: file paths → plan file, everything else → ticket ID.\n\n### Tickets\n\nIf you have [ticket](https://github.com/wedow/ticket) CLI installed, programmator can use it to get the plan from the ticket. Tickets are markdown files with YAML frontmatter and checkbox phases.\n\n### Files\n\nA plan file is a markdown file with checkbox tasks:\n\n```markdown\n# Plan: Feature Name\n\n## Validation Commands\n- `go test ./...`\n- `golangci-lint run`\n\n## Tasks\n- [x] Task 1: Investigate current implementation and update plan.md (already completed, will be skipped)\n- [ ] Task 2: Implement the feature\n- [ ] Task 3: Add tests\n- [ ] Task 4: Cleanup\n```\n\n- **Title**: First `# ` heading (optional `Plan:` prefix)\n- **Validation Commands**: Run after each task completion (optional)\n- **Tasks**: Checkbox items (`- [ ]` / `- [x]`) anywhere in the file\n\n## Review\n\nAfter all tasks complete, programmator automatically runs a multi-agent code review. By default 9 agents run in parallel (bug-shallow, bug-deep, architect, simplification, silent-failures, claudemd, type-design, comments, tests-and-linters). Issues found are auto-fixed and re-reviewed, up to 3 iterations.\n\nReview configuration is flexible:\n- Use the default 9 agents\n- Select a subset with `review.include` / `review.exclude`\n- Override prompts/focus for default agents with `review.overrides`\n- Replace defaults entirely with a custom `review.agents` list\n- Use a different executor/model for review via `review.executor`\n\nYou can also run review standalone on any branch:\n\n```bash\nprogrammator review                       # review current branch vs main\nprogrammator review --base develop        # review against a different base\n```\n\n## Commands\n\n```bash\nprogrammator start ./plan.md              # execute a plan\nprogrammator start ./plan.md --auto-commit # with git workflow (branch + commits)\nprogrammator start pro-1a2b               # execute a ticket\nprogrammator review                       # review-only mode on current branch\nprogrammator run \"explain this codebase\"  # run configured coding agent with a custom prompt\nprogrammator config show                  # show resolved config\n```\n\n`programmator run` is a lightweight wrapper around the configured coding agent — pass any prompt as an argument or pipe via stdin. Useful for one-off tasks that don't need plan tracking.\n\n## Safety Gates\n\n- **Guard mode**: If [dcg](https://github.com/Dicklesworthstone/destructive_command_guard) is installed, programmator uses it to block destructive shell commands during autonomous execution.\n- **Max iterations**: Prevents runaway loops (default: 50)\n- **Stagnation detection**: Exits if no files change for N iterations (default: 3)\n- **Error repetition**: Exits if same error occurs 3 times\n- **Timeout**: Kills the executor if a single invocation takes too long (default: 900s)\n- **Ctrl+C**: Graceful stop after current iteration\n\n## Auto Git Workflow\n\nOpt-in via config or CLI flags:\n- `--auto-commit`: Creates a `programmator/\u003cslug\u003e` branch, commits after each phase\n- `--move-completed`: Moves completed plans to `plans/completed/`\n- `--branch [optional name]`: Custom branch name\n\n## Configuration\n\nProgrammator uses a unified YAML config with multi-level merge (highest priority last):\n\n1. [Embedded defaults](internal/config/defaults/config.yaml) (built into binary)\n2. Global config (`~/.config/programmator/config.yaml`)\n3. Local config (`.programmator/config.yaml` in project directory)\n4. CLI flags\n\nSee resolved values with `programmator config show`.\n\n\u003cdetails\u003e\n\u003csummary\u003eConfig keys\u003c/summary\u003e\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `max_iterations` | `50` | Maximum loop iterations before forced exit |\n| `stagnation_limit` | `3` | Exit after N consecutive iterations with no file changes |\n| `timeout` | `900` | Seconds per executor invocation |\n| `executor` | `claude` | Which coding agent to use (`\"claude\"` or `\"pi\"`) |\n| `claude.flags` | `\"\"` | Additional flags passed to the `claude` command |\n| `claude.config_dir` | `\"\"` | Custom Claude config directory (empty = default) |\n| `claude.anthropic_api_key` | `\"\"` | Anthropic API key passed to Claude (overrides env) |\n| `pi.flags` | `\"\"` | Additional flags passed to the `pi-coding-agent` command |\n| `pi.config_dir` | `\"\"` | Custom PI_CODING_AGENT_DIR (empty = default) |\n| `pi.provider` | `\"\"` | LLM provider for pi (e.g. `\"anthropic\"`, `\"openai\"`) |\n| `pi.model` | `\"\"` | Model name for pi (e.g. `\"sonnet\"`, `\"gpt-4o\"`) |\n| `pi.api_key` | `\"\"` | API key for the configured pi provider |\n| `ticket_command` | `tk` | Binary name for the ticket CLI (`tk` or `ticket`) |\n| `git.auto_commit` | `false` | Auto-commit after each phase completion |\n| `git.move_completed_plans` | `false` | Move completed plans to a `completed/` directory |\n| `git.completed_plans_dir` | `\"\"` | Directory for completed plans (default: `plans/completed`) |\n| `git.branch_prefix` | `\"\"` | Prefix for auto-created branches (default: `programmator/`) |\n| `review.max_iterations` | `3` | Maximum review fix iterations |\n| `review.parallel` | `true` | Run review agents in parallel |\n| `review.executor.name` | `\"\"` | Optional review executor override (`claude` / `pi`, empty = inherit top-level) |\n| `review.executor.claude.flags` | `\"\"` | Review-only Claude flags (for example `--model opus`) |\n| `review.executor.pi.*` | `\"\"` | Review-only PI settings (`flags`, `config_dir`, `provider`, `model`, `api_key`) |\n| `review.include` | `[]` | Subset of built-in review agents (empty = all defaults) |\n| `review.exclude` | `[]` | Remove specific default review agents |\n| `review.overrides` | `[]` | Override default agents by name (focus/prompt/prompt_file) |\n| `review.agents` | `[]` | Explicit custom review agents; when non-empty replaces defaults |\n| `review.validators.issue` | `true` | Run cross-agent false-positive validator |\n| `review.validators.simplification` | `true` | Run simplification value validator |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eEnvironment variables\u003c/summary\u003e\n\nEnvironment variables used by programmator and its executors:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PROGRAMMATOR_DEBUG` | `\"\"` | Set to `1` to enable debug output |\n| `PROGRAMMATOR_STATE_DIR` | XDG state dir | Override the state directory path |\n| `TICKETS_DIR` | `~/.tickets` | Where ticket files live |\n| `CLAUDE_CONFIG_DIR` | - | Custom Claude config directory (passed to Claude subprocess) |\n| `PI_CODING_AGENT_DIR` | - | Custom pi coding agent config directory |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePrompt templates\u003c/summary\u003e\n\nPrompts are customizable via Go `text/template` files. Override any prompt by placing a file in:\n- `~/.config/programmator/prompts/` (global)\n- `.programmator/prompts/` (per-project)\n\nAvailable templates: `phased.md`, `phaseless.md`, `review_first.md`. See [prompt template docs](docs/prompt_templates.md) for variables and examples.\n\n\u003c/details\u003e\n\n## Claude Code Plugin\n\nThe plugin (see [Install with Claude Code](#install-with-claude-code)) provides:\n\n- **`/programmator-setup`** — Guided install and configuration of programmator.\n- **`/plan-to-file`** — Convert the most recent Claude Code plan into a programmator plan file (`plan.md`), ready for `programmator start ./plan.md`.\n- **`/plan-to-ticket`** — Convert the most recent Claude Code plan into a programmator ticket (requires `ticket` CLI).\n\n## Documentation\n\n- [Orchestration flow](docs/orchestration.md) — detailed walkthrough of execution and review\n- [Prompt templates](docs/prompt_templates.md) — override chain, template variables, customization\n- [E2E tests](docs/e2e_tests.md) — manual integration tests\n\n## Development\n\n```bash\ngo build ./...                # Build\ngo test ./...                 # Run tests\ngo test -race ./...           # Run tests with race detector\nmake lint                     # Lint (golangci-lint + govulncheck + deadcode + go mod tidy)\n\n# E2E test prep (creates toy projects in /tmp)\nmake e2e-prep                 # Plan-based run\nmake e2e-review               # Review mode\n```\n\n## Releasing\n\nPush a git tag to trigger a GitHub Actions release via GoReleaser:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\nBinaries are published for linux/darwin (amd64/arm64).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexander-akhmetov%2Fprogrammator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexander-akhmetov%2Fprogrammator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexander-akhmetov%2Fprogrammator/lists"}