A GitHub Action that hands a failed CI run to a coding agent, lets it inspect the repo and logs directly, commits the fix, and waits for CI again.

Quickstart · How It Works · Configuration · Languages · Agent Skill · Contributing

🤖 AI Agent? Load SKILL.md to install greencheck into any repo — step-by-step instructions your agent can execute directly.

Most CI failures are small — a missing semicolon, a type mismatch, a renamed import. You know the fix in seconds, but the context-switch costs minutes. greencheck eliminates that friction:

• Zero human intervention — push code, go back to what you were doing
• Agent-first investigation — the LLM gets the failed run, raw logs, and the repo immediately
• Safe by default — protected files like lockfiles and secrets can still be filtered before commit
• Self-correcting — if a fix introduces a regression, it automatically reverts
• Cost-controlled — hard limits on spend and runtime, with detailed cost reporting
• Helpful hints when available — log parsers for ESLint, TypeScript, Jest, Vitest, Pytest, Go, and Rust still provide extra signal

greencheck is not trying to be an AI developer. It's a surgical CI repair tool that fixes the obvious stuff so you don't have to.

greencheck watches failed GitHub Actions runs, downloads the logs, saves them into the workspace, and gives Claude Code or Codex immediate control to investigate, fix, verify, and wait for CI to run again.

It is designed for workflow_run-based remediation flows and includes:

• Multi-language log hints — ESLint, Biome, TypeScript, Jest, Vitest, Pytest, Go, and Rust
• Raw log handoff — failed workflow logs are saved under .greencheck/logs/ for the agent to inspect directly
• Regression detection — new failures after a fix trigger an automatic revert
• Reporting — PR comments, GitHub Actions job summaries, and Slack notifications
• Safety guardrails — cost limits, timeouts, protected files, stale-context detection
• Checkpoint/resume — long-running fix sessions survive re-runs

name: greencheck

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

permissions:
  actions: read
  contents: write
  issues: write
  pull-requests: write

jobs:
  fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
          token: ${{ secrets.GREENCHECK_TOKEN }}

      - uses: braedonsaunders/greencheck@v0
        with:
          agent: claude
          agent-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          trigger-token: ${{ secrets.GREENCHECK_TOKEN }}

For Claude Code with OAuth instead of an API key:

      - uses: braedonsaunders/greencheck@v0
        with:
          agent: claude
          agent-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          trigger-token: ${{ secrets.GREENCHECK_TOKEN }}

For Codex:

      - uses: braedonsaunders/greencheck@v0
        with:
          agent: codex
          agent-api-key: ${{ secrets.OPENAI_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          trigger-token: ${{ secrets.GREENCHECK_TOKEN }}

Note: Codex requires agent-api-key. OAuth-only Codex auth is not supported in this action.

A complete example workflow lives at examples/greencheck.workflow.yml.

CI fails → greencheck downloads logs and saves them into .greencheck/logs/
  → invokes Claude Code / Codex with the failed run context immediately
  → agent inspects logs, repo code, workflows, and runs its own verification
  → greencheck filters protected-file edits, commits safe changes
  → pushes → waits for CI → repeats if needed

1. A monitored workflow finishes with failure.
2. greencheck downloads the failed job logs, saves them locally, and optionally parses them into hints.
3. It invokes Claude Code or Codex right away with the workflow metadata, raw log path, and any parsed hints.
4. The agent investigates the failure itself, including running the repository's own tests, linting, or typechecks as needed.
5. It pushes the fix and waits for the next workflow run on that commit.
6. If new failures appear, it reverts the regressive commit and continues.
7. If the branch has advanced since the failed run, greencheck keeps going on the latest branch state while using the failed run logs as its debugging context.

Configure greencheck with a .greencheck.yml file in your repository root. Explicit action inputs always override repository config values.

watch:
  workflows: [CI, Lint]
  branches: [main, develop]
  ignore-authors: [dependabot]

fix:
  agent: claude
  model: claude-sonnet-4-20250514
  types: [lint, type-error, test-failure]
  max-passes: 5
  max-cost: "$3.00"
  timeout: 20m

merge:
  enabled: false
  max-commits: 3
  require-label: true
  protected-patterns: [main, master, develop, release/*]

report:
  pr-comment: true
  job-summary: true
  slack-webhook: https://hooks.slack.com/services/...

safety:
  never-touch-files: ["*.lock", "package-lock.json", ".env*"]
  max-files-per-fix: 10
  revert-on-regression: true

• Latest-branch recovery — if the branch moved past the failed commit, greencheck still proceeds using the latest branch state plus the failed run logs
• Protected file filtering — never modifies lockfiles, .env, or custom patterns
• Protected file filtering — discards agent changes to files matching protected patterns before commit
• Regression revert — automatically reverts commits that introduce new failures
• Cost and time limits — hard caps on spend and wall-clock time
• Auto-merge safety — requires PR approval, optional label gating, protected branch patterns

npm install
npm test          # vitest
npm run lint      # eslint
npm run typecheck # tsc --noEmit
npm run build     # ncc bundle → dist/

See CONTRIBUTING.md for details.

The branch advanced after the failed run greencheck now continues on the latest branch state and uses the failed run logs as context. If that newer branch already fixed the issue, the agent may decide no code change is needed.

"All changed files are protected, discarding changes" The agent tried to modify files matching your safety.never-touch-files patterns (e.g., lockfiles, .env). greencheck discards those changes. If the fix genuinely requires modifying a protected file, adjust the patterns in .greencheck.yml.

"Cost limit reached" greencheck hit the max-cost cap. Increase it in your workflow or .greencheck.yml, or narrow fix-types to reduce the number of fix attempts.

"Timed out waiting for CI" The CI pipeline took longer than the remaining time budget. Increase timeout or optimize your CI pipeline.

Agent installation fails greencheck auto-installs Claude Code or Codex via npm install -g. If this fails, pre-install the agent in a prior workflow step:

- run: npm install -g @anthropic-ai/claude-code@latest

No failures found in logs greencheck still hands control to the agent and saves the raw workflow logs under .greencheck/logs/. Parsers are only hints now. If the agent was missing useful structure, open an issue with the log snippet and we'll add support.

Using an AI coding agent to set up greencheck? SKILL.md is a procedural skill file that any LLM agent (Claude Code, Codex, Cursor, OpenCode, etc.) can load and execute step-by-step to install and configure greencheck in any repository. It includes trigger conditions, numbered steps, all inputs/outputs, and a pitfalls section.

MIT