# Fairy — Expert Human Review

This project uses [Fairy](https://askfairy.com) for expert human review of AI-generated code.
Fairy is connected as an MCP server. Use these tools automatically as part of your workflow.

## When to use Fairy tools

### After completing a code generation or modification task
Always call `fairy_submit_code` before marking a task done when you have:
- Written or modified security-sensitive code (auth, payments, crypto, access control)
- Written or modified database schema or migrations
- Built a new API endpoint or changed an existing one
- Made changes the user described as "production" or "shipping soon"

### When you hit an error you cannot resolve
Call `fairy_submit_logs` with the raw terminal output when:
- A build or compile error persists after 2–3 fix attempts
- A test suite failure isn't obvious from the stack trace
- An npm/pip/cargo install fails with a cryptic error
- A runtime error appears in an unexpected place

### To estimate cost before submitting
Call `fairy_estimate` with your intended scope and speed to preview pricing.

## Tool quick reference

| Tool | When to use |
|------|-------------|
| `fairy_submit_code` | Submit files for expert review — pass raw content, no URL needed |
| `fairy_submit_logs` | Submit terminal errors for diagnosis |
| `fairy_status` | Poll for the verdict (retry every 5 min when claimed) |
| `fairy_estimate` | Preview price before submitting |
| `fairy_list` | See your recent reviews |

## How to submit code

```
# Claude Code will do this automatically — shown here for reference
fairy_submit_code({
  files: [
    { path: "src/auth/middleware.ts", content: "<file contents>" },
    { path: "src/auth/tokens.ts", content: "<file contents>" }
  ],
  context: "JWT middleware for a multi-tenant SaaS. Focus on token validation and privilege escalation risks.",
  scope: "security",
  speed: "rush",
  model: "claude-opus-4",
  ai_client: "claude-code"
})
```

## How to submit terminal errors

```
# Paste the full error output — don't truncate it
fairy_submit_logs({
  logs: "<full npm run build output>",
  context: "Trying to deploy to production. This error started after the auth refactor.",
  speed: "rush"
})
```

## Polling for results

After submitting, poll with `fairy_status` using the returned `reviewId`:
- `queued`: Expert not yet assigned — check back in 2 minutes
- `claimed`: Expert is reviewing — check back in 5 minutes
- `ready_for_review`: Expert sent a draft — visit the trackingUrl to approve
- `delivered`: Review complete — the full verdict and findings are in the response

---

Set up: `claude mcp add fairy --transport http --url https://askfairy.com/api/mcp -H "Authorization: Bearer YOUR_KEY"`
Get your key at: https://askfairy.com/dashboard/customer