{"id":50588197,"url":"https://github.com/vitalivu992/claude-code-manager-scripts","last_synced_at":"2026-06-05T08:01:37.624Z","repository":{"id":359830863,"uuid":"1185962407","full_name":"vitalivu992/claude-code-manager-scripts","owner":"vitalivu992","description":"Get tired of babysitting your Claude code terminal? Try this simple workflow","archived":false,"fork":false,"pushed_at":"2026-05-23T16:21:51.000Z","size":230,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-23T18:15:07.309Z","etag":null,"topics":["claude-code"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vitalivu992.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-19T05:45:43.000Z","updated_at":"2026-05-23T16:21:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vitalivu992/claude-code-manager-scripts","commit_stats":null,"previous_names":["vitalivu992/claude-code-manager-scripts"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vitalivu992/claude-code-manager-scripts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalivu992%2Fclaude-code-manager-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalivu992%2Fclaude-code-manager-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalivu992%2Fclaude-code-manager-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalivu992%2Fclaude-code-manager-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vitalivu992","download_url":"https://codeload.github.com/vitalivu992/claude-code-manager-scripts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitalivu992%2Fclaude-code-manager-scripts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33935514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"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":"2026-06-05T08:01:36.807Z","updated_at":"2026-06-05T08:01:37.617Z","avatar_url":"https://github.com/vitalivu992.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-code-manager-scripts\n\nA multi-agent AI coding workflow that autonomously plans, implements, reviews, and commits code using Claude Code. Four specialized agents — **PLANNER**, **EXECUTOR**, **REVIEWER**, and **JANITOR** — coordinate through tmux sessions and a shared state machine.\n\n## How It Works\n\n```\nPLANNER ──planner:done──\u003e EXECUTOR ──executor:done──\u003e REVIEWER\n                              ^                            │\n                              │        reviewer:gaps       │\n                              └────────────────────────────┤\n                                                           │ reviewer:approved\n                                                       JANITOR\n                                                   (commit + push)\n```\n\n| Role | Responsibility |\n|------|---------------|\n| **PLANNER** | Reads requirements and produces an implementation plan |\n| **EXECUTOR** | Implements the plan; loops back if the REVIEWER finds gaps |\n| **REVIEWER** | Audits the implementation; either approves or documents gaps |\n| **JANITOR** | Commits, pushes, and tears down all workflow sessions |\n\nEach role runs in its own tmux session. A directory-based mutex (`.lockdir`) ensures only one role executes at a time. All coordination state lives in `~/.claude-auto-code/`.\n\n## Prerequisites\n\n- **tmux** — session management (`apt install tmux`)\n- **git** — version control (`apt install git`)\n- **realpath** — path resolution (`apt install coreutils`)\n- **yq** — YAML parser for config.yaml (`brew install yq` / `snap install yq` / [github.com/mikefarah/yq](https://github.com/mikefarah/yq))\n- **claude** — [Claude Code CLI](https://claude.ai/code)\n\nVerify everything is in place:\n\n```bash\nmake check\n```\n\n## Installation\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/vitalivu992/claude-code-manager-scripts.git ~/claude-code-manager-scripts\ncd ~/claude-code-manager-scripts\n\n# 2. Check dependencies\nmake check\n\n# 3. Create data directory and default config\nmake configure\n\n# 4. Install the CLI (symlinks to ~/.local/bin)\nmake install\n```\n\nMake sure `~/.local/bin` is on your `$PATH`. If not, add this to your shell profile:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n## Quick Start\n\n```bash\ncd /path/to/your/repo\n\n# Optional: set a specific goal\nclaude-code-manager plan \"Add user authentication with OAuth\"\n\n# Run the full autonomous workflow\nclaude-code-manager run\n```\n\nThe workflow runs until the JANITOR commits and pushes, then exits cleanly.\n\n## CLI Reference\n\n```\nclaude-code-manager \u003ccommand\u003e [args]\n```\n\n| Command | Description |\n|---------|-------------|\n| `plan \"\u003crequirement\u003e\"` | Set requirements for the next PLANNER run |\n| `run [--once]` | Run the workflow loop; `--once` executes a single tick |\n| `retry [--once]` | Resume from current state after a failure |\n| `status` | Show current state, metadata, and active sessions |\n| `stop` | Kill all sessions and clear state |\n| `help` | Show help |\n\n### Examples\n\n```bash\n# Start with a specific feature request\nclaude-code-manager plan \"Refactor database layer to use repository pattern\"\nclaude-code-manager run\n\n# Check what's happening\nclaude-code-manager status\n\n# Something went wrong — resume\nclaude-code-manager retry\n\n# Emergency stop\nclaude-code-manager stop\n```\n\n## Configuration\n\n`make configure` creates `~/.claude-code-manager/config.yaml`:\n\n```yaml\nroles:\n  planner:\n    commands:\n      - claude\n  executor:\n    commands:\n      - claude\n      - claude-opus          # randomly selected on each session creation\n    idle_threshold: 2\n    max_restarts: 3\n  reviewer:\n    commands:\n      - claude\n  janitor:\n    commands:\n      - claude\n\ngit:\n  command: git\n  push: true                 # set to false to skip git push after commit\n\ninterval: 30                 # polling interval in seconds (default: 30)\n```\n\nEach role's `commands` list is sampled uniformly at random every time a new tmux session is created for that role. A single-item list always selects that one command. This enables load balancing across models or API keys.\n\nSet `git.push: false` to skip the `git push` step after committing — useful when you want to review changes before pushing or use a CI pipeline instead.\n\n## Monitoring Sessions\n\nAttach to any running role session at any time:\n\n```bash\ntmux attach -t \u003cbase-name\u003e-PLANNER\ntmux attach -t \u003cbase-name\u003e-EXECUTOR\ntmux attach -t \u003cbase-name\u003e-REVIEWER\ntmux attach -t \u003cbase-name\u003e-JANITOR\n```\n\nThe `\u003cbase-name\u003e` is derived from your repo path: e.g. `/home/you/myproject` → `home-you-myproject`.\n\nList all active sessions:\n\n```bash\ntmux ls\n```\n\n## Recovering from Failures\n\nIf a session crashes or the workflow gets stuck, use `retry` to resume:\n\n```bash\nclaude-code-manager retry        # rolls back one state, restarts loop\nclaude-code-manager retry --once # single tick, useful for debugging\n```\n\n`retry` kills any stale sessions and backs the state machine up one step before re-running.\n\n## Using with Cron (Advanced)\n\nFor unattended operation, add a single entry to crontab:\n\n```cron\n*/5 * * * * cd /path/to/your/repo \u0026\u0026 claude-code-manager run --once\n```\n\n`--once` runs a single workflow tick per cron invocation. The `.lockdir` mutex ensures only one execution runs at a time even if cron fires while a previous tick is still active.\n\n\n## State Machine Reference\n\n| State | Active Role | What Happens |\n|-------|-------------|--------------|\n| _(empty)_ | PLANNER | Starts planning |\n| `planner:active` | PLANNER | Waits for plan completion |\n| `planner:done` | EXECUTOR | Starts implementation |\n| `executor:active` | EXECUTOR | Waits for `READY_FOR_REVIEW` |\n| `executor:done` | REVIEWER | Starts review |\n| `reviewer:active` | REVIEWER | Waits for approval or gaps |\n| `reviewer:approved` | JANITOR | Starts commit |\n| `reviewer:gaps` | EXECUTOR | Starts gap-fix iteration |\n| `janitor:commit` | JANITOR | Waits for commit, then pushes |\n| `janitor:push` | JANITOR | Waits for push, then cleans up |\n\n## Testing\n\n```bash\nmake test\n```\n\nRuns three suites: state/metadata unit tests, role guard tests, and end-to-end retry tests.\n\nState and metadata files at runtime (`~/.claude-auto-code/`):\n\n| File | Purpose |\n|------|---------|\n| `\u003cbase\u003e.lockdir/pid` | Directory-based mutex — prevents concurrent role execution |\n| `\u003cbase\u003e.state` | Current workflow state |\n| `\u003cbase\u003e.meta` | Key-value metadata (`plan_path`, `gaps_path`, `review_iteration`, …) |\n| `\u003cbase\u003e.PLANNER.mail` | Requirement text consumed on first PLANNER run |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitalivu992%2Fclaude-code-manager-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitalivu992%2Fclaude-code-manager-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitalivu992%2Fclaude-code-manager-scripts/lists"}