Cline

Run cline auth interactively (needs a TTY/PTY), or use flags:

cline auth -p <provider> -k <api_key> -m <model_id>

v2.8.0 quirk: Even with flags, auth launches a TUI. Run in the background with a long timeout (20-25s) — it writes config before exiting on SIGTERM. Config is saved to ~/.cline/data/globalState.json and ~/.cline/data/secrets.json.

One-Shot Tasks (Headless)

cd /path/to/project
cline -y "Add error handling to all API calls in src/"

-y / --yolo = auto-approve all file changes, forces headless mode.

With Timeout (CI/CD)

cline -y --timeout 300 "Run tests and fix any failures"

Piped Input

git diff origin/main | cline -y "Review these changes for bugs and security issues"
npm test 2>&1 | cline -y "Fix failing tests"

JSON Output (for scripting)

cline --json "List all TODO comments" | jq '.text'

Custom Model

cline -y -m anthropic/claude-sonnet-4-5 "Refactor auth module to use JWT"

Parallel Workstreams

(cd /tmp/branch-a && cline -y "Fix login bug") &
(cd /tmp/branch-b && cline -y "Add unit tests for auth") &
wait

Planning Subagent + Cline Pattern

For complex multi-task implementations, don't send vague instructions to Cline. Use a two-step pattern:

1. Plan first — dispatch a delegate_task subagent with full codebase context to read the relevant files, understand the structure, and write a detailed plan doc (exact file paths, line numbers, complete code snippets) to e.g. docs/plans/YYYY-MM-DD-feature.md.

2. Implement with Cline — hand the plan file to Cline:

   cline -y --timeout 600 -m anthropic/claude-sonnet-4-5 \
     "Implement the plan in docs/plans/2026-04-03-feature.md exactly as written. Read the plan first, then read each source file before editing it."
   

   Optionally add --double-check-completion to force Cline to re-verify its work before marking done. Adds time, reduces the need for a first-pass audit.

This pattern works because:

• The subagent reads the actual code and generates grounded, correct code snippets
• Cline gets precise instructions and doesn't have to infer structure
• The plan doc is a reviewable artefact before a line of code is written

When to use: Any implementation involving 3+ files, or where field names / API shapes need to be verified before writing code.

Opus Review + Cline Fix Cycle

For features spanning many files, Cline first passes routinely miss steps — even with a detailed plan. Observed: 5 of 13 planned steps skipped on a leaderboard feature (UI, tests, runner loop all absent). The reliable pattern is:

1. Cline implements — fire with a detailed prompt, set a cron review job for 15-20 min
2. Opus reviews — spawn delegate_task with max_iterations=40, ask it to read every changed file against the plan and produce a prioritised list: bugs, missing steps, integration gaps, test gaps. Specify exact files and what to check.
3. Targeted second Cline pass — write a new prompt referencing specific findings by file:function:line. Include exact replacement code for bugs, not just descriptions. This pass is faster and cleaner than the first because the problem space is fully defined.
4. Repeat if needed — a second opus review after the fix pass usually comes back clean.

Key differences from the first pass prompt:

• List each fix as a numbered section with file path in the heading
• For bugs: include the exact broken code and the exact replacement
• For missing implementations: paste in the complete code, not a description of it
• End with "Run tests and commit if they pass"

Observed outcome: Two-pass cycle (Cline → Opus review → Cline) consistently produces cleaner results than one long prompt, because the review grounds the second prompt in reality rather than the plan.

File Conflict Rule

If all tasks in a phase touch the same file — use ONE Cline agent for the whole phase.

The parallel workstream pattern only works when tasks are on different files. When a code review or plan surfaces N tasks that all modify dashboard.html (or any single file), combine them into one agent prompt rather than trying to parallelize. Sequential tasks in a single session preserve the file state correctly.

Quick decision:

• Tasks on different files → parallel agents, one per file group
• Tasks on same file → one agent, all tasks in one prompt

Exception: Kanban. When using cline kanban, each task runs in its own git worktree. Parallel agents can't clobber each other because they're working in separate checkpoints. The one-agent-per-file constraint does not apply when using Kanban.

Single-File Rule

One agent per file, always — unless using Kanban (worktrees handle isolation natively). If multiple tasks touch the same file and you're using raw CLI, combine them into one agent prompt. Two agents editing the same file concurrently will clobber each other — the second write overwrites the first, silently. Group tasks by file before dispatching.

Parallel Bug-Fix Pattern (Multi-Agent from Code Review)

When a code review surfaces N independent issues, dispatch one Cline agent per issue as background processes. Critical rule: split work so no two agents touch the same file. If two agents edit the same file concurrently, the second write overwrites the first.

Workflow:

1. Group issues by the files they require editing
2. Combine any issues that share files into a single agent task
3. Dispatch agents in sequence (small stagger), redirect each to its own log
4. Schedule a cron job to review all results after a fixed delay

cd /path/to/your/project

# Agent 1: touches only dice.py
cline -y --timeout 300 "Fix scatter logic in app/game/dice.py: ..." \
  > /tmp/fix_scatter.log 2>&1 &
echo "Agent 1 pid $!"

# Agent 2: touches only combat.py
cline -y --timeout 300 "Implement assists in app/game/combat.py: ..." \
  > /tmp/fix_assists.log 2>&1 &
echo "Agent 2 pid $!"

# Agent 3: touches only action_executor.py
cline -y --timeout 300 "Implement push in app/state/action_executor.py: ..." \
  > /tmp/fix_push.log 2>&1 &
echo "Agent 3 pid $!"

Then schedule a single cron job (deliver: origin) to fire after enough time for all agents to finish. The cron task reads each log, runs the full test suite, and reports pass/fail per agent plus any issues needing manual attention.

# In the cron prompt, check each log and run tests:
# - cat /tmp/fix_scatter.log | tail -30
# - cd /path/to/your/project && uv run pytest tests/ -q | tail -20

Multi-Pass Implementation with Opus Audit

For larger features (5+ files), a single Cline pass frequently skips steps or times out silently. Realistically expect three passes for anything complex:

1. Plan — delegate_task subagent reads codebase, writes docs/plans/YYYY-MM-DD-feature.md with exact file paths, line numbers, and complete code snippets.

2. First Cline pass — implement the plan with a tight, specific prompt.

3. Opus audit — run as a direct delegate_task (not a cron) when actively working — faster feedback. Use a cron (deliver: origin) if you're stepping away. The subagent reads every new/modified file and produces a prioritised findings report: bugs, missing steps, integration gaps, test coverage. Give it the plan file path and the specific integration points to check.

4. Second Cline pass — targeted fix prompt. Provide exact code for each fix, not just descriptions. Cline is significantly more accurate when the prompt says "add this exact block after line X" vs "fix the timeout handling". List each issue as a numbered heading with the precise code to insert.

5. Second Opus audit + third Cline pass if needed — for a feature with multiple review cycles, the second audit is usually much cleaner. If only a handful of issues remain (missing tests, minor edge cases), fix them directly rather than firing another Cline pass.

Observed failure modes on first pass:

• Steps silently skipped (5 of 13 in one case) with no error in the log
• --timeout 600 hit mid-task, leaving the last file untouched (0-byte test file)
• Frontend JS wiring (calling new function from existing function) frequently missed
• Pydantic v2 issues: @property not serialized (needs @computed_field), datetime.utcnow() deprecated
• Score/state fields not cleared in reset methods, causing data bleed across sessions
• In-memory guard (set.add()) placed before the disk write it protects — silent data loss on failure

Audit prompt shape that works well: