agent-deck

Groundskeeper

Autonomous agent shell around OMP workers and Espalier Core.

Groundskeeper is the durable backend for a fleet of autonomous coding agents. It owns the long-lived substrate an agent fleet needs to run unattended — agent threads, scheduled jobs, an approvals inbox, an audit log of every external action, a worker pool, and a runtime-neutral adapter for spawning agent processes. OMP workers do the coding; Groundskeeper owns everything around them that has to survive a crash.

What Groundskeeper owns

• Durable task/job ledger — agent threads, recurring jobs, dead-letter queue, persisted in SQLite (WAL).
• Scheduler and recurrence — loop specs with max-turns / max-wall-minutes / max-cost caps.
• Approvals inbox — risk-gated human approval before external actions.
• Audit log — every external action recorded, with redaction at the trust boundary.
• Worker pool — per-thread serialization, crash recovery (stuck-running requeued on startup).
• OMP RPC adapter — spawns OMP workers via omp --mode rpc over stdio (roadmap).
• Channel gateway — notifications to email/calendar/Slack sidecars (roadmap).

What Groundskeeper does not own

• Provider login — delegated to OMP/Pi.
• Model registry — delegated to OMP/Pi.
• Coding tool runtime — delegated to OMP/Pi.
• Pi/OMP session loop — OMP runs the agent; Groundskeeper manages the lifecycle around it.
• Espalier learning ledger / learned routines / jj+eval gates — Espalier Core is loaded into OMP sessions as an extension; Groundskeeper never imports Espalier internals.

Status

Phases 0–8 are implemented:

• Phase 0–3: fork, rename, upstream audit docs, durable substrate (gk.db), CLI, fake adapter.
• Phase 4: OMP RPC adapter (internal/runtime OmpAdapter) — spawns omp --mode rpc, streams the JSONL protocol, verified against the real omp binary.
• Phase 5: Worker pool (internal/worker) — single dispatcher, bounded slots, crash recovery, per-task worktrees, loop-spec runner. gk-daemon runs it.
• Phase 6: Fleet view (internal/fleet) + unprefixed CLI commands (fleet, threads, jobs, approvals).
• Phase 7: Channel gateway (internal/channel) — notification policy, HMAC-signed delivery, approval routing.
• Phase 8: Sidecars (internal/sidecar) — email/calendar/contact handlers behind an HMAC-verified HTTP server; the daemon never holds platform credentials.

This is a development build, not a release. The bubbletea TUI shows Groundskeeper threads alongside Agent Deck sessions via the Home projection model (internal/ui/gk_home.go).

Quick Start

Public one-command install from GitHub:

export OLLAMA_CLOUD_API_KEY='<your ollama cloud key>'
curl -fsSL https://raw.githubusercontent.com/potato-hash/groundskeeper/main/install.sh |
  bash -s -- --non-interactive --run-setup --model ollama-cloud/glm-5.2 --verify-model

If raw.githubusercontent.com is behind main during install testing, use the GitHub Contents API raw endpoint:

export OLLAMA_CLOUD_API_KEY='<your ollama cloud key>'
curl -fsSL -H 'Accept: application/vnd.github.raw' \
  'https://api.github.com/repos/potato-hash/groundskeeper/contents/install.sh?ref=main' |
  bash -s -- --non-interactive --run-setup --model ollama-cloud/glm-5.2 --verify-model

Pre-release installs prefer release binaries when available. Until the first Groundskeeper release exists, the installer falls back to building github.com/potato-hash/groundskeeper/cmd/groundskeeper@main, so Go 1.25.11 or newer must be available on a fresh machine. First-run setup installs or discovers OMP, builds Espalier with Bun, creates ~/.local/share/groundskeeper/gk.db, and delegates provider authentication to OMP/environment variables.

Post-install state and secret-persistence check:

curl -fsSL https://raw.githubusercontent.com/potato-hash/groundskeeper/main/scripts/verify-install-state.sh | bash

Clean-VM install smoke with output redaction and state verification:

export OLLAMA_CLOUD_API_KEY='<your ollama cloud key>'
curl -fsSL https://raw.githubusercontent.com/potato-hash/groundskeeper/main/scripts/smoke-public-install.sh | bash

Set GK_SMOKE_INSTALL_DIR=/tmp/groundskeeper-smoke-bin to keep a smoke run in an isolated install directory; the wrapper passes it through as --dir and adds it to PATH for verification.

Local development:

# Build
go build ./cmd/groundskeeper

# First-run onboarding (checks omp, creates gk.db, checks Espalier)
./groundskeeper setup

# Create an agent thread
./groundskeeper gk-thread create --title "Fix the test" --runtime omp --workspace .

# Set up a loop (until_done, max 5 turns)
./groundskeeper loop set <thread-id> --mode until_done --prompt "Fix the test" --max-turns 5

# Start the loop + daemon
./groundskeeper loop start <thread-id>
./groundskeeper gk-daemon --model ollama-cloud/glm-5.2 --slots 2