frog weekly downloads statistics

Automated friction logging for agents.

Problem · Solution · Quick Prompt · Setup · Usage

Problem

An agent hits friction constantly, and notices all of it. That makes it the best friction logger you have, and the worst at keeping one: each workaround goes unrecorded, and the next agent starts from nothing.

Nobody who could fix the friction hears about it either. Keeping the log by hand does not work: you stop noticing what to write, and nothing removes the entries you did write. The list goes stale, and a stale list goes unread.

Solution

Frog gives the agent somewhere to put it. Each entry is a directory in .agents/friction-log/ holding the write-up and whatever reproduces it, committed with the code and written the moment friction is hit. The agent reads them before it starts guessing.

Each entry is then reported as an issue, so somebody owns it, and deleted once that issue closes, so the log only ever holds what is still unresolved. Friction in a dependency can be reported to that project instead, if it has opted in.

Quick Prompt

Prompt your agent:

Setup

1. Install Frog (optional)

Install a standalone executable:

Or install Frog globally:

2. Initialize Frog

If you installed Frog:

If you skipped installation, use your package manager:

You can use these runners with any Frog command, e.g. npx frog list.

3. Choose Automation Method

Frog supports two automation methods. If an agent is doing the setup, it should prompt the user before changing repository access or adding a workflow:

• Install the Frog GitHub App and add the App mode workflow for pull-request comments, forks, and cross-repository reporting. • Use the Action-only mode workflow for same-repository automation without granting a third-party App access.

Choose one method per repository. Running both can create duplicate issues.

Workflow

See the original lifecycle in wevm/frog-demo, where an agent adding a health endpoint hit a config loader that turns a missing environment variable into the string "undefined", and logged it on the way past. These linked setup commits predate the least-privilege App workflow; use the current setup below.

| Step | What happens | Example |

| 1 | Agent hits friction while working and runs frog log | — | | 2 | The entry commits alongside the change that provoked it | 0de4ab6 | | 3 | Frog comments on the pull request, naming what it found | #1 | | 4 | Frog reports the entry as an issue and writes its issue: link | #2 | | 5 | You fix the friction and close the issue | #3 | | 6 | Frog opens a pull request deleting the resolved entry | #4 | | 7 | Merging leaves the log holding only what is still unresolved | e4ac13d |

Action-only workflow

Action-only uses the repository's workflow and GITHUB_TOKEN, without installing the Frog GitHub App:

| Step | What happens | Example |

| 1 | Run frog init, choose Action-only, and add the repository workflow. | 5a3142b | | 2 | An agent hits friction and runs frog log; the report uses the repository's friction issue form. | friction.md | | 3 | Frog reports the friction as an issue and opens or updates one accumulating frog/sync pull request. | #1 · #2 | | 4 | A fix closes the issue. | #3 | | 5 | The issue event or next scheduled run updates the same frog/sync pull request to delete the resolved report. | #2 | | 6 | Merging leaves the log holding only unresolved reports. | 900ea2c |

Usage

Add Logs

Records one friction as an entry: a directory holding the write-up and anything needed to reproduce it. Prompts for the details in a terminal, or takes them as flags.

--publish reports it as an issue immediately. Otherwise it stays pending until the next frog publish.

View Logs

Shows every unresolved entry: what it is, whether it has been reported, where it is targeted, and whether it ships a reproduction. Exits 1 on an entry that fails to parse, so it doubles as a CI check.

Logging Upstream

Reports friction to another project instead of your own. A target is an npm package or an owner/repo, and it has to have opted in: targets lists the ones your dependencies declare.

A package names its repository through the standard repository field, and consent is then read from that repository's own default branch. So nothing a package says can send a report somewhere that has not itself agreed to receive one.

Naming a target also scaffolds the entry from that project's GitHub issue form, so the report answers the questions it actually asks rather than Frog's own. A project that names no form keeps Frog's sections.

Accept Inbound Logs

Accept friction reported by other repositories with .agents/friction-log/config.json:

frog init enables inbound reports by default. Run frog init --no-inbound to initialize without accepting inbound reports.

Store Logs in a Database

Store friction logs in a shared database so multiple agents and applications can record and inspect them.

Database Support

| Database | Status | Factory |

| PostgreSQL | Available | Store.postgres({ connectionString }) | | SQLite | Coming soon | — | | Cloudflare D1 | Coming soon | — |

CLI Reference

Automation Modes

GitHub App or Action-only?

Choose the GitHub App for pull-request feedback, forks, cross-repository reporting, or durable event processing. Choose Action-only when same-repository automation and avoiding a third-party App grant matter most. Choose one method per repository; running both can create duplicate issues.

| Area | GitHub App | Action-only |…

Description from the npm listing.