Integrates with Windsurf (Codeium) by adding an MCP server entry to ~/.codeium/windsurf/mcp_config.json, enabling Atomic Reps to ask a question after coding tasks that change files.
Integrates with GitHub Copilot in VS Code and Copilot CLI (and other Copilot hosts via their own mcp.json). Registers the Atomic Reps MCP server so Copilot can call rep when a coding task ends and ask a multiple-choice question to the user.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@atomicreps quiz me on the React auth hook I just wrote"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
One short question about the thing you just built. Works inside Claude Code, GitHub Copilot, Cursor, Windsurf, Codex, or any MCP client.
You describe a bug, your coding agent changes the code, and Atomic Reps asks you one multiple-choice question about that change. You answer with a letter, from memory, and the server grades it.
The two-minute demo: four bugs fixed in Claude Code, one question after each.
https://github.com/user-attachments/assets/521c1bb3-9f75-4c25-8b71-ed763de7debc
Requires Node 24+ and a free account. On an older Node, every command prints the version it needs instead of starting.
npx atomicrepsThe first run is a setup wizard:
Pick what to practise, how often, and how hard.
Sign in: the terminal prints a code, and you type it at atomicreps.com/connect.
Pick your editors. connect writes only the entries you tick.
Then go back to work. When your agent finishes a task that changed files, the question appears after its answer:
Type the letter. The verdict comes back with a one-line explanation, and the next line names up to three other topics the session touched:
Every run after the first opens the terminal screen: your streak, this session, your topics, mutes and rate.
Related MCP server: spar-agent
npx atomicreps the terminal screen; the setup wizard on the first run
npx atomicreps setup the setup wizard again: areas, topics, how often, how hard
npx atomicreps login sign in from a browser with a typed code
npx atomicreps connect register the server with your editor
npx atomicreps connect --pin pin the launch args to this installed version, for a command you can commit
npx atomicreps mcp the stdio MCP server process (what the editor launches)
npx atomicreps doctor token, server ping, version, when the next rep may come, allowlist
npx atomicreps why the last ten times a question could have appeared, and why it did or did not
npx atomicreps logout forget the token on this machine
npx atomicreps logout --purge also forget your reps and status, and offer to undo connectAdd --alpha to any command to use staging. It keeps its own token and cache,
so you can be signed in to both staging and production at once.
Plain connect writes npx -y atomicreps mcp, which always resolves to
whatever is latest at launch. connect --pin writes npx -y atomicreps@<version> mcp instead, the version this CLI is running, so an
organisation can review one exact command and commit it rather than trusting
npx to fetch the same thing twice.
npx atomicreps connect offers four Claude Code rows:
Claude Code registers the server at user scope.
…and a question at the end of each turn adds a Stop hook and a
UserPromptSubmit hook to ~/.claude/settings.json. When Claude finishes a
turn that changed files, the question prints in your terminal without Claude
taking an extra turn, and the letter you type next is graded. Hooks you
already have stay.
…and allow its four tools adds rep, answer, me and settings to
permissions.allow, so the first question does not stop on a permission
prompt.
…and a Claude Code status line shows the open question under the prompt. A status line you already have keeps printing first.
Without connect, the server alone:
claude mcp add --scope user atomicreps -- npx -y atomicreps mcpnpx atomicreps connect offers VS Code and Copilot CLI as rows. Without it:
code --add-mcp '{"name":"atomicreps","type":"stdio","command":"npx","args":["-y","atomicreps","mcp"]}'
copilot mcp add atomicreps -- npx -y atomicreps mcpCopilot in JetBrains, Visual Studio, Xcode and Eclipse reads the same entry
from its own mcp.json (Settings, then MCP). A team can
commit it as .vscode/mcp.json so every clone has it:
{
"servers": {
"atomicreps": { "type": "stdio", "command": "npx", "args": ["-y", "atomicreps", "mcp"] }
}
}Copilot reads the server's instructions and calls rep when a task ends,
the same as Cursor and Codex. Approve the four tools once and they stay
approved.
connect adds one entry to ~/.cursor/mcp.json or
~/.codeium/windsurf/mcp_config.json, and runs codex mcp add for Codex.
Anything already in those files stays. By hand:
codex mcp add atomicreps -- npx -y atomicreps mcp{
"mcpServers": {
"atomicreps": { "command": "npx", "args": ["-y", "atomicreps", "mcp"] }
}
}Any other MCP client takes the same command: npx -y atomicreps mcp. The
"I'll set it up myself" row in connect prints it and writes nothing.
When your coding agent finishes a task, it calls rep once with a few words
for what changed. The server picks one question, or nothing, and your agent
shows it to you unchanged. Reply with a letter, or ignore it.
Under the verdict, one line names up to three other things the session touched. A number asks about one of them. "Never Swift" mutes a topic permanently. "Not this topic" mutes it for thirty days. "Unmute Swift" removes the mute. "How am I doing" prints your summary.
The server enforces the pace, not the agent. It sets a minimum gap between
automatic reps, a daily cap, and mute and off. It refuses an answer typed
within seconds of the question. It never includes the answer key in a rep.
Every failure returns no rep rather than an error; doctor says why.
tool | what it does |
| one question, one insight, or nothing; |
| the verdict, the explanation, and the offer line |
|
|
| the rate, the pinned topics, the difficulty range, the preferred areas, mutes, the dialog |
Handles are topic or topic.subskill (react.hooks_core). Fifty sub-skill
slugs repeat across topics, so the topic is always part of the name.
settings({ dialog: true }) asks for the letter in your editor's native
dialog instead of the chat. It blocks the turn, so it is a setting, never the
default.
What leaves your machine on a rep call: catalog handles with small weights.
Also package, file extension and folder names the public catalog already
knows. Your agent's touched words are matched to handles on your machine;
the words themselves are never sent. An unknown package name is dropped. A
private name (@acme/react-internal) is sent as its public alias (react).
We never send your code, a file's contents, or a prompt. npx atomicreps setup prints the exact payload for your repo, before you sign in.
npx atomicreps mcp forwards each JSON-RPC message from your editor to the
Atomic Reps server with your token. The answer comes back the same way.
ATOMICREPS_API is honoured only for an Atomic Reps or loopback address,
since your token goes wherever it points. Anything else is ignored and
reported by doctor; set ATOMICREPS_UNSAFE_ORIGIN=1 to override.
npx atomicreps prints a code. Type it at atomicreps.com/connect while
signed in; a forwarded link approves nothing. The token is saved in
~/.config/atomicreps/config.json (mode 0600), prefixed arep_ so secret
scanners find it. You can revoke it from your account page. logout forgets
it; logout --purge also deletes the reps and status this machine cached, then
lists every editor entry connect wrote (both channels) and removes the ones you
leave ticked.
The trust boundary, and how to report a vulnerability: SECURITY.md.
dist/cli.js is built from these files and nothing else. The package has no
runtime dependencies.
npm install
npm run build # writes dist/cli.js from src
npm test # the behaviour described above, as testsTo compare with what npm serves: npm pack atomicreps, then read its
dist/cli.js beside the one you just built. Everything the client sends is in
src/api.ts. Everything it reads from your repository is in src/infer.ts.
MIT.
Grade the user's pick for the open rep and return the verdict block.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| pick | Yes | ||
| sure | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It says it grades a pick and returns a verdict, but does not disclose whether grading is a side-effecting mutation, whether the pick is locked in, whether it requires the rep to be open, or what the 'verdict block' contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states the action and result without filler. Its brevity is a virtue, though the terseness contributes to the semantic gaps noted elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and three undocumented parameters, the description is too thin. It does not explain prerequisites, side effects, or the meaning of the verdict it returns, leaving an agent unable to call it correctly with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 3 parameters, so the description must compensate. It only loosely maps 'pick' to the user's choice; 'id' and 'sure' are entirely unexplained, and the significance of the boolean 'sure' flag is left to guesswork.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('grade') and object ('the user's pick for the open rep'), which is more informative than the bare name 'answer'. However, domain jargon like 'open rep' and 'verdict block' is left undefined, and there is no differentiation from the sibling tool 'rep'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the siblings ('rep', 'me', 'settings'), no prerequisites, and no statement of what state the tool assumes. The agent must infer that an 'open rep' must exist first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How the user is doing: summary, skills, reps, streak, or mutes, as a block.
| Name | Required | Description | Default |
|---|---|---|---|
| show | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It only says the result is 'as a block,' which hints at an aggregate return but omits read/write safety, authentication needs, side effects, or whether 'show' filters or selects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler. It is appropriately sized for a simple tool, though the leading title-like phrase is somewhat redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0% schema coverage, the description is incomplete. It should clarify how 'show' works and what the block contains, but leaves key invocation details unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single 'show' parameter is undocumented in the schema. The description implicitly lists likely values (summary, skills, reps, streak, mutes), adding useful meaning, but it does not state that these are the accepted values, nor does it cover defaults or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description lists the data categories returned (summary, skills, reps, streak, mutes) but does not use a specific verb or clearly differentiate from siblings rep, answer, and settings. An agent can infer it retrieves a user profile block, but the purpose is not sharply stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no exclusions, and no mention of alternatives like rep or settings. The agent must guess that this is the general user overview tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One rep about what was just built, or the one the user asked for by handle. Call once as the last step of a turn that changed files, before your final reply, unless the turn ends by asking the user something; uncommitted or untested work counts. Returns a block to print verbatim, or nothing. Never solve or hint at it.
| Name | Required | Description | Default |
|---|---|---|---|
| ask | No | ||
| kind | No | ||
| lane | No | ||
| topic | No | ||
| topics | No | ||
| exclude | No | ||
| touched | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does reasonably well: it discloses the return behavior ('a block to print verbatim, or nothing'), the once-per-turn call discipline, and an important constraint ('Never solve or hint at it'). It omits any mention of permissions, failure modes, or what triggers an empty return, but the behavioral profile is substantially conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is compact and the critical timing instruction is front-loaded, so little is wasted. However, the density comes at the cost of clarity — the jargon-heavy phrasing packs several conditions into one sentence and leaves the reader parsing rather than understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 undocumented parameters, no annotations, and no output schema, the description covers usage timing but leaves the parameter surface and the nature of the returned block opaque. An agent could call it at the right moment but could not reliably populate the inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% across 7 parameters, so the description must compensate and largely fails to. It only obliquely touches 'the one the user asked for by handle' (mapping loosely to lane='asked') and 'turn that changed files' (possibly 'touched'); ask, kind, topic, topics, and exclude are entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says a 'rep' is about 'what was just built' and that it returns a block to print verbatim, which hints at a generated exercise/prompt artifact. But the core noun 'rep' is never defined, and the opening clause largely restates the title. An agent can infer the shape of the output but not clearly what the tool actually produces or why.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Strong timing and conditionality: 'Call once as the last step of a turn that changed files, before your final reply, unless the turn ends by asking the user something.' It also clarifies that 'uncommitted or untested work counts,' removing a likely ambiguity. It does not name sibling tools as alternatives, but the when/when-not guidance is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set intensity, insights, a timed mute, a topic mute for days or forever, an unmute, preferred domains, strict, the dialog.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| mute | No | ||
| dialog | No | ||
| prefer | No | ||
| strict | No | ||
| unmute | No | ||
| insights | No | ||
| intensity | No | ||
| muteMinutes | No | ||
| confidencePrompt | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers very little. 'A topic mute for days or forever' hints at duration semantics, but there is no disclosure of whether settings persist across sessions, how mutes interact, what permissions are needed, or what the response looks like for a 10-parameter mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short but not concise in a useful sense: a single unpunctuated fragment listing ten loosely related knobs, with no front-loaded summary and no grouping of mute/unmute/preference behaviors. The brevity here reflects under-specification rather than efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters, zero schema coverage, no annotations, and no output schema, the one-line field list is entirely inadequate. An agent has nothing to reason about regarding defaults, mutual exclusivity (e.g., mute vs. unmute), or valid inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 10 parameters, so the description must compensate and largely fails. It echoes a subset of parameter names (intensity, mute, unmute, prefer, strict, dialog, insights) without explaining accepted values or semantics, and never clarifies the days vs. muteMinutes vs. 'forever' distinction or what confidencePrompt means.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a comma-separated list of parameter names ('intensity, insights, a timed mute...') rather than a statement of what the tool does. 'Settings' plus a field dump is effectively a restatement of the schema, and nothing distinguishes it from the siblings rep/answer/me. An agent cannot tell what operation this performs on what resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of the alternative sibling tools (rep, answer, me). The only implicit signal is the word 'Set', which implies mutation but doesn't tell the agent when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0answermerepsettingsScored across 4 tools
Each tool targets a distinct part of the workflow: rep handles the rep itself, answer grades a pick, me reports user stats, and settings configures preferences. The rep/answer boundary is clear enough from descriptions, though both revolve around the same rep concept.
All names are lowercase single words, which is readable, but they mix nouns (rep, settings), a pronoun (me), and a verb (answer). There is no consistent verb_noun or action-resource pattern across the set.
Four tools is well-scoped for this server's apparent purpose. The core loop (rep, answer) plus user status (me) and configuration (settings) each earns its place without redundancy.
The surface covers creating/receiving a rep, grading an answer, viewing user progress, and changing settings. Minor lifecycle gaps exist, such as explicit history or deletion operations, but the core interaction cycle is complete.
Build and study spaced-repetition flashcards with your agent.
One shared brain for your AI coding agents: team memory, agent Q&A, tasks, and file claims.
Files what you learn into a personal wiki and quizzes you before you forget it.
Co-Learn with your Agent: fact-checked AI lessons with Human and Agent views.
