{"id":31991165,"url":"https://github.com/radleta/claude-iterate","last_synced_at":"2026-04-12T22:32:22.019Z","repository":{"id":318739529,"uuid":"1073783680","full_name":"radleta/claude-iterate","owner":"radleta","description":"A professional CLI tool for managing automated task iterations with Claude Code. Provides workspace management, instruction crafting, templates, and autonomous iteration loops—all with comprehensive TypeScript types and testing.","archived":false,"fork":false,"pushed_at":"2025-10-14T18:32:47.000Z","size":395,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-14T18:52:57.628Z","etag":null,"topics":["claude-code"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/radleta.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":"2025-10-10T16:01:29.000Z","updated_at":"2025-10-14T18:32:51.000Z","dependencies_parsed_at":"2025-10-14T18:53:06.535Z","dependency_job_id":null,"html_url":"https://github.com/radleta/claude-iterate","commit_stats":null,"previous_names":["radleta/claude-iterate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/radleta/claude-iterate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fclaude-iterate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fclaude-iterate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fclaude-iterate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fclaude-iterate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radleta","download_url":"https://codeload.github.com/radleta/claude-iterate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radleta%2Fclaude-iterate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020335,"owners_count":26086868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"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":["claude-code"],"created_at":"2025-10-15T11:51:59.859Z","updated_at":"2026-04-12T22:32:21.997Z","avatar_url":"https://github.com/radleta.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-iterate\n\n---\n\n\u003e ⚙️ **Built with AI-Paired Development**\n\u003e This project was rapidly developed using AI-assisted workflows (Claude Code, Gemini, ChatGPT) under my direction. While it contains known bugs and rough edges due to scope and velocity, it reflects real-world utility and has been validated through integration tests and end-user use. Architecture and system behavior were guided and owned by me.\n\n---\n\nAutomate multi-step tasks with Claude Code through managed workspaces, reusable templates, and autonomous iteration loops.\n\n[![Tests](https://img.shields.io/badge/tests-228%20passing-brightgreen)](https://github.com/radleta/claude-iterate)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](https://www.typescriptlang.org/)\n[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n## Features\n\n- 🎯 **Workspace Management** - Isolated environments for complex tasks\n- 🔄 **Autonomous Execution** - Iteration loops that run until completion\n- 🎭 **Dual Modes** - Loop (incremental) or iterative (autonomous) execution\n- 🛡️ **Stagnation Detection** - Automatic stop after N consecutive no-work iterations (iterative mode)\n- 📦 **Templates** - Reusable patterns for common workflows\n- ⚙️ **Git-Style Config** - Layered configuration (project, user, runtime)\n- 📁 **Archives** - Preserve and restore completed work\n- 🔔 **Notifications** - HTTP notifications for long-running tasks (ntfy.sh compatible)\n\n## Quick Start\n\n```bash\n# Install globally\nnpm install -g claude-iterate\n\n# Create a workspace\nclaude-iterate init my-feature\n\n# Set up instructions interactively\nclaude-iterate setup my-feature\n\n# Run the autonomous loop\nclaude-iterate run my-feature\n```\n\nClaude will read your instructions, track progress in `TODO.md`, and iterate until complete.\n\n## Installation\n\n### Global (Recommended)\n\n```bash\nnpm install -g claude-iterate\n```\n\n### Local\n\n```bash\nnpm install claude-iterate\nnpx claude-iterate init my-task\n```\n\n### Requirements\n\n- Node.js \u003e= 18.0.0\n- Claude CLI installed and in PATH\n\n## Core Concepts\n\n### Workspaces\n\nIsolated task environments with:\n\n- `INSTRUCTIONS.md` - What Claude should do\n- `TODO.md` - Progress tracking (human-readable)\n- `.status.json` - Completion status (machine-readable)\n- `.metadata.json` - Iteration state\n- `iterate-*.log` - Timestamped execution logs\n- `working/` - Scratch space\n\n#### Status Tracking\n\nClaude tracks progress in two complementary files:\n\n**TODO.md** - Human-readable task list and notes for Claude's working context\n\n**.status.json** - Machine-readable progress signals for reliable completion detection:\n\n```json\n{\n  \"complete\": false,\n  \"progress\": {\n    \"completed\": 35,\n    \"total\": 60\n  },\n  \"summary\": \"Migrated 35/60 API endpoints\",\n  \"lastUpdated\": \"2025-10-16T14:30:00Z\"\n}\n```\n\nClaude updates `.status.json` each iteration. When `complete: true`, the task is finished. This prevents false positives from completion markers appearing in instructions or examples.\n\n### Execution Modes\n\n**Loop Mode (Default)**\n\n- Incremental progress with explicit step tracking\n- Complete one item per iteration\n- Best for tasks with discrete steps\n- Default max: 50 iterations\n\n**Iterative Mode**\n\n- Autonomous work sessions completing multiple items\n- Complete as many items as possible per iteration\n- Best for complex tasks requiring sustained focus\n- Default max: 20 iterations (does more per iteration)\n- **Stagnation detection**: Automatically stops after N consecutive iterations with no work (default: 2, prevents infinite loops)\n\n```bash\n# Use iterative mode\nclaude-iterate init my-task --mode iterative\n\n# Customize stagnation threshold\nclaude-iterate init my-task --mode iterative --stagnation-threshold 5\n\n# Disable stagnation detection (trust Claude completely)\nclaude-iterate init my-task --mode iterative --stagnation-threshold 0\n```\n\n### Templates\n\nSave successful workflows as reusable templates:\n\n```bash\n# Save workspace as template (uses workspace name)\nclaude-iterate template save my-task\n\n# Save with custom template name\nclaude-iterate template save my-task api-migration\n\n# Save to global templates\nclaude-iterate template save my-task --global\n\n# Update existing template\nclaude-iterate template save my-task --force\n\n# Use a template\nclaude-iterate template use api-migration new-service\n```\n\nTemplates can be project-specific (`./claude-iterate/templates/`) or global (`~/.config/claude-iterate/templates/`).\n\n### Configuration\n\nLayered configuration with priority: CLI flags → Project config → User config → Defaults\n\n```bash\n# Project: .claude-iterate.json\n# User: ~/.config/claude-iterate/config.json\n\n# View configuration\nclaude-iterate config --list\n\n# Set values\nclaude-iterate config defaultMaxIterations 100\nclaude-iterate config --global notifyUrl https://ntfy.sh/my-topic\n```\n\n## Commands Reference\n\n### Workspace Operations\n\n| Command                | Description                     |\n| ---------------------- | ------------------------------- |\n| `init \u003cname\u003e`          | Initialize a new workspace      |\n| `list`                 | List all workspaces with status |\n| `show \u003cname\u003e`          | Show workspace details          |\n| `clean \u003cname\u003e --force` | Archive and delete workspace    |\n| `reset \u003cname\u003e`         | Reset iteration counts          |\n\n### Instructions\n\n| Command           | Description                       |\n| ----------------- | --------------------------------- |\n| `setup \u003cname\u003e`    | Create instructions interactively |\n| `edit \u003cname\u003e`     | Modify instructions interactively |\n| `validate \u003cname\u003e` | Validate instruction quality      |\n\n### Verification\n\n| Command         | Description                      |\n| --------------- | -------------------------------- |\n| `verify \u003cname\u003e` | Verify workspace work completion |\n\n**Options:**\n\n- `--depth \u003clevel\u003e` - Verification depth: quick, standard, deep\n- `--report-path \u003cpath\u003e` - Custom report path\n- `--json` - Output JSON results\n- `--show-report` - Show full report in console\n- `-v, --verbose` - Show full Claude output\n- `-q, --quiet` - Silent execution, errors only\n- `--dangerously-skip-permissions` - Skip permission prompts (runtime only)\n\n**Depth Levels:**\n\n- `quick` (~500-1K tokens): File existence and basic count verification\n- `standard` (~2-4K tokens): Balanced deliverable review with quality checks (default)\n- `deep` (~5-10K tokens): Comprehensive code quality, edge cases, and documentation analysis\n\n**Exit codes:** 0 = verified complete, 1 = incomplete/needs review\n\n**Usage Examples:**\n\n```bash\n# Basic verification (may prompt for permissions)\nclaude-iterate verify my-workspace\n\n# Autonomous verification (no prompts)\nclaude-iterate verify my-workspace --dangerously-skip-permissions\n\n# Deep verification with verbose output\nclaude-iterate verify my-workspace --depth deep --verbose --dangerously-skip-permissions\n\n# Quick verification with custom report location\nclaude-iterate verify my-workspace --depth quick --report-path ./reports/verify.md\n```\n\n**Note:** Verification requires Claude CLI to read workspace files and write reports. For autonomous operation without permission prompts, use `--dangerously-skip-permissions` or configure `claude.args` in your project/user config. See [Security: Permission Prompts](#security-permission-prompts) for details.\n\n### Execution\n\n| Command      | Description                       |\n| ------------ | --------------------------------- |\n| `run \u003cname\u003e` | Run the autonomous iteration loop |\n\n**Options:**\n\n- `-m, --max-iterations \u003cn\u003e` - Override iteration limit\n- `-d, --delay \u003cseconds\u003e` - Delay between iterations\n- `--no-delay` - Skip delays\n- `--stagnation-threshold \u003cn\u003e` - Stop after N consecutive no-work iterations (iterative mode only, 0=never)\n- `-v, --verbose` - Show full Claude output (equivalent to --output verbose)\n- `-q, --quiet` - Silent execution, errors only (equivalent to --output quiet)\n- `--output \u003clevel\u003e` - Output level: quiet, progress, verbose\n- `--dangerously-skip-permissions` - Disable permission prompts (see security note)\n\n### Templates\n\n| Command                            | Description                    |\n| ---------------------------------- | ------------------------------ |\n| `template save \u003cworkspace\u003e [name]` | Save workspace as template     |\n| `template use \u003cname\u003e \u003cworkspace\u003e`  | Create workspace from template |\n| `template list`                    | List available templates       |\n| `template show \u003cname\u003e`             | Show template details          |\n\n**Options for `save`:**\n\n- `[name]` - Template name (defaults to workspace name if omitted)\n- `-d, --description \u003ctext\u003e` - Template description\n- `-t, --tags \u003ctags\u003e` - Comma-separated tags\n- `-g, --global` - Save to global templates\n- `-f, --force` - Overwrite existing template\n\n### Archives\n\n| Command                            | Description          |\n| ---------------------------------- | -------------------- |\n| `archive save \u003cname\u003e`              | Archive a workspace  |\n| `archive list`                     | List all archives    |\n| `archive restore \u003carchive\u003e [name]` | Restore an archive   |\n| `archive show \u003cname\u003e`              | Show archive details |\n| `archive delete \u003cname\u003e --force`    | Delete an archive    |\n\n### Configuration\n\n| Command                         | Description                |\n| ------------------------------- | -------------------------- |\n| `config [key] [value]`          | Get or set configuration   |\n| `config --list`                 | List all configuration     |\n| `config --keys`                 | Show available config keys |\n| `config --global [key] [value]` | Manage user config         |\n\n**Array operations:**\n\n```bash\nclaude-iterate config claude.args --add --dangerously-skip-permissions\nclaude-iterate config claude.args --remove --dangerously-skip-permissions\nclaude-iterate config claude.args --unset\n```\n\n### Discovering Configuration Keys\n\nTo see all available configuration keys with descriptions, types, defaults, and current values:\n\n```bash\n# Show project config keys\nclaude-iterate config --keys\n\n# Show user config keys\nclaude-iterate config --keys --global\n\n# Show workspace config keys\nclaude-iterate config --keys --workspace my-task\n\n# Get JSON output for scripting\nclaude-iterate config --keys --json\n```\n\nOutput includes:\n\n- Key name (with dot notation)\n- Type (string, number, boolean, array, enum, object)\n- Default value\n- **Current effective value and source** (user, project, or workspace) - color-coded for easy identification\n- Description and examples\n- Related keys and notes\n\nThe `--keys` command shows the current effective value for each setting along with its source, making it easy to understand which configuration is actually being used and where it comes from in the hierarchy (User → Project → Workspace).\n\n## Configuration\n\n### Project Configuration\n\nCreate `.claude-iterate.json` in your project root:\n\n```json\n{\n  \"workspacesDir\": \"./claude-iterate/workspaces\",\n  \"templatesDir\": \"./claude-iterate/templates\",\n  \"archiveDir\": \"./claude-iterate/archive\",\n  \"defaultMaxIterations\": 50,\n  \"defaultDelay\": 2,\n  \"defaultStagnationThreshold\": 2,\n  \"outputLevel\": \"progress\",\n  \"notifyUrl\": \"https://ntfy.sh/my-project\",\n  \"notifyEvents\": [\"all\"],\n  \"notification\": {\n    \"statusWatch\": {\n      \"enabled\": true,\n      \"debounceMs\": 2000,\n      \"notifyOnlyMeaningful\": true\n    }\n  },\n  \"verification\": {\n    \"autoVerify\": true,\n    \"resumeOnFail\": true,\n    \"maxAttempts\": 2,\n    \"reportFilename\": \"verification-report.md\",\n    \"depth\": \"standard\",\n    \"notifyOnVerification\": true\n  }\n}\n```\n\n### User Configuration\n\nCreate `~/.config/claude-iterate/config.json`:\n\n```json\n{\n  \"globalTemplatesDir\": \"~/.config/claude-iterate/templates\",\n  \"defaultMaxIterations\": 50,\n  \"defaultDelay\": 2,\n  \"defaultStagnationThreshold\": 2,\n  \"outputLevel\": \"progress\",\n  \"claude\": {\n    \"command\": \"claude\",\n    \"args\": []\n  },\n  \"colors\": true,\n  \"verification\": {\n    \"autoVerify\": true,\n    \"resumeOnFail\": true,\n    \"maxAttempts\": 2,\n    \"depth\": \"standard\"\n  }\n}\n```\n\n### Per-Workspace Configuration\n\nConfigure workspace-specific settings that override project and user defaults. This allows different workspaces to have different verification depths, output levels, or Claude settings.\n\n**Priority order**: CLI flags \u003e Workspace config \u003e Project config \u003e User config \u003e Defaults\n\n```bash\n# Set verification depth for a specific workspace\nclaude-iterate config --workspace my-task verification.depth deep\n\n# Set output level for a workspace\nclaude-iterate config --workspace my-task outputLevel verbose\n\n# Set Claude args for a workspace\nclaude-iterate config --workspace my-task claude.args --add --dangerously-skip-permissions\n\n# View workspace config\nclaude-iterate config --workspace my-task --list\n\n# Remove override (fall back to project/user config)\nclaude-iterate config --workspace my-task verification.depth --unset\n```\n\n**Available workspace config settings**:\n\n- `verification.depth` - Verification depth (quick, standard, deep) - default: standard\n- `verification.autoVerify` - Auto-verify on completion (default: true, ~2-4K tokens per verification)\n- `verification.resumeOnFail` - Resume iterations on failed verification (default: true)\n- `verification.maxAttempts` - Max verification attempts (1-10) - default: 2\n- `verification.reportFilename` - Custom report filename\n- `verification.notifyOnVerification` - Send verification notifications (true/false)\n- `outputLevel` - Console output level (quiet, progress, verbose)\n- `claude.command` - Override Claude CLI command\n- `claude.args` - Override Claude CLI arguments (use --add/--remove for arrays)\n\n**Example use cases**:\n\n```bash\n# Critical task - use deep verification\nclaude-iterate init api-migration\nclaude-iterate config --workspace api-migration verification.depth deep\n\n# Debug task - verbose output\nclaude-iterate init debug-task\nclaude-iterate config --workspace debug-task outputLevel verbose\n\n# Simple task - quick verification\nclaude-iterate init docs-update\nclaude-iterate config --workspace docs-update verification.depth quick\n\n# Now run without CLI flags (uses workspace config)\nclaude-iterate verify api-migration  # Uses deep\nclaude-iterate run debug-task        # Uses verbose output\nclaude-iterate verify docs-update    # Uses quick\n```\n\nWorkspace configuration is stored in `.metadata.json` under the `config` field and can be copied via templates:\n\n```bash\n# Create template with workspace config\nclaude-iterate config --workspace my-task verification.depth deep\nclaude-iterate template save my-task my-template\n\n# New workspaces from template inherit config\nclaude-iterate template use my-template new-task\n```\n\n### Security: Permission Prompts\n\nBy default, `claude.args` is empty, meaning Claude Code will prompt for permissions during execution. This is the **safe default**.\n\nTo enable autonomous iteration without interruptions:\n\n```bash\n# Per-project (recommended)\nclaude-iterate config claude.args --add --dangerously-skip-permissions\n\n# Globally (all projects)\nclaude-iterate config --global claude.args --add --dangerously-skip-permissions\n\n# Per-run only (not saved)\nclaude-iterate run my-task --dangerously-skip-permissions\n```\n\n⚠️ **WARNING:** The `--dangerously-skip-permissions` flag allows Claude to read/write files and execute commands without confirmation. Anthropic recommends using this \"only in a container without internet access.\" [Learn more](https://docs.anthropic.com/en/docs/agents/agent-security-model#disabling-permission-prompts)\n\n### Notifications\n\nSend HTTP POST notifications for long-running tasks (compatible with ntfy.sh):\n\n```bash\n# Configure during init\nclaude-iterate init my-task \\\n  --notify-url https://ntfy.sh/my-topic \\\n  --notify-events all\n\n# Or in config\nclaude-iterate config notifyUrl https://ntfy.sh/my-topic\n```\n\n**Available events:** `setup_complete`, `execution_start`, `iteration`, `iteration_milestone`, `completion`, `error`, `status_update`, `all`\n\n**Default events:** `all` (all event types)\n\n**Status Update Events:** The `status_update` event is triggered automatically when Claude updates the `.status.json` file during execution. This provides real-time progress notifications without polling. The watcher uses 2-second debouncing and filters out timestamp-only changes to prevent notification spam. Status updates include progress deltas (e.g., \"35/60 items (+5)\"), summary text, and completion status.\n\n## Viewing Claude Output\n\nClaude-iterate provides three output levels for console feedback, plus comprehensive log files:\n\n### Output Levels\n\n**Progress (Default)** - Shows iteration progress and completion status without full output:\n\n```bash\nclaude-iterate run my-task\n\n# Output:\n# Starting claude-iterate run for workspace: my-task\n# Mode: loop | Max iterations: 50 | Delay: 2s\n#\n# Running iteration 1...\n# ✓ Iteration 1 complete (4 items remaining)\n#\n# Running iteration 2...\n# ✓ Iteration 2 complete (3 items remaining)\n# ...\n# ✓ Task completed successfully after 5 iterations\n```\n\n**Verbose** - Shows full Claude output with real-time tool visibility:\n\n```bash\nclaude-iterate run my-task --verbose\n# or\nclaude-iterate run my-task --output verbose\n```\n\nVerbose mode displays Claude's tool usage as it happens:\n\n```bash\nRunning iteration 1...\n\n🔧 Using Read tool\n   File: /workspace/repo/TODO.md\n✓ File read successfully (45 lines)\n\n🔧 Using Edit tool\n   File: TODO.md\n   Replacing: \"- [ ] Task 1\"\n✓ Edit successful\n\n🔧 Using Write tool\n   File: /workspace/repo/.status.json\n✓ File created successfully\n\n📝 Claude's response:\n✅ Iteration 1 Complete\n\nI've successfully completed one task as instructed:\n\n**Changes made:**\n- ✓ Checked Task 1 in TODO.md\n- ✓ Updated .status.json\n\n✓ Iteration 1 complete (4 items remaining)\n```\n\n**Tool visibility features:**\n\n- 🔧 Tool name displayed (Read, Edit, Write, Bash, Grep, etc.)\n- 📄 File paths shown for file operations\n- 💻 Commands shown for Bash tool\n- 🔍 Patterns shown for Grep tool\n- ✓/❌ Success/error indicators for tool results\n- 📝 Claude's text responses and reasoning\n\nHelpful for:\n\n- Debugging issues - See which tool failed and why\n- Monitoring Claude's reasoning - Watch the step-by-step process\n- Understanding detailed progress - Know exactly what files are being modified\n- Building trust - Full transparency into Claude's actions\n\n**Quiet** - Silent execution, only errors/warnings:\n\n```bash\nclaude-iterate run my-task --quiet\n# or\nclaude-iterate run my-task --output quiet\n```\n\nIdeal for:\n\n- CI/CD pipelines\n- Background tasks\n- Minimal logging\n\nYou can also configure the default output level in your config:\n\n```json\n{\n  \"outputLevel\": \"progress\"\n}\n```\n\n### Log Files\n\nEvery run automatically creates a timestamped log file in the workspace directory:\n\n```bash\n# List all log files for a workspace (sorted by time)\nls -lt claude-iterate/workspaces/my-task/iterate-*.log\n\n# View the latest log file\nls -t claude-iterate/workspaces/my-task/iterate-*.log | head -1 | xargs cat\n\n# Search for specific content across all logs\ngrep \"error\" claude-iterate/workspaces/my-task/iterate-*.log\n```\n\n**Log file naming:** `iterate-YYYYMMDD-HHMMSS.log` (e.g., `iterate-20251015-142345.log`)\n\nEach log file contains:\n\n- Run metadata (workspace, mode, max iterations) - logged once\n- Instructions and system prompts - logged once at start for efficiency\n- Iteration timestamps and Claude output\n- Tool usage events (when running with --verbose)\n- Completion status and remaining counts\n\n**Note:** Log files use a deduplicated format that logs static content (instructions, system prompts) once at the start instead of repeating them for each iteration. This reduces log file size by ~60% while maintaining full auditability. Log files are created regardless of the output level. Tool events are logged when using verbose mode for better debugging and auditability.\n\n## Examples\n\n### Basic Workflow\n\n```bash\n# 1. Initialize workspace\nclaude-iterate init frontend-pages\n\n# 2. Create instructions interactively\nclaude-iterate setup frontend-pages\n\n# 3. Validate instructions\nclaude-iterate validate frontend-pages\n\n# 4. Run\nclaude-iterate run frontend-pages\n\n# 5. Verify completion\nclaude-iterate verify frontend-pages\n\n# 6. Save as template for reuse\nclaude-iterate template save frontend-pages\n```\n\n### Verification Workflow\n\n```bash\n# Run a task\nclaude-iterate run api-migration\n\n# Task claims completion - verify it's actually done\nclaude-iterate verify api-migration\n\n# If verification passes:\n# ✅ VERIFICATION PASSED\n\n# If verification fails:\n# ❌ VERIFICATION FAILED\n# Issues found: 5\n# Full report: claude-iterate/workspaces/api-migration/verification-report.md\n\n# Use different depth levels\nclaude-iterate verify api-migration --depth quick    # Fast check\nclaude-iterate verify api-migration --depth deep     # Thorough review\n\n# Get JSON output for automation\nclaude-iterate verify api-migration --json\n```\n\n### Using Templates\n\n```bash\n# Save workspace as template (defaults to workspace name)\nclaude-iterate template save frontend-pages\n\n# Save with custom name\nclaude-iterate template save frontend-pages page-generator\n\n# Update existing template\nclaude-iterate template save frontend-pages --force\n\n# Use existing template\nclaude-iterate template use page-generator user-service\n\n# Customize if needed\nclaude-iterate edit user-service\n\n# Run with custom settings\nclaude-iterate run user-service --max-iterations 100 --delay 5\n```\n\n### Iterative Mode for Large Tasks\n\n```bash\n# Initialize with iterative mode\nclaude-iterate init refactor-codebase --mode iterative\n\n# Set up instructions\nclaude-iterate setup refactor-codebase\n\n# Run - Claude completes as many items as possible per iteration\nclaude-iterate run refactor-codebase\n```\n\n### Monthly Reports\n\n```bash\n# Create global template once\nclaude-iterate init monthly-report\nclaude-iterate setup monthly-report\nclaude-iterate template save monthly-report monthly-report --global\n\n# Use each month\nclaude-iterate template use monthly-report report-january-2025\nclaude-iterate run report-january-2025\n```\n\n## Directory Structure\n\n```\n# Project\n./my-project/\n├── .claude-iterate.json       # Optional project config\n└── claude-iterate/\n    ├── workspaces/            # Active workspaces\n    │   └── my-task/\n    │       ├── INSTRUCTIONS.md\n    │       ├── TODO.md\n    │       ├── .status.json         # Machine-readable completion status\n    │       ├── .metadata.json\n    │       ├── iterate-20251015-142345.log  # Run logs (timestamped)\n    │       ├── iterate-20251015-153021.log\n    │       └── working/\n    ├── templates/             # Project templates\n    └── archive/               # Completed workspaces\n\n# User home\n~/.config/claude-iterate/\n├── config.json                # User defaults\n└── templates/                 # Shared templates\n```\n\n### Git Integration\n\nWorkspaces are **not** .gitignored for AI agent compatibility. Use the pre-commit hook to prevent accidental commits:\n\n```bash\n# Setup hook\ngit config core.hooksPath .githooks\n\n# Or copy manually\ncp .githooks/pre-commit .git/hooks/pre-commit\nchmod +x .git/hooks/pre-commit\n```\n\nThe hook blocks commits of `claude-iterate/workspaces/` and `scratch/` directories.\n\n## Documentation\n\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development guide\n- **[CHANGELOG.md](CHANGELOG.md)** - Version history\n- **[GitHub Issues](https://github.com/radleta/claude-iterate/issues)** - Report bugs or request features\n- **[GitHub Discussions](https://github.com/radleta/claude-iterate/discussions)** - Ask questions\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:\n\n- Development setup\n- Code quality guidelines\n- Testing requirements\n- Commit conventions\n- Pull request process\n\nQuick start for contributors:\n\n```bash\ngit clone https://github.com/radleta/claude-iterate.git\ncd claude-iterate\nnpm install\nnpm run build\nnpm test\nnpm run validate  # Run all checks\n```\n\n## License\n\n[MIT](LICENSE) © 2025 Richard Adleta\n\n## Acknowledgments\n\nBuilt with TypeScript, Commander.js, and Zod. Tested with Vitest (228 passing tests).\n\nRequires [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) by Anthropic.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradleta%2Fclaude-iterate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradleta%2Fclaude-iterate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradleta%2Fclaude-iterate/lists"}