Keelmarker

For AI agents

Last updated: October 30, 2026

This page is written for an AI coding agent that has been asked to use Keelmarker for its user. Keelmarker keeps a list of what the user asked for, links each item to a test, and answers one question: is every promise backed by passing proof? Use it so that you never tell the user work is done while the gate is blocked.

1. Connect

Ask the user for an access token. They create it under Settings in the app at https://keelmarker.com/app/. Never invent or guess a token, and never write one into a file that is committed. Then add Keelmarker as an MCP server over HTTP:

claude mcp add --transport http keelmarker https://keelmarker.com/api/v1/mcp --header "Authorization: Bearer YOUR_TOKEN"

If you are not Claude Code, add an MCP server with the address https://keelmarker.com/api/v1/mcp and the header Authorization: Bearer YOUR_TOKEN. Tell the user if a restart is needed before the tools appear.

2. Work in this order

  1. at_list_products: find the product this project belongs to, or create it with at_create_product.
  2. at_task_start: record what the user asked for before writing code.
  3. at_promise: write one testable promise for each behavior the user asked for.
  4. at_create_test: register each test by its exact name, then link it to its promise with at_link_spec_test.
  5. at_report_results: report the real test results for the commit, using the short commit id.
  6. at_check_gate: ask for the verdict before telling the user anything is done.
  7. at_task_close: close the task; it only succeeds when the gate passes.
  8. at_record_deployment: record which commit is running where, after each deployment.

Use the short commit id (not the full one) when you report results or deployments. A test name must match the real test name exactly.

3. What you may not do

You can read everything, add and strengthen requirements, link tests, and report results and findings. You cannot sign off a risk, dismiss a finding, promote a gate rule or retire a test: a person does those and the record carries their name. If a requirement can only be judged by a person, say so and ask the user to sign it off. Never say something is proven when it was not run.

4. Answers to common questions

The same questions and answers as on the home page are in /llms-full.txt. The full guide is at /docs/. Sign-up is by early access; a read-only live demo is on the home page.