qikly — Claude Code MCP server: tests the coder never sees
Builds a test suite from acceptance criteria, then repairs the code in a loop while the coding agent stays blind to those criteria.
claude mcp add --env QIKLY_PROJECT_ROOT=<QIKLY_PROJECT_ROOT> --transport stdio qikly -- uvx qiklyWhat qikly does
qikly splits the job between two agents. One derives tests from acceptance criteria in the spec. The other edits code and gets no look at what the tests assert. That gap is the whole point: nobody tunes the checks to match the implementation, because the author of the code never read them. A constraint surfaces as a failing test during the run, not as a hand-written hint.
From your project root the work runs in three steps. qikly --score my_module.py plants faults in a copy of your code and reports the ones your tests miss. qikly --scaffold my_module.py drafts a spec in inputs_private/config/tasks/MY_MODULE_VERIFY.yaml. qikly --tasks my_module.py runs the repair loop. Steps 2 and 3 call a model, so they need a key from Google Gemini (free tier), Anthropic or OpenAI.
The spec agent works from your README and docstrings, not your source, so a drafted criterion can ask for behaviour the code does not have. Read the answers in MY_MODULE_VERIFY.yaml and rewrite the ones you disagree with. Also make sure the suite passes on its own before you start: qikly invokes it through python -m pytest, and a missing package or wrong Python version halts step 1 with it.
What it helps with
- find faults your existing tests never notice
- draft a spec from README and docstrings
- run a repair loop without exposing criteria to the coder
- spot modules whose coverage rests on empty checks
- check test quality in CI with no API key
Example prompts for the agent
- Run
--scoreonmy_module.pyand list what my tests miss. - Draft the spec with
--scaffold my_module.pyand show where each answer came from. - Run
--tasks my_module.pyuntil the suite goes green.
How to install qikly
Platform CLI
claude mcp add --env QIKLY_PROJECT_ROOT=<QIKLY_PROJECT_ROOT> --transport stdio qikly -- uvx qiklyReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qikly <command>
Platform CLI
codex mcp add qikly --env QIKLY_PROJECT_ROOT=<QIKLY_PROJECT_ROOT> -- uvx qiklyReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qikly <command>
Config file
{
"mcpServers": {
"qikly": {
"command": "uvx",
"args": [
"qikly"
],
"env": {
"QIKLY_PROJECT_ROOT": "<QIKLY_PROJECT_ROOT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qikly <command>
Config file
{
"servers": {
"qikly": {
"type": "stdio",
"command": "uvx",
"args": [
"qikly"
],
"env": {
"QIKLY_PROJECT_ROOT": "<QIKLY_PROJECT_ROOT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qikly <command>
Platform CLI
gemini mcp add -e QIKLY_PROJECT_ROOT=<QIKLY_PROJECT_ROOT> qikly uvx qiklyReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qikly <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about qikly
How do I install qikly in Claude Code?
Run claude mcp add qikly -- uvx qikly. To pin the project root, use claude mcp add --env QIKLY_PROJECT_ROOT=<QIKLY_PROJECT_ROOT> --transport stdio qikly -- uvx qikly.
What does qikly do?
It turns acceptance criteria into tests, then iterates on the code until they pass. The coding agent never receives the criteria, so the suite stays independent of the implementation.
What is needed for steps 2 and 3?
An API key from Google Gemini (there is a free tier), Anthropic or OpenAI. The --score step runs without any key.
