claude-orchestrator

Claude Orchestrator

Control separate Claude Code sessions from this chat via playwright-cli. No API keys needed.

When Triggered

1. Check prerequisites: playwright-cli installed? Bash(playwright-cli:*) in permissions? If not, see references/setup.md.
2. Set up this (orchestrator) session:
   • Run /remote-control in this session.
   • Share the URL with the user: "Bookmark this URL — open it on your phone or another device to monitor what the orchestrator is doing and manually interrupt if needed."
3. Set up the worker session. Ask the user:
   • Worker URL: "Open a new terminal, cd to your project, run claude --dangerously-skip-permissions, then /remote-control, and paste the URL here."
   • Goal: "What should the worker do? (e.g. improve this project's UI, research X, refactor Y)"
   • For critic/creator: ask for a second worker URL.
4. Open the worker URL, snapshot once to find coordinates, then begin the loop.

Two-Session Minimum (CRITICAL)

This session = orchestrator. Reads responses, decides follow-ups, sends via playwright-cli. A separate session = worker. Receives prompts, does the actual work.

Never use your own session's remote control URL — you'll talk to yourself.

How It Works

1. Open worker session: playwright-cli open --headed --browser=chrome --profile="<chrome-profile-path>" "<worker-url>"
2. Snapshot once to find input and send button coordinates (reuse for all iterations)
3. Send message: click input → type → click send button (not Enter — it inserts newline)
4. Poll with playwright-cli snapshot — check button state: Interrupt visible = still working, Submit [disabled] = idle. Adjust poll interval by task complexity: quick search → 20-30s, moderate edits → 45-60s, large rewrites → 90-120s.
5. Confirm completion: Once button shows idle, wait 5s and snapshot once more. If content differs from previous snapshot, the page is still loading — wait and retry. If identical, safe to read.
6. Read response from the snapshot. If worker asks a question, answer it. Otherwise decide next prompt. Optional for code tasks in git repos: run git diff to verify what actually changed — useful as a fallback when the snapshot lags.
7. Loop back to step 3 with the next focused prompt. Or stop.

Chrome profile path: Windows C:\Users\<USER>\AppData\Local\Google\Chrome\User Data\Default · macOS ~/Library/Application Support/Google/Chrome/Default · Linux ~/.config/google-chrome/Default

Permissions

The worker terminal stays open — user approves permissions there as needed. The orchestrator just polls until done.

For full autonomy (recommended): Start the worker with claude --dangerously-skip-permissions so it auto-approves all tool calls. This grants unrestricted file/command access in the project directory.

For manual control, start with claude instead — you'll approve each permission in the worker terminal.

Design Principle: One Small Prompt Per Iteration

• Iteration 1: "Explore the project. List what you see."
• Iteration 2: "Top 3 improvements for [goal]?"
• Iteration 3: "Implement #1: [X]"
• Iteration 4: "Implement #2: [Y]"
• Iteration 5: "Review changes. What still needs work?"

Prefer small prompts for iterative work. Compound prompts are fine when the worker needs full context (e.g. creative tasks).

Patterns

See references/patterns.md for: single injection, self-feedback loop, critic/creator, human-checkpoint.

Troubleshooting

See references/troubleshooting.md.