Cline Automation Examples

This directory contains example automation specs for file-based and event-driven automation in Cline. Use these as templates to set up your own recurring or event-driven tasks.

🚀 Quick Start: Pick Your Automation

📋 Overview

Cline automation supports two types of specs:

1. Recurring specs (.cron.md) — Run on a schedule
2. Event-driven specs (.event.md) — Run when an event occurs

Both can be enabled in .cline/cron/ to be picked up by the hub or SDK.

🔄 Recurring Specs

daily-code-review.cron.md

A production-ready example that runs a code review automation on weekday mornings.

Key fields:

• schedule: "0 9 * * MON-FRI" — 9 AM on weekdays (cron format)
• tools: run_commands,read_files — Restrict tools to specific actions
• mode: act — Execute commands (vs. plan or yolo)
• timeoutSeconds: 1800 — 30-minute timeout
• modelSelection — Override model/provider for this run
• notesDirectory — Durable automation notes for multi-run state

Usage:

mkdir -p ~/.cline/cron
cp examples/cron/daily-code-review.cron.md ~/.cline/cron/
# Edit the spec: set workspaceRoot, model, etc.
# Spec is reconciled on startup; next run enqueued automatically

One-off specs: For one-time tasks, save as .cline/cron/<name>.md (no .cron infix) and omit the schedule field.

Additional Recurring Spec Examples

changelog-generator.cron.md

Auto-generate changelog from recent commits

Runs every Friday at 6 PM. Reviews commits in a directory (e.g., apps/cli/) and generates a changelog entry summarizing new features, bug fixes, and breaking changes. Updates CHANGELOG.md without bumping the version.

Best for: Projects with frequent releases and manual changelog maintenance overhead.

dependency-check.cron.md

Weekly dependency health check

Runs every Monday at 10 AM. Checks for outdated packages, security vulnerabilities, unused dependencies, and major version upgrades. Generates a prioritized report for action.

Best for: Teams that want proactive dependency maintenance without daily alerts.

test-coverage-report.cron.md

Daily test coverage metrics

Runs every day at 10 PM. Runs the full test suite, generates coverage reports, and identifies files needing more tests. Creates a markdown summary with visual indicators.

Best for: Maintaining code quality standards and tracking coverage trends over time.

performance-baseline.cron.md

Track performance metrics overnight

Runs daily at 2 AM. Measures build time, bundle size, and cold start performance. Detects regressions and alerts if metrics exceed thresholds.

Best for: CLI tools, libraries, or services where performance is critical.

type-check-strict.cron.md

Strict TypeScript type checking

Runs every morning at 6 AM in plan mode. Reports all type errors with strict compiler options and categorizes them by issue type.

Best for: Gradually improving type safety without blocking development.

code-style-audit.cron.md

Code style and linting audit

Runs every Wednesday at 3 AM. Runs ESLint and Prettier, identifies unused code, detects anti-patterns, and provides a summary of violations.

Best for: Maintaining code consistency across a team.

dead-code-finder.cron.md

Find and report dead code

Runs every Sunday at 4 AM in plan mode. Identifies unused exports, unreachable code, and deprecated patterns. Prioritizes safe removals vs. ones requiring review.

Best for: Regular codebase cleanup and reducing technical debt.

documentation-check.cron.md

Documentation coverage audit

Runs every Thursday at 5 AM in plan mode. Analyzes documentation completeness, identifies missing JSDoc comments, checks for outdated docs, and evaluates overall documentation structure.

Best for: Improving code maintainability and onboarding of new team members.

weekly-metrics-summary.cron.md

Fun weekly metrics summary for the team 🎉

Runs every Friday at 5 PM. Collects a week's worth of data: commits, test coverage, performance, PR activity, and contributor stats. Generates a celebratory markdown report with emojis, top contributors, metrics trends, and fun facts.

Best for: Team morale, tracking velocity, and celebrating wins. Great for Friday morning stand-ups or team channels.

🎯 Event-Driven Specs

Event-driven specs live in .cline/cron/events/ and trigger when normalized events are ingested.

events/pr-review.event.md

Runs a pull request review whenever a new PR opens on the main branch.

Key fields:

• event: github.pull_request.opened — Trigger on this event type
• filters — Narrow scope: match repository, branch, labels, etc.
• debounceSeconds: 30 — Wait 30s for more events before triggering
• dedupeWindowSeconds: 600 — Ignore duplicate events within 10 minutes
• cooldownSeconds: 120 — Wait 2 minutes after a run before next trigger
• maxParallel: 2 — Run at most 2 in parallel

Usage:

mkdir -p ~/.cline/cron/events
cp examples/cron/events/pr-review.event.md ~/.cline/cron/events/
# Configure your repository, branch, and workspace
# Wire up GitHub App or webhook to ingest events

Ingesting events: Events are ingested via:

• GitHub App or webhook receiver
• Plugin-emitted events (see plugins/automation-events.ts)
• Connector adapters
• cline.automation.ingestEvent() in the SDK

events/local-manual-test.event.md

Local test spec for verifying event-driven automation without external services.

Key fields:

• event: local.manual_test — Local event type (no external dependency)
• filters: { topic: cron-feature-2 } — Match on event payload fields
• debounceSeconds: 0 — Trigger immediately
• maxIterations: 5 — Quick timeout for testing

Usage:

mkdir -p ~/.cline/cron/events
cp examples/cron/events/local-manual-test.event.md ~/.cline/cron/events/

# Start the hub with automation enabled
# In another shell, ingest a test event
node -e "
  const { HubWebSocketClient } = require('@cline/core');
  const client = new HubWebSocketClient('ws://localhost:8000');
  client.send('cron.event.ingest', {
    eventType: 'local.manual_test',
    envelope: { subject: 'test', topic: 'cron-feature-2', message: 'hello' }
  });
"

events/local-plugin-event.event.md

Test spec for plugin-emitted events. Pairs with plugins/automation-events.ts.

Additional Event-Driven Examples

events/pr-changelog-check.event.md

Verify CHANGELOG updates in PRs

Triggers when a PR opens on main. If the PR modifies source code but doesn't update CHANGELOG, posts a comment suggesting what should be added. If CHANGELOG is updated, verifies the format.

Best for: Maintaining an up-to-date changelog without manual reminders. Reduces reviewer burden.

events/pr-test-coverage.event.md

Analyze test coverage impact of PRs

Triggers when a PR is opened or updated. Runs test coverage against the PR branch, compares to main, and posts a comment showing:

• Which new code is covered vs. uncovered
• Coverage impact percentage
• Files with decreased coverage
• Recommendations for additional tests

Best for: Maintaining test coverage standards while being helpful rather than blocking. Guides authors toward better test practices.

Key fields:

• event: local.plugin_event — Custom event emitted by the plugin
• filters: { topic: plugin-demo } — Match on plugin event attributes
• Minimal throttling for responsive testing

Usage:

mkdir -p ~/.cline/cron/events
cp examples/cron/events/local-plugin-event.event.md ~/.cline/cron/events/

# Load the plugin that emits these events
mkdir -p ~/.cline/plugins
cp examples/plugins/automation-events.ts ~/.cline/plugins/

# Run CLI with automation enabled; the plugin emits events
cline --enable-automation -i "Test automation events"

🚀 Getting Started

1. Set up the spec directory

mkdir -p ~/.cline/cron/events

2. Copy a template

• For scheduled tasks: Copy daily-code-review.cron.md
• For GitHub events: Copy pr-review.event.md
• For local testing: Copy local-manual-test.event.md
• For plugin events: Copy local-plugin-event.event.md

3. Customize the spec

Edit your copied spec:

• Set workspaceRoot to your project path
• Set modelSelection if using a non-default model
• Update filters to match your repos/branches
• Adjust timeout, iterations, and tool restrictions
• Refine the prompt (the YAML body)

4. Enable automation

In the hub:

new HubWebSocketServer({
  cronOptions: { workspaceRoot: "/absolute/workspace" }
});

In the SDK:

const cline = await ClineCore.create({
  automation: true,  // Enable automation
  // ... other options
});

In the CLI:

cline --enable-automation

5. Monitor runs

Completed and failed runs are reported to .cline/cron/reports/<run-id>.md with:

• YAML frontmatter (run ID, status, timing, token usage)
• Summary of work performed
• Tool calls and results
• For events: trigger event context

📖 Field Reference

Common fields

Recurring-only fields (.cron.md)

Event-only fields (.event.md)

📚 Tools Reference

Available tool names:

• read_files — Read file contents
• search_codebase — Search across the project
• run_commands — Execute shell commands
• fetch_web_content — Fetch URLs
• apply_patch — Apply code patches
• editor — Edit files
• skills — Call custom skills
• ask_question — Query the user
• submit_and_exit — Complete the run

💡 Practical Automation Workflows

Complete Development Automation Suite

Combine multiple specs for comprehensive automation:

Monday 10 AM    → dependency-check.cron.md       (Check dependencies)
Tuesday 3 AM    → code-style-audit.cron.md       (Lint and format)
Wednesday 5 AM  → documentation-check.cron.md    (Doc coverage)
Thursday 4 AM   → dead-code-finder.cron.md       (Find cleanup opportunities)
Friday 6 PM     → changelog-generator.cron.md    (Auto-generate changelog)
Daily 2 AM      → performance-baseline.cron.md   (Track metrics)
Daily 10 PM     → test-coverage-report.cron.md   (Coverage trends)
Daily 6 AM      → type-check-strict.cron.md      (Type safety)

On every PR:
  → pr-changelog-check.event.md     (Verify CHANGELOG)
  → pr-test-coverage.event.md       (Coverage impact)

This provides continuous quality monitoring without developers having to remember to run checks manually.

Team Workflows by Role

For Team Leads:

• dependency-check.cron.md — Weekly security review
• dead-code-finder.cron.md — Quarterly cleanup planning
• performance-baseline.cron.md — Monitor system health

For QA Engineers:

• test-coverage-report.cron.md — Track trends
• pr-test-coverage.event.md — PR-level feedback

For Backend Teams:

• performance-baseline.cron.md — Build time, API response time
• type-check-strict.cron.md — Type safety

For Frontend Teams:

• performance-baseline.cron.md — Bundle size, cold start
• code-style-audit.cron.md — Consistent styling

🔍 Examples in Action

Schedule a daily security audit

---
id: daily-security-audit
title: Daily Security Audit
workspaceRoot: /path/to/repo
schedule: "0 2 * * *"  # 2 AM daily
tools: read_files,search_codebase
mode: act
timeoutSeconds: 3600
extensions:
  - skills
---
Search for hardcoded secrets, outdated dependencies, and insecure patterns.
Report findings to the team.

Review all new PRs on main

---
id: pr-security-review
title: Security Review for PRs
workspaceRoot: /path/to/repo
event: github.pull_request.opened
filters:
  pullRequest:
    baseBranch: main
cooldownSeconds: 300
maxParallel: 3
---
Summarize the changes, check for security risks, and recommend approval or changes.

🔗 See Also

• Architecture automation overview — Runtime architecture and flow details
• plugins/automation-events.ts — Plugin event emission
• Cline SDK Examples — Other integration examples