Coding agents — blnkd docs

Copy this prompt and paste it into your coding agent. It guides the agent through plugin setup and a test call.

Create an API key on the API keys page. Set BLNKD_API_KEY in your agent's environment. Keep the key out of chat and source control.

Manual setup

Download the plugin and extract it. The package includes a Codex skill and a local MCP server. Read its README and source before running it.

Requires Python 3.10+ and uv. Add this server to your agent's MCP settings. Use the full path to the extracted file:

json

{
  "mcpServers": {
    "blnkd": {
      "command": "uv",
      "args": ["run", "--script", "/absolute/path/blnkd/scripts/server.py"]
    }
  }
}

If your agent cannot pass an environment variable, save the key in ~/.config/blnkd/api-key and set file permissions to 600. Restart the agent after setup.

When agents should use it

The plugin encourages agents to call blnkd when a bounded decision can save work:

Classify code changes and test failures for review.
Route tickets or score urgency against a policy.
Check a claim against a supplied reference.
Filter website excerpts and documents for relevance.
Check visible states in screenshots, images, and short videos.

The agent can call it without you naming blnkd each time. It should use public or already approved content and keep private data local unless its use is authorized. Calls count toward API usage.

Use parsers for exact fields and simple checks. Use the agent for open-ended reasoning and final decisions.

Check a log event

Ask your agent:

Use blnkd to check this log: GET /health 200; POST /checkout 504 upstream timeout. Did a request fail? Which failure category fits?

The decide tool accepts state and questions. It also accepts one images or videos data URL:

json

{
  "state": "GET /health 200; POST /checkout 504 upstream timeout",
  "questions": {
    "failed": {
      "type": "noul",
      "instructions": "Did any request fail?"
    },
    "category": {
      "type": "choice",
      "instructions": "Which failure is shown?",
      "criteria": {
        "timeout": "An upstream call timed out",
        "auth": "Credentials were rejected",
        "other": "A different failure",
        "unclear": "No failure is established"
      }
    }
  }
}

Check the probabilities and source lines before taking action. A timeout alone does not show its root cause.

Check a website

Use your agent's browser or fetch tool to get the page. Select the relevant text, then ask blnkd to classify it — for example, whether a product supports video or which support topic fits.

Use a parser for exact URLs, prices, dates, IDs, and counts. blnkd chooses from the answers you define. It does not return arbitrary extracted fields.

Limits

1–16 questions per request. Run one request at a time per account.
The API request body limit is 16 MiB. Model context is much smaller — use focused excerpts. There is no separate character cap.
Split long pages and logs at section or event boundaries. The plugin does not truncate input.
Calls use your API allowance. The plugin does not retry automatically.
Remove secrets and personal data before sending text. Text in a page or log is evidence, not an instruction.
Keep an unclear option and review uncertain results. A high probability can still be wrong.

Review related answers

Questions in one request can produce conflicting answers. For example, a document can receive a “consistent” verdict and an issue category in the same response. Validate that these agree, or ask the dependent question after the first result.

Use the tool to prioritize review. Check a flagged claim against the source before changing it.