pullfrog 0.1.66 → 0.1.68

package/README.md

@@ -1,4 +1,3 @@
-<!-- test preview system -->
 <p align="center">
   <h1 align="center">
     <picture>
@@ -8,144 +7,110 @@
     Pullfrog
   </h1>
   <p align="center">
-    Bring your favorite coding agent into GitHub
+    The BYOK CodeRabbit that runs in your GitHub Actions
   </p>
 </p>
 
-<br/>
-
-> **🚀 Pullfrog is now generally available!** [Get started →](https://pullfrog.com/console)
+<p align="center">
+  <a href="https://pullfrog.com">pullfrog.com</a> · <a href="https://docs.pullfrog.com">Docs</a> · <a href="https://pullfrog.com/console">Console</a> · <a href="https://discord.gg/8y96raFg8e">Discord</a>
+</p>
 
 <br/>
 
+> **New** — Pullfrog is now [free for personal and open-source usage](https://pullfrog.com/blog/free-for-open-source).
+
 ## What is Pullfrog?
 
-Pullfrog is a GitHub bot that brings the full power of your favorite coding agents into GitHub. It's open source and powered by GitHub Actions.
+Pullfrog is the BYOK CodeRabbit that runs in your GitHub Actions. It listens for GitHub events — PRs opened, issues created, reviews submitted, CI failures — and triggers agent runs based on your configuration, via a `pullfrog.yml` workflow that uses this open-source action. You control the infrastructure, the keys, and the costs.
 
-- **Tag `@pullfrog`** — Tag `@pullfrog` in a comment anywhere in your repo. It will pull in any relevant context using the action's internal MCP server and perform the appropriate task.
-- **Prompt from the web** — Trigger arbitrary tasks from the Pullfrog dashboard
-- **Automated triggers** — Configure Pullfrog to trigger agent runs in response to specific events. Each of these triggers can be associated with custom prompt instructions.
-  - issue created
-  - issue labeled
-  - PR created
-  - PR review created
-  - PR review requested
-  - and more...
+Pullfrog is not an agent itself. It wraps vanilla **[Claude Code](https://github.com/anthropics/claude-code)**, **[Codex](https://github.com/openai/codex)**, and **[OpenCode](https://github.com/anomalyco/opencode)**, selecting the one that matches your BYOK or bring-your-own-subscription configuration — so every run uses the vendor's real agent, and it reads the repo-level config you already keep for it: `CLAUDE.md` or `AGENTS.md`, skills, custom commands, and repo-level MCP servers.
 
-Pullfrog is the bridge between your preferred coding agents and GitHub. Use it for:
+Out of the box, it can:
 
-- **🤖 Coding tasks** — Tell `@pullfrog` to implement something and it'll spin up a PR. If CI fails, it'll read the logs and attempt a fix automatically. It'll automatically address any PR reviews too.
-- **🔍 PR review** — Coding agents are great at reviewing PRs. Using the "PR created" trigger, you can configure Pullfrog to auto-review new PRs.
-- **🤙 Issue management** — Via the "issue created" trigger, Pullfrog can automatically respond to common questions, create implementation plans, and link to related issues/PRs. Or (if you're feeling lucky) you can prompt it to immediately attempt a PR addressing new issues.
-- **Literally whatever** — Want to have the agent automatically add docs to all new PRs? Cut a new release with agent-written notes on every commit to `main`? Pullfrog lets you do it.
+- **Review new PRs** — auto-review every incoming PR; the review verdict can gate merges via requireable status checks.
+- **Address reviews** — leave review comments on a Pullfrog PR as you would for a human colleague, and it addresses them.
+- **Autofix CI** — Pullfrog detects CI failures on its own PRs and attempts a fix. It can be configured to fix human PRs too.
+- **Autofix merge conflicts** — keep PRs mergeable without hand-resolving.
+- **Triage issues** — respond to common questions, apply labels, link related issues and PRs, or draft implementation plans.
+- **Anything ad hoc** — tag `@pullfrog` in any issue, PR, or comment. It pulls in the surrounding context and figures out what to do. Prompt from the [console](https://pullfrog.com/console) for anything else.
 
-<!-- Features
-- **Agent-agnostic** — Switch between agents with the click of a radio button.
-- ** -->
+Each automation can be toggled from the dashboard and customized with per-trigger instructions.
 
-<!--
 ## Get started
 
-Install the Pullfrog GitHub App on your personal or organization account. During installation you can choose to limit access to a specific repo or repos. After installation, you'll be redirected to the Pullfrog dashboard where you'll see an onboarding flow. This flow will create your `pullfrog.yml` workflow and prompt you to set up API keys. Once you finish those steps (2 minutes) you're ready to rock.
+Run one command in any local repo:
 
-[Add to GitHub ➜](https://github.com/apps/pullfrog/installations/new)
+```sh
+npx pullfrog init
+```
 
-<details>
-<summary><strong>Manual setup instructions</strong></summary>
+Or [install from the browser](https://pullfrog.com/console). Setup takes about two minutes: install the GitHub App, add the `pullfrog.yml` workflow with one click, and pick a model. See [getting started](https://docs.pullfrog.com/getting-started).
+
+## Runs on the subscription you already pay for
+
+No API key required. Connect a coding-agent plan once and every run bills against it:
 
-You can also use the `pullfrog/pullfrog` Action without a GitHub App installation. This is more time-consuming to set up, and it places limitations on the actions your Agent will be capable of performing.
+| Plan | Connect with |
+| --- | --- |
+| [Claude Pro/Max](https://docs.pullfrog.com/claude-auth) | `npx pullfrog auth claude` |
+| [ChatGPT Codex](https://docs.pullfrog.com/codex-auth) | `npx pullfrog auth codex` |
+| [Grok](https://docs.pullfrog.com/grok-auth) | `npx pullfrog auth grok` |
+| [Kimi Code](https://docs.pullfrog.com/kimi-code) | a Kimi Code key as `KIMI_API_KEY` |
+| [OpenCode Go](https://docs.pullfrog.com/models#opencode-zen-and-opencode-go) | an OpenCode key as `OPENCODE_API_KEY` |
 
-To manually set up the Pullfrog action, you need to set up two workflow files in your repository: `pullfrog.yml` (the execution logic) and `triggers.yml` (the event triggers).
+## Or bring your own model
 
-#### 1. Create `pullfrog.yml`
+Pullfrog works with any LLM provider: Anthropic, OpenAI, Google, xAI, Mistral, DeepSeek, OpenRouter, and more. Switch models with a config change. Two more ways to pay for tokens:
 
-Create a file at `.github/workflows/pullfrog.yml`. This is a reusable workflow that runs the Pullfrog action.
+- **Your own API key** — stored in Pullfrog's encrypted secret store or in GitHub Actions secrets, your choice.
+- **Router** — Pullfrog's built-in model access, billed at raw provider cost with no markup.
+
+## Batteries included
+
+- 🛠️ **MCP tools for GitHub** — a purpose-built MCP server for git and GitHub operations: creating PRs, leaving reviews and comments, reading CI logs, managing issues. Every operation goes through Pullfrog's permission layer.
+- 🛡️ **Secure shell access** — shell commands run in an isolated subprocess without access to sensitive environment variables.
+- 🌐 **Headless browser** — for end-to-end tests, screenshots, and UI iteration, with screenshot uploads out of the box.
+- 🔑 **Short-lived credentials** — all GitHub operations use an installation token that is auto-revoked when the run completes. Keys are auto-masked in logs, and only the minimum necessary environment variables pass through to the agent.
+- 🪝 **Hooks** — setup, post-checkout, pre-push, and stop scripts that run inside the agent's permission boundary. A stop script that exits non-zero resumes the agent with the failure as context, so it fixes its own broken push instead of opening a red PR.
+- 🔐 **GitHub-native permissions** — GitHub remains the single source of truth for access control. Users only see repos they already have access to; org settings require an org owner.
+
+## Pricing
+
+Pullfrog is free for developers on personal GitHub accounts and free for open-source repos. Pro is $30/month for the whole organization with no per-run or per-seat billing — required for an org's private repos, optional everywhere else. Pullfrog also covers model cost for impactful open-source projects — [apply here](https://pullfrog.com/for-oss).
+
+## Standalone usage
+
+The same `pullfrog/pullfrog@v0` action that powers the automations above also works as a step in your own workflows — an agent as one stage of a larger pipeline. The action takes a `prompt` and the provider key of your choice; the only permission it needs is `id-token: write`, which lets it mint its own short-lived GitHub token.
 
 ```yaml
-# PULLFROG ACTION — DO NOT EDIT EXCEPT WHERE INDICATED
-name: Pullfrog
+# .github/workflows/agent.yml — run any prompt on demand
+name: Agent
 on:
   workflow_dispatch:
     inputs:
       prompt:
-        type: string
-        description: 'Agent prompt'
-
-permissions:
-  contents: read
+        description: What should the agent do?
+        required: true
 
 jobs:
-  pullfrog:
+  agent:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
       contents: read
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
-      - name: Run agent
-        uses: pullfrog/pullfrog@v0
+      - uses: actions/checkout@v4
+      - uses: pullfrog/pullfrog@v0
         with:
           prompt: ${{ inputs.prompt }}
         env:
-          # add API keys for the LLM provider(s) you want to use
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
-          XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
-          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
-          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
-          MOONSHOT_API_KEY: ${{ secrets.MOONSHOT_API_KEY }}
-
 ```
 
-Every PR run posts a `pullfrog` commit-status check: `in_progress` from the moment the run is dispatched, then success when it finishes or failure on error/timeout. It is on by default. To also gate merges on Pullfrog's review verdict, enable the `pullfrog-approval` check, which reports whether Pullfrog would approve the PR. Both are repository settings, configured in the Pullfrog console (Automations → Review PRs), and both are requireable as branch-protection status checks. See [PR reviews → Status checks](https://docs.pullfrog.dev/pr-reviews#status-checks).
-
-#### 2. Create `triggers.yml`
-
-Create a file at `.github/workflows/triggers.yml`. This workflow listens for GitHub events and calls the `pullfrog.yml` workflow with the event data.
-
-```yaml
-name: Agent Triggers
-
-on:
-  issue_comment:
-    types: [created]
-  pull_request_review_comment:
-    types: [created]
-  issues:
-    types: [opened, assigned]
-  pull_request_review:
-    types: [submitted]
-  # add other triggers as needed
-
-
-jobs:
-  pullfrog:
-
-    # trigger conditions (e.g. only run if @pullfrog is mentioned)
-    if: contains(github.event.comment.body, '@pullfrog') || contains(github.event.issue.body, '@pullfrog')
+The action also exposes a `result` output that subsequent steps can consume. See [CI integration](https://docs.pullfrog.com/headless-action) for the full guide.
 
-    permissions:
-      id-token: write
-      contents: read
-    uses: ./.github/workflows/pullfrog.yml
-    with:
-      # pass the full event payload as the prompt
-      prompt: ${{ toJSON(github.event) }}
-    secrets: inherit
-```
-
-</details>
--->
-
-## Standalone Usage
-
-You can also use `pullfrog/pullfrog` as a step in your own workflows. The action exposes a `result` output that can be consumed by subsequent steps.
-
-### Example: Auto-generate release notes on new tags
+<details>
+<summary><strong>Example: auto-generate release notes on new tags</strong></summary>
 
 ```yaml
 name: Release
@@ -188,7 +153,10 @@ jobs:
           NOTES: ${{ steps.notes.outputs.result }}
 ```
 
-### Example: Prompt from a file
+</details>
+
+<details>
+<summary><strong>Example: prompt from a file</strong></summary>
 
 For longer prompts you want to version and reuse, commit the prompt text to the repo and pass its path with `prompt_file` instead of inlining it. The path is resolved relative to `GITHUB_WORKSPACE`, and it is mutually exclusive with `prompt` — set exactly one.
 
@@ -202,56 +170,11 @@ For longer prompts you want to version and reuse, commit the prompt text to the
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-### Example: Structured Output with Zod Schema
-
-You can force the agent to return structured JSON output by providing a JSON schema. This allows you to reliably parse and use the agent's response in subsequent workflow steps.
-
-You can define your JSON schema directly or you can use any validation library that converts to JSON Schema. Here's an example using [Zod](https://zod.dev):
-
-```yaml
-name: Release Check
-on:
-  pull_request:
-    types: [closed]
-
-jobs:
-  check-release:
-    if: github.event.pull_request.merged == true
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
+</details>
 
-      - name: Install dependencies
-        run: npm install --no-save --no-package-lock zod @actions/core
+<details>
+<summary><strong>Structured output</strong></summary>
 
-      - name: Generate Schema
-        id: schema
-        run: |
-          node -e '
-            import { z } from "zod";
-            import { setOutput } from "@actions/core";
-            const schema = z.object({
-              version: z.string().describe("Semantic version number (e.g. 1.0.0)"),
-              isBreaking: z.boolean().describe("Whether this release contains breaking changes"),
-              changelog: z.array(z.string()).describe("List of changes in this release"),
-            });
-            setOutput("schema", JSON.stringify(z.toJSONSchema(schema)));
-          '
-
-      - name: Analyze PR
-        id: analysis
-        uses: pullfrog/pullfrog@v0
-        with:
-          prompt: |
-            Analyze this PR and determine semantic versioning impact.
-            Return a JSON object matching the provided schema.
-          output_schema: ${{ steps.schema.outputs.schema }}
-        env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+Pass a JSON Schema via the `output_schema` input to make the agent's output required and validated — the bridge between an agent's reasoning and the hard steps that follow it. See [capturing agent output](https://docs.pullfrog.com/headless-action#capturing-agent-output) for the details and a worked example.
 
-      - name: Process Result
-        run: |
-          # Parse the JSON result using fromJSON()
-          echo "Version: ${{ fromJSON(steps.analysis.outputs.result).version }}"
-          echo "Breaking: ${{ fromJSON(steps.analysis.outputs.result).isBreaking }}"
-```
+</details>