{"id":47669718,"url":"https://github.com/abdelrahman-mohammad/claude-code-loops","last_synced_at":"2026-04-02T12:28:50.668Z","repository":{"id":346559500,"uuid":"1190500744","full_name":"abdelrahman-mohammad/claude-code-loops","owner":"abdelrahman-mohammad","description":"Autonomous code-review-fix loops for Claude Code","archived":false,"fork":false,"pushed_at":"2026-03-25T11:17:29.000Z","size":142,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T14:19:04.333Z","etag":null,"topics":["agentic","automation","cicd","claude","claude-ai","claude-code","code-review"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/claude-code-loops","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abdelrahman-mohammad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":null,"dco":null,"cla":null}},"created_at":"2026-03-24T10:46:40.000Z","updated_at":"2026-03-25T11:17:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abdelrahman-mohammad/claude-code-loops","commit_stats":null,"previous_names":["abdelrahman-mohammad/claude-code-loops"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/abdelrahman-mohammad/claude-code-loops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abdelrahman-mohammad%2Fclaude-code-loops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abdelrahman-mohammad%2Fclaude-code-loops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abdelrahman-mohammad%2Fclaude-code-loops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abdelrahman-mohammad%2Fclaude-code-loops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abdelrahman-mohammad","download_url":"https://codeload.github.com/abdelrahman-mohammad/claude-code-loops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abdelrahman-mohammad%2Fclaude-code-loops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31306036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agentic","automation","cicd","claude","claude-ai","claude-code","code-review"],"created_at":"2026-04-02T12:28:50.115Z","updated_at":"2026-04-02T12:28:50.659Z","avatar_url":"https://github.com/abdelrahman-mohammad.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-code-loops (WIP)\n\n[![CI](https://github.com/abdelrahman-mohammad/claude-code-loops/actions/workflows/ci.yml/badge.svg)](https://github.com/abdelrahman-mohammad/claude-code-loops/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/claude-code-loops)](https://www.npmjs.com/package/claude-code-loops)\n[![npm downloads](https://img.shields.io/npm/dm/claude-code-loops)](https://www.npmjs.com/package/claude-code-loops)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nAutonomous code-review-fix loops for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).\n\nScaffolds Claude Code configurations (agents, hooks, rules, CLAUDE.md, orchestration scripts) for automated coder-reviewer loops across multiple tech stacks.\n\n## Quick Start\n\n```bash\n# 1. Scaffold into your project\ncd your-project\nnpx ccl init          # or: npx claude-code-loops init\n\n# 2. Write a task\necho \"Add input validation to all API endpoints\" \u003e task.md\n\n# 3. Run the loop (coder → commit → build gate → reviewer → repeat)\nbash scripts/loop.sh task.md\n```\n\nThat's it. The loop runs up to 10 iterations with smart stopping -- it exits early when tests pass and the reviewer gives LGTM.\n\n### Pick a stack\n\n```bash\nnpx ccl init --stack node         # Node.js / TypeScript\nnpx ccl init --stack spring-boot  # Java / Spring Boot\nnpx ccl init --stack fastapi      # Python / FastAPI\nnpx ccl init --stack django       # Python / Django\nnpx ccl init --stack nextjs       # Next.js\nnpx ccl init --stack generic      # Any project\n```\n\nOr just run `npx ccl init` -- it auto-detects your stack.\n\n## What Gets Created\n\n```\nyour-project/\n├── .claude/\n│   ├── agents/\n│   │   ├── coder.md          # Coding agent with write access\n│   │   └── reviewer.md       # Review agent (read-only)\n│   ├── rules/\n│   │   └── safety.md         # Protected file rules\n│   └── settings.json         # Hooks for auto-formatting \u0026 safety\n├── scripts/\n│   ├── loop.sh               # Main orchestration loop\n│   └── lib/\n│       ├── logging.sh        # Timestamped logging\n│       ├── git-commit.sh     # Auto-commit utilities\n│       ├── rate-limit.sh     # Rate limit detection \u0026 backoff\n│       ├── stopping.sh       # Smart stopping conditions\n│       ├── monitor.sh        # Live tmux dashboard\n│       └── report.sh         # Post-loop markdown reports\n├── CLAUDE.md                 # Project conventions for Claude\n└── .claudeignore             # Files Claude should ignore\n```\n\n## Stacks\n\n| Stack                  | Coder Agent                 | Reviewer Agent              | Auto-format         | Extras                                     |\n| ---------------------- | --------------------------- | --------------------------- | ------------------- | ------------------------------------------ |\n| **Node.js/TypeScript** | Senior TS engineer          | Principal engineer reviewer | Prettier            | TypeScript strict rules                    |\n| **Java/Spring Boot**   | Spring Boot engineer        | Spring reviewer             | google-java-format  | Spring DI rules, compile-check Stop hook   |\n| **Python/FastAPI**     | Async Python engineer       | FastAPI reviewer            | ruff format + check | Pydantic v2 rules, async correctness       |\n| **Python/Django**      | Django engineer             | Django reviewer             | ruff + djlint       | ORM patterns, N+1 detection                |\n| **Next.js**            | Full-stack Next.js engineer | Next.js reviewer            | Prettier + ESLint   | App Router rules, Server/Client boundaries |\n| **Generic**            | --                          | General code reviewer       | --                  | Minimal setup for any project              |\n\nAll agents run on Sonnet by default. The coder and reviewer run in **separate context windows** -- the reviewer cannot see the coder's reasoning, providing genuine independent review.\n\n## Commands\n\n### `init` -- Scaffold Configuration\n\n```bash\nccl init [options]\n\nOptions:\n  -s, --stack \u003cstack\u003e    Stack: node, spring-boot, fastapi, django, nextjs, generic\n  --no-interactive       Skip prompts, use defaults\n```\n\n### `plan` -- Generate Task Files\n\nConvert requirements into structured task files for the loop:\n\n```bash\nccl plan requirements.md                                    # From a file\nccl plan --input https://github.com/org/repo/issues/42     # From a GitHub issue\nccl plan --prompt \"Add JWT authentication to the API\"       # From inline text\n```\n\n### `run` -- Execute the Loop\n\nFirst-class CLI wrapper around `loop.sh` with signal forwarding:\n\n```bash\nccl run task.md                              # Defaults: 10 iterations, smart stopping\nccl run task.md --iterations 5 --coder-turns 30   # Customize\nccl run task.md --dry-run                    # Preview resolved config without running\n```\n\n### `status` -- Show Project Configuration\n\n```bash\nccl status              # Human-friendly summary of current setup\nccl status --json       # Machine-readable JSON output\n```\n\n### `doctor` -- Verify Setup\n\nDiagnostic checks to verify your setup is correct and catch common issues:\n\n```bash\nccl doctor              # Run all checks\n```\n\n### `upgrade` -- Update Scaffolded Files\n\nUpdate scaffolded files to the latest template versions:\n\n```bash\nccl upgrade             # Update templates to latest\n```\n\n### `agent list` -- List Agents\n\nList all agents and their configuration, including per-agent overrides:\n\n```bash\nccl agent list          # Show all agents\nccl agent list --json   # Machine-readable JSON output\n```\n\n### `history` -- Show Loop Run Results\n\nShow latest loop run data and iteration breakdown:\n\n```bash\nccl history             # Show latest run results\nccl history --json      # Machine-readable JSON output\n```\n\n### Running the Loop Directly\n\n```bash\nbash scripts/loop.sh \u003ctask-file\u003e [OPTIONS]\n\nOptions:\n  --iterations N          Max iterations (default: 10)\n  --coder-agent NAME      Agent for coding (default: coder)\n  --reviewer-agent NAME   Agent for review (default: reviewer)\n  --coder-turns N         Max turns for coder (default: 20)\n  --reviewer-turns N      Max turns for reviewer (default: 8)\n  --no-commit             Skip auto-commit after each phase\n  --log-dir DIR           Log directory (default: .claude/logs)\n  --permission-mode MODE  Permission mode (default: acceptEdits)\n  --coder-budget \u003cusd\u003e    Max cost per coder call (e.g. 2.00)\n  --reviewer-budget \u003cusd\u003e Max cost per reviewer call (e.g. 1.00)\n  --phase-timeout \u003cduration\u003e Timeout per phase (e.g. 10m, 1h)\n\nStopping conditions (all ON by default except opt-in):\n  --stop-on-pass          Exit on tests pass + LGTM review\n  --stop-on-no-progress   Circuit breaker for stuck agents\n  --build-gate            Skip reviewer on build failure\n  --zero-diff-halt        Halt on no changes for 2 iterations\n  --coverage-threshold N  Stop when coverage meets target (opt-in)\n  --token-budget N        Cost ceiling across iterations (opt-in)\n  --time-limit N          Wall-clock timeout in minutes (opt-in)\n\nMonitoring:\n  --monitor               Live tmux dashboard showing iteration progress\n```\n\n## How It Works\n\n```\n                       ┌──────────────────────────────────────────────┐\n                       ▼                                              │\n┌──────────┐     ┌───────────┐     ┌───────────┐     ┌──────────┐     │\n│  Task /  │────\u003e│   Coder   │────\u003e│   Auto    │────\u003e│  Build   │     │\n│ Findings │     │   Agent   │     │  commit   │     │   Gate   │     │\n└──────────┘     └───────────┘     └───────────┘     └────┬─────┘     │\n     ▲                                                    │           │\n     │                                             Pass? ─┼─ No ──────┘\n     │                                                    │\n     │                                                   Yes\n     │                                                    │\n     │           ┌───────────┐     ┌────────────┐         ▼\n     └───FAIL────│   Stop    │\u003c────│  Reviewer  │\u003c────────┘\n                 │ Conditions│     │   Agent    │\n                 └─────┬─────┘     └────────────┘\n                       │\n                      Met?\n                       │\n                       ├─ Yes: exit with report\n                       └─ No: next iteration\n```\n\n1. **Coder agent** reads the task (or review findings) and implements/fixes code\n2. **Auto-commit** saves the changes\n3. **Build gate** checks compilation -- skips reviewer on build failure\n4. **Reviewer agent** examines the diff, runs tests, produces PASS/FAIL verdict\n5. **Stop conditions** evaluate: tests passing, progress stalled, budget exceeded, coverage met\n6. If no stop condition triggers: findings feed back to coder for next iteration\n\n## Using Agents Directly\n\nThe scaffolded agents work standalone too:\n\n```bash\nclaude --agent coder \"Implement the user registration endpoint\"\nclaude --agent reviewer \"Review all recent changes\"\n```\n\n## Merge Behavior\n\nRunning `init` on a project with an existing `.claude/` directory offers three options:\n\n- **Merge** (default): Add new files, skip existing ones. `settings.json` and `CLAUDE.md` are always merged intelligently.\n- **Overwrite**: Replace all files.\n- **Backup**: Copy existing `.claude/` to `.claude.backup-\u003ctimestamp\u003e/`, then overwrite.\n\nRe-running `init` is safe -- `CLAUDE.md` uses comment markers to replace only the generated section, preserving your edits.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, development commands, and how to add a new stack.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabdelrahman-mohammad%2Fclaude-code-loops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabdelrahman-mohammad%2Fclaude-code-loops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabdelrahman-mohammad%2Fclaude-code-loops/lists"}