# specloop — Documentation

> specloop gives AI coding agents human-expert guidance. Send a focused coding
> question with your app context; a vetted human expert answers; you get an
> agent-ready prompt back in your terminal or agent. Interfaces: a CLI and an MCP
> server (local stdio + remote HTTP).

- Website: https://specloop.dev
- Docs (human): https://specloop.dev/docs
- Docs (this file, Markdown): https://specloop.dev/docs.md
- npm package: `@specloop/cli`
- Remote MCP endpoint: `https://specloop.dev/mcp` (Streamable HTTP)

---

## Quickstart

```bash
npm i -g @specloop/cli            # or call commands with: npx @specloop/cli <command>
specloop login                    # GitHub device flow — approve a code in the browser
specloop credits buy --pack starter   # prints a Stripe link (or redeem a voucher in the dashboard)

specloop ask \
  --query "What should I prompt my agent next for auth?" \
  --summary "B2B dashboard; added bearer middleware + /me route" \
  --tech "Next.js, Postgres, Cloudflare" \
  --tools "Stripe, GitHub OAuth"

specloop watch                    # desktop ping + clipboard when an expert answers
specloop get <request-id>         # the agent-ready prompt — paste it into your coding agent
```

Requires Node 18+.

---

## How it works

1. You send a question plus app context (overview, tech stack, tools, optional snippet/URL).
2. A private, secret-stripped scratch pull request is created so a vetted human expert can review your context.
3. An available expert claims the request and replies. Internal targets: claim within 10 minutes, reply within 20.
4. Their guidance comes back as a synthesized, agent-ready prompt you paste into your coding agent.

**Money-back guarantee:** if no expert answers within 24 hours, the credits for that request are automatically refunded.

---

## Install the CLI

```bash
npm i -g @specloop/cli      # global: enables the `specloop` command
# or, no install:
npx @specloop/cli --help
```

Sign in once with GitHub. Your token is saved to `~/.ai-review/config.json` and reused by every command and by the MCP server.

```bash
specloop login              # GitHub device-flow login
```

---

## Get credits

Each guidance request costs **100 credits** (about one request).

- **Buy:** `specloop credits buy --pack starter` prints a Stripe checkout link. Packs: `starter` (100), `pro` (500), `team` (1000).
- **Voucher:** redeem a code in the dashboard (https://specloop.dev/dashboard → Billing & Usage). Same GitHub account as the CLI, so credits are shared.
- **Balance:** `specloop credits`.

---

## Connect via MCP

The specloop MCP server lets your agent submit requests and pull answers directly — no copy-paste. It runs locally over stdio and works in any tool that supports MCP servers (Claude Code, Claude Desktop, Codex, Cursor, Windsurf, VS Code).

Sign in once first, so the server can authenticate (CLI v0.1.6+ reuses the saved token — no env needed):

```bash
specloop login
```

> Token note: after `specloop login`, the MCP server reuses your saved token automatically. On CLI versions older than 0.1.6, add it as an env var on the server: `"env": { "SPECLOOP_TOKEN": "air_…" }` (your token is in `~/.ai-review/config.json`).

### Claude Code

```bash
claude mcp add specloop -- npx -y @specloop/cli mcp
```

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart:

```json
{
  "mcpServers": {
    "specloop": {
      "command": "npx",
      "args": ["-y", "@specloop/cli", "mcp"]
    }
  }
}
```

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.specloop]
command = "npx"
args = ["-y", "@specloop/cli", "mcp"]
```

### Cursor

Settings → MCP → Add new global MCP server, or create `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "specloop": {
      "command": "npx",
      "args": ["-y", "@specloop/cli", "mcp"]
    }
  }
}
```

Then toggle `specloop` on in Settings → MCP; the tools become available in Agent/Composer.

### Remote MCP (web platforms)

For web tools that connect by URL instead of a local command (Streamable HTTP):

```
URL:    https://specloop.dev/mcp
Header: Authorization: Bearer <your-token>
```

Get your token from `specloop login` or the dashboard.

---

## MCP tools

| Tool | Description |
| --- | --- |
| `submit_human_guidance` | Submit a request: `query` plus `summary`, `techStack`, `tools`, optional `codeSnippet` / `githubUrl`. |
| `get_human_guidance_status` | Check a request's status and how many expert responses it has. |
| `get_expert_comments` | Fetch the exact human-expert comments for a request. |
| `get_agent_ready_prompt` | Fetch the synthesized prompt to paste back into your agent. |

---

## CLI command reference

| Command | Description |
| --- | --- |
| `specloop login` | Sign in with GitHub (device flow). |
| `specloop credits` | Show your credit balance. |
| `specloop credits buy --pack <pack>` | Buy credits — prints a Stripe checkout link. |
| `specloop ask --query … --summary … --tech … --tools …` | Submit a guidance request. |
| `specloop status [id]` | Check one request, or list your requests. |
| `specloop comments <id>` | Show the exact expert comments. |
| `specloop get <id>` | Print the agent-ready prompt. |
| `specloop watch` | Ping (desktop + clipboard) when an expert answers. |
| `specloop mcp` | Run the MCP server (stdio) for your agent tools. |

---

## For experts

Apply in the dashboard (https://specloop.dev/dashboard → Become an expert). Applicants are vetted by recent GitHub activity and approved by an admin. Once approved:

| Command | Description |
| --- | --- |
| `specloop expert:available on` | Go on duty (receive/claim requests). `off` to pause. |
| `specloop inbox` | List open requests you can claim. |
| `specloop expert:claim <id>` | Claim an open request (then ~20 minutes to reply). |
| `specloop answer <id> --comment "…"` | Answer. With no comment, your PR review is pulled in. |
| `specloop watch` | Ping when a new request is available to claim. |