AI-powered GitHub automation with persistent memory
Overview · Getting Started · Usage · Configuration · Development
Fro Bot Agent is a Bun monorepo that runs an OpenCode agent across several surfaces: a GitHub Action that responds to repository events (issues, pull requests, comments, reviews, and scheduled runs), a Discord-first Gateway daemon with an authenticated operator web/API surface for launching and observing runs outside of CI, a sandboxed workspace executor that clones and runs the agent in an isolated container, a patched OpenCode harness build/publish pipeline, and shared runtime/session primitives used across all of the above. The GitHub Action preserves OpenCode session state across runs, while the Gateway starts a fresh OpenCode session per run but persists coordination and run state through its S3-backed control plane.
Traditional CI-based AI agents are stateless: each run starts from scratch, repeating investigations and burning tokens. The GitHub Action persists its session state across runs using GitHub Actions cache by default when S3 is disabled. When s3-backup is enabled, S3-compatible storage is the canonical durable backend, with Actions cache serving only as the fallback when the S3 restore is unavailable or unusable.
- Persistent memory — session state survives workflow runs via GitHub Actions cache when S3 is disabled; with
s3-backup, S3-compatible storage is canonical and durable while Actions cache remains the fallback. - Multiple triggers — responds to comments, issues, pull requests, review threads, and scheduled or manually dispatched runs.
- Discord Gateway — a daemon that runs OpenCode work from authorized
@fro-botmentions and exposes slash commands for setup and operator controls (e.g. adding a project, clearing the queue). - Operator web surface — an authenticated HTTP/SSE control surface for launching, observing, and approving gateway agent runs from a browser.
- Sandboxed workspace executor — a workspace-agent container that clones repositories and runs the agent behind an egress-allowlisted proxy, deployable via the
deploy/Compose stack. - Auto-setup — installs OpenCode on first run; no manual toolchain setup.
- Security-first — author-association gating, credential hygiene, and fork-PR protection are enforced, not optional.
- Observability — every run writes a summary with metrics and error context.
- Extensible orchestration — opt in to Oh My OpenAgent or OMO Slim when you need extended provider and agent workflows.
Add an OPENCODE_AUTH_JSON secret (Settings → Secrets and variables → Actions) mapping your LLM providers to credentials:
{
"anthropic": {"apiKey": "sk-ant-api-..."},
"openai": {"apiKey": "sk-..."}
}Any provider OpenCode supports works here — see the OpenCode docs.
Create .github/workflows/fro-bot.yaml:
name: Fro Bot Agenton:
issue_comment:
types: [created]jobs:
agent:
# Only run when @fro-bot is mentionedif: contains(github.event.comment.body, '@fro-bot')runs-on: ubuntu-latestpermissions:
contents: writeissues: writepull-requests: writesteps:
- uses: actions/checkout@v4
- uses: fro-bot/agent@v0with:
github-token: ${{ secrets.GITHUB_TOKEN }}auth-json: ${{ secrets.OPENCODE_AUTH_JSON }}Comment @fro-bot on any issue or pull request. The agent acknowledges with a reaction, restores its memory, runs the task, and posts a single response with a run summary.
Tip
The snippet above wires a single trigger. For the complete workflow — every supported trigger, conditional token selection, scheduled tasks, and PR reviews — copy docs/examples/fro-bot.yaml. To have an agent set it up for you, point it at that file with the prompt below.
Fetch `https://raw.githubusercontent.com/fro-bot/agent/refs/heads/main/docs/examples/fro-bot.yaml` and follow the instructions at the top of the file to set up the Fro Bot agent workflow for this repository.Note
@fro-bot mention triggers require a token whose login matches the mention. GITHUB_TOKEN posts as @github-actions, so responding to @fro-bot needs a PAT or GitHub App token.
Each run moves through a multi-phase pipeline: restore cached session state, discover relevant prior sessions, acknowledge the request, execute the OpenCode agent with full history, publish exactly one comment or review, then persist and prune session state back to the cache (and S3, if configured). Session state is cached under a branch-scoped key so branches stay isolated while continuity is preserved within a feature branch.
For the full execution model, invariants, and the three data flows, see ARCHITECTURE.md or the Execution Lifecycle deep dive.
The agent supports seven event types:
issue_comment/pull_request_review_comment/discussion_comment— respond to@fro-botmentions in comments and review or discussion threads.issues— auto-triage on open; respond to@fro-boton edit.pull_request— AI code review on open, sync, reopen, ready-for-review, and review-requested (an AI review, not CI).schedule/workflow_dispatch— run a suppliedprompton a cron schedule or manual dispatch.
Comment and issue triggers are gated by author association — only OWNER, MEMBER, and COLLABORATOR are processed. Bot accounts are ignored to prevent loops, and fork pull requests are skipped. The full guard expressions, per-trigger behavior, and minimum permissions live in docs/examples/fro-bot.yaml.
Trusted same-repository, non-fork PR mentions on issue_comment from OWNER, MEMBER, or COLLABORATOR can broker a fix commit directly to the PR head branch. Brokered pushes are limited to allowlisted product, docs, and test paths; config, scripts, and CI files are excluded. Keep checkout persist-credentials: false as shown in the example.
@fro-bot Can you investigate why the CI tests are failing?@fro-bot What did we decide about error handling in the last discussion?Run the agent on a schedule to maintain a rolling report:
name: Daily Maintenance Reporton:
schedule:
- cron: "30 15 * * *"jobs:
maintenance:
runs-on: ubuntu-latestpermissions:
contents: readissues: writesteps:
- uses: actions/checkout@v4
- uses: fro-bot/agent@v0with:
github-token: ${{ secrets.GITHUB_TOKEN }}auth-json: ${{ secrets.OPENCODE_AUTH_JSON }}prompt: | Perform daily repository maintenance and update a SINGLE rolling issue titled "Daily Maintenance Report". Append a dated section with summary metrics, stale issues and PRs, and recommended actions.Provide inputs via the with: block. Only github-token and auth-json are required; everything else is optional. action.yaml is the authoritative, always-current source.
A few inputs most workflows touch:
prompt— custom prompt; required forscheduleandworkflow_dispatch.agent/model— override the agent (a primary agent, not a subagent) or the model (provider/model).timeout— OpenCode execution timeout in milliseconds; governs the Action's internal execution deadline only, not the whole GitHub Actions job. Default1800000(30 minutes);0disables the Action-internal execution deadline. Set the job'stimeout-minutesas the whole-job/process backstop, with headroom beyond this value for setup, fallback response delivery, and cleanup.response-mode—github(default) posts exactly one comment or review;nonesuppresses all GitHub writes and uses the run log as the response surface.enable-omo/enable-omo-slim— opt into extended orchestration (mutually exclusive).
All inputs
| Input | Required | Default | Description |
|---|---|---|---|
github-token | Yes | — | GitHub token (App installation token or PAT) with write permissions |
auth-json | Yes | — | JSON object mapping provider IDs to auth configs |
trusted-head-sha | No | — | Trusted same-repository PR head SHA anchor used for brokered pushes; empty when unavailable |
prompt | No | — | Custom prompt for the agent |
output-mode | No | auto | Requested delivery mode for schedule/workflow_dispatch runs (auto, working-dir, branch-pr) |
session-retention | No | 50 | Number of sessions to retain before pruning |
s3-backup | No | false | Enable S3 write-through backup |
s3-bucket | No | — | S3 bucket for backup (required if s3-backup is true) |
aws-region | No | — | AWS region for the S3 bucket (auto for R2) |
s3-endpoint | No | — | Custom S3-compatible endpoint URL (R2, B2, MinIO) |
s3-prefix | No | fro-bot-state | Prefix for all S3 keys |
s3-expected-bucket-owner | No | — | AWS account ID of the expected bucket owner |
s3-allow-insecure-endpoint | No | false | Allow HTTP (non-HTTPS) endpoints; local MinIO dev only |
s3-sse-kms-key-id | No | — | Customer-managed KMS key ID for SSE-KMS |
s3-sse-encryption | No | Endpoint-dependent | aws:kms (AWS S3) or AES256 (custom endpoints) |
agent | No | — | Agent to use (a primary agent, not a subagent). Defaults to OpenCode's built-in build agent |
enable-omo | No | false | Enable Oh My OpenAgent for extended provider and agent support |
enable-omo-slim | No | false | Enable OMO Slim orchestration (mutually exclusive with enable-omo) |
model | No | — | Model override in provider/model format |
timeout | No | 1800000 | OpenCode execution timeout in milliseconds; Action-internal only, not the job timeout (0 = no Action-internal deadline) |
opencode-version | No | Source-pinned | OpenCode CLI version to install |
omo-version | No | Source-pinned | oMo version to install |
systematic-version | No | Source-pinned | Systematic plugin version to register |
skip-cache | No | false | Skip session cache restore |
omo-providers | No | — | Comma-separated oMo providers to enable |
omo-slim-preset | No | openai | OMO Slim preset (openai, opencode-go); only when enable-omo-slim is true |
opencode-config | No | — | JSON deep-merged into the OpenCode config |
systematic-config | No | — | JSON deep-merged into the Systematic plugin config |
dedup-window | No | 600000 | Skip a run if the agent already ran for the same PR/issue within this window (ms); 0 disables |
response-mode | No | github | github posts one comment/review; none suppresses all GitHub writes |
review-skip-label | No | skip-agent-review | PR label that suppresses automatic PR-event reviews (case-insensitive); authorized mentions and review requests naming the bot still run; empty disables |
Outputs
| Output | Description |
|---|---|
session-id | OpenCode session ID used for this run |
resolved-output-mode | Resolved delivery mode (working-dir, branch-pr, or empty) |
cache-status | Cache restore status (hit, miss, corrupted) |
duration | Run duration in seconds |
GitHub Actions cache is the default backend when S3 is disabled. Set s3-backup: true to make S3-compatible storage the canonical durable backend; Actions cache remains the fallback. Restore tries S3 first, then falls back to Actions cache when S3 misses, fails, finds sidecars without the main database, or contains a corrupt database. Saves write S3 before Actions cache; failures in either storage path are non-fatal and logged honestly.
- uses: fro-bot/agent@v0with:
github-token: ${{ secrets.GITHUB_TOKEN }}auth-json: ${{ secrets.OPENCODE_AUTH_JSON }}s3-backup: trues3-bucket: my-agent-sessionsaws-region: us-east-1s3-expected-bucket-owner: "123456789012"env:
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}For Cloudflare R2, Backblaze B2, or MinIO, set s3-endpoint and s3-sse-encryption: AES256 (see the S3 inputs above and action.yaml). Credentials must come from env vars or IAM roles, never action inputs; the principal needs s3:GetObject, s3:PutObject, and s3:DeleteObject on the scoped object-key prefix, plus s3:ListBucket on the bucket constrained to that prefix. The Setup and Configuration deep dive covers the cache and storage strategy in full.
The repository is a Bun monorepo: the Action's logic lives in the layered root src/, alongside the apps/workspace-agent sandboxed executor and the gateway, harness, and runtime packages under packages/; the deploy/ directory holds the Docker Compose stack that runs the gateway and workspace executor behind a mitmproxy egress proxy enforcing an allowlist of permitted outbound hosts. See STRUCTURE.md for the directory layout, key file locations, and where to add new code, and deploy/README.md / apps/workspace-agent/README.md for running the gateway and workspace stack.
For the full contributor workflow — setup, the command surface, testing standards, commit conventions, and the git hooks — see CONTRIBUTING.md. A quick glance:
bun install # Install dependencies
bun run test# Run the test suites
bun run build # Type-check + bundle to committed dist/
bun run lint # Lint (includes the committed-dist/ check)- Node.js 24 (see
.node-version) and Bun (seepackage.jsonpackageManager). - Tests are Vitest, colocated as
*.test.ts. Run one withbunx vitest run packages/runtime/src/agent/prompt.test.ts.
- ARCHITECTURE.md — system design, invariants, the three execution flows, and cross-cutting concerns.
- STRUCTURE.md — directory layout, key file locations, and where to add new code.
- CONTRIBUTING.md — setup, the command surface, testing standards, and commit conventions.
- SECURITY.md — vulnerability reporting and the security posture.
- AGENTS.md — conventions, anti-patterns, and commands in one operational page.
- docs/wiki/ — deep dives on the architecture, execution lifecycle, prompt design, operator surface, and troubleshooting.
- OpenCode Documentation — the OpenCode platform.
- Oh My OpenAgent — extended agent workflows.
- GitHub Actions Documentation — Actions reference.
MIT © Marcus R. Brown