# AI Explore Review Loop Plugin

An open-source Claude Code plugin that lets a coding-agent session wait for a
durable, exact-head pull-request review and continue the same review/fix/push
loop without polling GitHub.

The plugin combines:

- PostToolUse, Stop, and SessionStart Hooks;
- an ordinary stdio MCP server;
- Supabase durable reads plus Realtime wake-ups;
- exact PR head-SHA validation;
- idempotent local and server-side review receipts;
- skills for status, pause, resume, stop, and review handling.

It does **not** require Anthropic MCP Channels and can run in Claude Code setups
that use compatible third-party model providers.

## What is included

This public repository contains only the installable plugin, its buildable
source, tests, and public documentation. It intentionally excludes the private
server-side control plane, Pod addresses, GitHub App configuration, Supabase
migrations, Hermes deployment scripts, and operational baselines.

The full system requires a compatible backend exposing these authenticated
Supabase RPCs:

- `get_ai_explore_review_state(repo, pr_number, head_sha)`;
- `ack_ai_explore_review_result(result_id, client_id, session_hash, status, new_head)`.

The authenticated user must also have RLS SELECT access to the corresponding
`github_pr_state` row for Realtime wake-ups. Realtime is never treated as final
delivery; the MCP tool always re-reads durable state.

## Rush marketplace status

Rush marketplace distribution is not enabled yet. The current Rush Git importer
and installer preserve recognized Skills and `.mcp.json`, but omit the Hook,
`bin/`, and `dist/` files required by this plugin. A trial entry was removed
after this was verified with a real install.

Do not publish a reduced Skills+MCP package under the same name: it would appear
installed while lacking the automatic review-loop and its MCP executable. Rush
distribution can be enabled after the platform preserves arbitrary Claude
plugin assets and Hooks end to end.

## Install from GitHub without a checkout

```bash
claude plugin marketplace add kanyun-inc/ai-explore-review-loop-plugin
claude plugin install ai-explore-review-loop@ai-explore --scope user
```

## Configure

The plugin needs a Supabase project URL, public anon/publishable key, and a
developer Auth session. Run the login command through the public GitHub package
in a real terminal, so no repository checkout is needed and the password does
not enter the model transcript:

```bash
npm exec --yes \
  --package=github:kanyun-inc/ai-explore-review-loop-plugin \
  -- ai-explore-review-loop login \
  --url 'https://your-project.example.com' \
  --anon-key 'YOUR_PUBLIC_ANON_OR_PUBLISHABLE_KEY' \
  --email 'developer@example.com'
```

Passwords are read without echo and are not stored. Runtime state and refresh
tokens live outside the repository in a mode-`0600` user configuration file.

## Develop

Requires Node.js 22 or newer:

```bash
npm ci
npm run build
npm run check
npm run validate:plugin
npm run security:scan
```

Generated plugin bundles are committed so marketplace installation does not run
`npm install` on developer machines.

## Security properties

- no database URL or Supabase service-role credential;
- no GitHub App private key or worker password;
- developer RLS instead of shared admin credentials;
- exact-head binding before returning or handling a review;
- duplicate Realtime events are harmless;
- Stop Hook fails open on infrastructure/authentication errors rather than
  trapping the developer;
- GitHub review text is treated as untrusted input and verified against the
  current diff.

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## License

Apache License 2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).