# did-it

**Stop letting coding agents congratulate themselves.**

When a coding agent finishes a task, you review a summary the agent wrote about itself. Research on 5,851 real developer sessions found that those self-reports referred to about **one action in eleven** — and a reader working from the report alone recovered roughly **a fifth of the action log** ([arXiv:2609.12205](https://arxiv.org/abs/2609.12205)).

`did-it` is the missing gate: an **autonomous self-auditing MCP server**. The agent must call `verify_claimed_actions` against your Git working tree **before** it is allowed to say "Done." Ghost claims are a hard rejection. The user never sees a victory lap that Git cannot back.

```
Agent finishes coding
        ↓
.cursorrules mandates verify_claimed_actions
        ↓
MCP tool checks git status / diff
        ↓
Ghost claims → 🛑 hard rejection (fix or admit failure)
Verified    → ✅ completion allowed
```

---

## 30-second verification

```bash
git clone https://github.com/preprint-labs/did-it.git
cd did-it
npm install
npm test
npm run build
node dist/index.js --cli --text "I created src/index.ts"
```

You should see a receipts table, an honesty score, and `can_report_completion: true|false`. Exit code `1` means a ghost claim.

---

## Install in Cursor (mcp.json)

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (user):

```json
{
  "mcpServers": {
    "did-it": {
      "command": "node",
      "args": ["<FULL_PATH_TO_DID_IT>/dist/index.js"]
    }
  }
}
```

Point `args` at your built `dist/index.js`. Windows example: `"C:\\path\\to\\did-it\\dist\\index.js"`. In this repo, `.cursor/mcp.json` uses a **relative** `dist/index.js` so no machine-specific absolute path is committed.

The server audits **`process.cwd()`** of the host workspace (the project the agent is editing), not the did-it repo itself. Override with `DID_IT_WORKSPACE` if needed.

### 2-line rule (paste into `.cursorrules`)

```
Before declaring a task complete or outputting your final summary, you MUST call `verify_claimed_actions` with a list of all changes you claim to have made. If any ghost claims are flagged, you must execute the missing changes before responding to the user.
```

---

## Claude Code

```bash
claude mcp add did-it -- node "<FULL_PATH_TO_DID_IT>/dist/index.js"
```

Or in `~/.claude.json` / project MCP config:

```json
{
  "mcpServers": {
    "did-it": {
      "command": "node",
      "args": ["<FULL_PATH_TO_DID_IT>/dist/index.js"]
    }
  }
}
```

Windows example: `"C:\\path\\to\\did-it\\dist\\index.js"`.

Add the same 2-line rule to `CLAUDE.md`.

---

## GitHub Copilot (VS Code)

`mcp.json` in `.vscode/mcp.json` or your Copilot MCP settings:

```json
{
  "servers": {
    "did-it": {
      "command": "node",
      "args": ["<FULL_PATH_TO_DID_IT>/dist/index.js"]
    }
  }
}
```

---

## MCP tools

| Tool | What it does |
| --- | --- |
| `verify_claimed_actions({ claims: string[] })` | Audit claimed edits/creates/deletes/installs against `git status --porcelain`, `git diff --name-only`, and `git diff --staged --name-only`. Ghost claims return a **hard rejection**. |
| `inspect_actual_changes()` | Raw list of files that actually changed. Use this instead of guessing. |

Hard rejection text:

> 🛑 [did-it Verification Failed]: You claimed to have completed tasks that have zero evidence in Git: ${ghost_claims}. You are PROHIBITED from reporting completion to the user until these actions are physically executed or explicitly admitted as failed.

`honesty_score` is `verified / (verified + ghost)` in `[0.0, 1.0]`. `UNVERIFIABLE` rows (e.g. "ran tests" with no artifact) are shown but excluded. `can_report_completion` is **true** iff there are **zero** ghost claims.

---

## CLI fallback

MCP is primary. For a one-off local audit:

```bash
node dist/index.js --cli
node dist/index.js --cli --text "I updated src/index.ts and created src/ghost.ts"
echo "created README.md" | node dist/index.js --cli
```

`--cli` with no claims prints the real uncommitted file list. `--root <path>` sets the workspace.

---

## Cite

```bibtex
@article{kraishan2026plans,
  title   = {Plans They Abandon, Reports They Author: The Narrative Layer of Autonomous Agents},
  author  = {Kraishan, Obada and Jitkajornwanich, Kulsawasd},
  journal = {arXiv preprint arXiv:2609.12205},
  year    = {2026}
}
```

## License

MIT