groundkeeper

A deterministic, YAML-driven repository maintenance agent that runs as a GitHub Action. Safe, reviewable, and boring: every change is structured, validated, and generated under strict budgets and scope rules.

Quick Start (GitHub Action)

1. Create .github/agent.yml in your repository:

$schema: https://raw.githubusercontent.com/efremidze/groundkeeper/main/packages/schemas/agent.schema.json
version: '1.0'
mode: report-only

scope:
  include:
    - src/**
    - docs/**
    - README.md
  exclude:
    - node_modules/**
    - dist/**
    - .git/**

budgets:
  maxFiles: 100
  maxDiffLines: 800
  maxTokens: 10000

rules:
  allow:
    - documentation
    - formatting
  deny:
    - dependency-upgrades

runtime:
  provider: openai

publish:
  enabled: false

2. Create .github/workflows/groundkeeper.yml:

name: Repository Maintenance

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  workflow_dispatch:

jobs:
  groundkeeper:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Groundkeeper
        uses: efremidze/groundkeeper@v1
        with:
          config: .github/agent.yml
          github-token: ${{ secrets.GITHUB_TOKEN }}

3. Done! Groundkeeper will run on schedule or when manually triggered. Reports are saved to .groundkeeper/report.md.

Configuration

The .github/agent.yml file defines how Groundkeeper analyzes your repository.

Configuration Schema

version: '1.0'                 # Configuration version

mode: report-only              # Safety mode (always report-only in v1)

scope:
  include: [string]            # Paths to analyze (glob patterns)
  exclude: [string]            # Paths to skip

budgets:
  maxFiles: number             # Max files to analyze
  maxDiffLines: number         # Max diff lines in patches
  maxTokens: number            # Max LLM tokens per stage

rules:
  allow: [string]              # Allowed change types
  deny: [string]               # Denied change types

runtime:
  provider: openai | copilot   # LLM provider

publish:
  enabled: boolean             # Create PR/issue with findings (opt-in)
  target: pr | issue           # Publish target

Stages

Groundkeeper executes a deterministic pipeline:

| Stage | Description | LLM | |-------|-------------|-----| | Preflight | Validate repo and scope | No | | Analysis | Identify maintenance items | Yes | | Plan | Create action plan | Yes | | Patch | Generate diffs (report-only) | Yes | | Verify | Run checks and validate | Yes | | Publish | Generate PR/issue content | Yes |

Safety & Design

• YAML is the spec — .github/agent.yml defines all behavior
• Report-only by default — no changes without explicit publish.enabled: true
• Deterministic output — same config + repo = same results
• Hard budgets — scoped execution before LLM calls
• Structured validation — all LLM outputs validated against schemas
• No auto-merge — all PRs require manual review

CLI Usage (Local Testing)

For local development or testing:

# Install locally
npm install -g groundkeeper

# Run against your repository
groundkeeper run --config .github/agent.yml

# Check the report
cat .groundkeeper/report.md

CLI Commands

groundkeeper run [options]

Options:
  -c, --config <path>      Path to agent.yml (default: .github/agent.yml)
  -d, --directory <path>   Working directory (default: current directory)

Examples

Minimal Configuration (Report Only)

version: '1.0'
mode: report-only

scope:
  include: ['**']
  exclude: ['node_modules/**', 'dist/**']

budgets:
  maxFiles: 50
  maxDiffLines: 500
  maxTokens: 5000

runtime:
  provider: openai

publish:
  enabled: false

Advanced Configuration

version: '1.0'
mode: report-only

scope:
  include:
    - src/**
    - tests/**
    - docs/**
    - README.md
    - package.json
  exclude:
    - node_modules/**
    - dist/**
    - coverage/**
    - .git/**

budgets:
  maxFiles: 100
  maxDiffLines: 1000
  maxTokens: 15000

rules:
  allow:
    - documentation
    - formatting
    - tests
  deny:
    - breaking-changes
    - dependency-upgrades

runtime:
  provider: openai
  # Optional: copilot for GitHub Copilot SDK

publish:
  enabled: false  # Set to true to enable PR creation
  target: pr      # or 'issue'

Inputs & Outputs

GitHub Action Inputs

| Input | Description | Required | Default | |-------|-------------|----------|---------| | config | Path to .github/agent.yml | No | .github/agent.yml | | github-token | GitHub API token | No | ${{ github.token }} | | working-directory | Working directory for the action | No | . |

Outputs

| Output | Description | |--------|-------------| | report-path | Path to generated report (e.g., .groundkeeper/report.md) |

Generated Files

After running, Groundkeeper creates:

• .groundkeeper/report.md — Human-readable analysis report
• .groundkeeper/analysis.json — Structured analysis results
• .groundkeeper/plan.json — Proposed changes plan
• .groundkeeper/patch.json — Generated patches (report-only mode)

For Contributors & Maintainers

See CONTRIBUTING.md for development setup, architecture overview, and internal design principles.

License

MIT License - see LICENSE file for details.

Author

Lasha Efremidze

Note: Groundkeeper is designed to be safe and non-intrusive. It won't make changes to your repository without explicit permission.