grill-me

Why it exists

Working code is not the same as understood code. When your mental model drifts from the implementation, reviews become shallower, debugging becomes slower, and incidents become harder to reason about. grill-me helps surface those gaps before they matter.

See it in action

When run in a real codebase, a quiz can uncover more than a gap in your mental model:

You: /grill-me

Agent: Two processes append the same event type to the same aggregate stream at
nearly the same time. Does `FsEventStore` prevent event loss? Explain the
resulting behavior.

You: Yes. Each event is written to a unique temporary file and moved atomically
into the stream. If two writers select the same sequence number, one should
encounter a conflict and retry.

Agent: Incorrect. The temporary files are unique, but the destination filename
is not. Both processes can count the same existing files, calculate the same
sequence number, and move to the same destination with overwriting enabled.
The later move silently replaces the earlier event. The atomic move prevents
partial-file corruption, but it does not prevent event loss. See
`cli/src/infrastructure/persistence/FsEventStore.ts:24`.
Would you like another question?

You: No. That sounds like an implementation bug. Help me plan a Jumbo goal to
make event appends safe across processes.

Agent: Proposed goal: Make `FsEventStore` appends concurrency-safe.

Success criteria:
- Concurrent appends to one stream preserve every event.
- Every persisted event receives a unique, monotonically increasing sequence.
- Write collisions are retried or reported explicitly, never overwritten.
- A deterministic multi-process test reproduces and guards against the race.
- Existing event files remain readable without migration.

grill-me tests your understanding against the implementation—not against how the system ought to work. Sometimes the gap it finds is in the code.

Install

Codex

Add this repository as a plugin marketplace, then install the plugin:

codex plugin marketplace add joshuawheelock/grill-me
codex plugin add grill-me@grill-me

Start a new Codex thread after installation.

For standalone local use, you can instead clone or copy the skill so it is available at one of these paths:

  • User-wide: ~/.agents/skills/grill-me/SKILL.md
  • Repository-specific: <repository>/.agents/skills/grill-me/SKILL.md

Codex detects skill changes automatically. If the skill does not appear, restart Codex. See the official Build plugins documentation for plugin packaging and testing.

Claude Code

Add this repository as a marketplace, then install the plugin:

/plugin marketplace add joshuawheelock/grill-me
/plugin install grill-me@grill-me

Cursor

For local installation or marketplace testing, copy this repository to Cursor's local plugin directory:

~/.cursor/plugins/local/grill-me

Restart Cursor or run Developer: Reload Window after copying it. For public distribution, submit the repository through the Cursor Marketplace publisher form; after publication, users can install it from Cursor's Customize page.

Google Antigravity

Install the plugin from this repository with Antigravity CLI:

agy plugin install https://github.com/joshuawheelock/grill-me

For workspace-local use in Antigravity, you can instead copy the repository into <workspace>/.agents/plugins/grill-me. For global IDE use, copy it into ~/.gemini/config/plugins/grill-me.

OpenCode

OpenCode can load the existing Agent Skill directly; no executable OpenCode plugin is required. Copy or symlink skills/grill-me from this repository into one of these locations:

  • User-wide: ~/.agents/skills/grill-me or ~/.config/opencode/skills/grill-me
  • Repository-specific: <repository>/.agents/skills/grill-me or <repository>/.opencode/skills/grill-me

Start a new OpenCode session after installation so it discovers the skill.

Use

Invoke the installed skill for your coding agent:

Codex

$grill-me

Claude Code

/grill-me:grill-me

Cursor

/grill-me

Google Antigravity

/grill-me

OpenCode

Ask OpenCode to use the grill-me skill, or invoke it through natural language.

You can also ask in natural language:

Do I know this codebase?

Quiz me on this codebase.

The skill asks one question at a time. Once you answer, it grades the response and asks whether you want to continue.

How it works

When invoked, grill-me:

  1. Selects one viable file locally without sending a repository-wide file listing through the model context.
  2. Traces a substantive behavior from that file into only the related implementation, tests, and configuration needed to establish an answer.
  3. Avoids recently selected files and falls back to broader inspection when a useful subject cannot be found.
  4. Asks one focused question about how that part of the system works.
  5. Grades your response against the current code, allowing equivalent terminology.
  6. Replies with a simple confirmation when correct, or explains the actual behavior when incorrect.
  7. Offers another question after the current one is resolved.

What it tests

Questions favor maintainers' knowledge—behavior, control flow, data flow, state, boundaries, tradeoffs, and failure modes—over line-number or identifier trivia.

Privacy

grill-me ships small native helpers for Windows, macOS, and Linux on x64 and ARM64. They enumerate candidate paths locally and print only one selected relative path, with no Python, shell, or language runtime required. The auditable Go source and cross-build tool are included in the repository. The helpers have no MCP server, authentication, analytics, or network behavior. Repository inspection still uses the permissions and data-handling controls configured for the host coding agent.

Project status

grill-me is currently at v0.1.0 alpha. The core quiz workflow is ready for use and will continue to evolve from real-world feedback.

Contributing

Contributions that improve question quality, grading fairness, token efficiency, or compatibility with different codebases are welcome. Keep bundled automation narrow, local, and deterministic where practical.

Run the tests, rebuild the distributable helpers, and validate the repository before opening a pull request:

go test ./...
go run ./tools/build-picker
python scripts/validate.py

The design and tradeoffs behind token-efficient selection are documented in the question-selection roadmap. The public-directory review cases are prepared in plugin submission tests.

License

Licensed under the MIT License.