{"_id":"@amrishkhan05/frankly","_rev":"6-01ef4ed79feb40d8cfb2a442d2b9ee01","name":"@amrishkhan05/frankly","dist-tags":{"latest":"1.0.2"},"versions":{"0.1.0":{"name":"@amrishkhan05/frankly","version":"0.1.0","keywords":["ai","code-review","mcp","claude-code","change-intelligence"],"author":{"name":"Amrish Khan","email":"amrishkhan05@gmail.com"},"license":"MIT","_id":"@amrishkhan05/frankly@0.1.0","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/frankly#readme","bugs":{"url":"https://github.com/amrishkhan05/frankly/issues"},"bin":{"frankly":"dist/integrations/cli/index.js"},"dist":{"shasum":"8af40332a6aee07f6ef3242e618c6233f4fb58b9","tarball":"https://registry.npmjs.org/@amrishkhan05/frankly/-/frankly-0.1.0.tgz","fileCount":123,"integrity":"sha512-2Urhv2g1FXKZ3eqOmQb2Q5O0jYa8bVRK6auPz5zTGr4bc8eQIJOHU6S+qa9yH6kEAZDIKehZazcAoflrJ8jH1Q==","signatures":[{"sig":"MEYCIQDgDb+IDcmd4XP4Mx0EmLQx1HSDEaFNL/IMZJKgjbl4vAIhAL5rEPUM0H51ZSpvBGCWGagTs9TpxyS73l9EreNSbsAs","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":354226},"main":"index.js","type":"module","engines":{"node":">=20"},"gitHead":"2da6c5374cfb0b403c67e2de498c76a9cef7737e","scripts":{"dev":"tsx src/integrations/cli/index.ts","mcp":"tsx src/integrations/mcp/index.ts","demo":"tsx src/integrations/cli/demo.ts","test":"vitest run","build":"tsc -p tsconfig.json","review":"tsx src/integrations/cli/index.ts review","verify":"tsx src/integrations/cli/index.ts verify","benchmark":"tsx benchmarks/run.ts","test:watch":"vitest","prepublishOnly":"npm test && npm run build"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/frankly.git","type":"git"},"_npmVersion":"10.9.3","description":"Change intelligence for AI coding agents. Every changed line should earn its place.","directories":{"doc":"docs","example":"examples"},"_nodeVersion":"22.19.0","dependencies":{"tsx":"^4.7.0","zod":"^3.22.4","typescript":"^5.3.3","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11","@types/node":"^26.4.0"},"_npmOperationalInternal":{"tmp":"tmp/frankly_0.1.0_1788241200900_0.2576753836966177","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@amrishkhan05/frankly","version":"0.1.1","keywords":["ai","code-review","mcp","claude-code","change-intelligence"],"author":{"name":"Amrish Khan","email":"amrishkhan05@gmail.com"},"license":"MIT","_id":"@amrishkhan05/frankly@0.1.1","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/frankly#readme","bugs":{"url":"https://github.com/amrishkhan05/frankly/issues"},"bin":{"frankly":"dist/integrations/cli/index.js"},"dist":{"shasum":"e7be22339ee1b49ed2aef6f8afc1178f68369861","tarball":"https://registry.npmjs.org/@amrishkhan05/frankly/-/frankly-0.1.1.tgz","fileCount":123,"integrity":"sha512-4u7G5Y09L78EuRqTlgAr25OwAbxWW7+BDdqM5Qnx7Tm6N9oVT65RpNYNiX3+Sipme8KDlrysGNXZyDurmiTGvA==","signatures":[{"sig":"MEUCIF5IgOZ6fWi94jRc3U/rMz0USRcIF8TZW8QCyGA070OeAiEAkO6CCCoot3+S4RouM+XxvYnlwuvBEyZWCHQl2gGKAqI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":354256},"main":"index.js","type":"module","engines":{"node":">=20"},"gitHead":"25ba011a2cf56bc8bbcd7808204e1d881da3ed6d","scripts":{"dev":"tsx src/integrations/cli/index.ts","mcp":"tsx src/integrations/mcp/index.ts","demo":"tsx src/integrations/cli/demo.ts","test":"vitest run","build":"tsc -p tsconfig.json","review":"tsx src/integrations/cli/index.ts review","verify":"tsx src/integrations/cli/index.ts verify","benchmark":"tsx benchmarks/run.ts","test:watch":"vitest","prepublishOnly":"npm test && npm run build"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/frankly.git","type":"git"},"_npmVersion":"10.9.3","description":"Change intelligence for AI coding agents. Every changed line should earn its place.","directories":{"doc":"docs","example":"examples"},"_nodeVersion":"22.19.0","dependencies":{"tsx":"^4.7.0","zod":"^3.22.4","typescript":"^5.3.3","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11","@types/node":"^26.4.0"},"_npmOperationalInternal":{"tmp":"tmp/frankly_0.1.1_1788241693141_0.3777459937455889","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@amrishkhan05/frankly","version":"0.1.2","keywords":["ai","code-review","mcp","claude-code","change-intelligence"],"author":{"name":"Amrish Khan","email":"amrishkhan05@gmail.com"},"license":"MIT","_id":"@amrishkhan05/frankly@0.1.2","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/frankly#readme","bugs":{"url":"https://github.com/amrishkhan05/frankly/issues"},"bin":{"frankly":"dist/integrations/cli/index.js"},"dist":{"shasum":"b5cb812feb228be312708f26eb2ccbd4251506ba","tarball":"https://registry.npmjs.org/@amrishkhan05/frankly/-/frankly-0.1.2.tgz","fileCount":123,"integrity":"sha512-xFFfxHElZhros8p3BcUpceX4lJH78Q3nQTG+nNQAIB105W5xBVckDWZBoEmEqPjFm0BYHEME4B0unDwKiTLH+A==","signatures":[{"sig":"MEQCIClUJCOoApeoJKSxuo6G/I6tEPO9VQjf0VQMu9g/kg9AAiARQit5iEazv9utY9NJUWd0xzLPM2gLUcJliusMXuA5LQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":356075},"main":"index.js","type":"module","engines":{"node":">=20"},"gitHead":"25ba011a2cf56bc8bbcd7808204e1d881da3ed6d","scripts":{"dev":"tsx src/integrations/cli/index.ts","mcp":"tsx src/integrations/mcp/index.ts","demo":"tsx src/integrations/cli/demo.ts","test":"vitest run","build":"tsc -p tsconfig.json","review":"tsx src/integrations/cli/index.ts review","verify":"tsx src/integrations/cli/index.ts verify","benchmark":"tsx benchmarks/run.ts","test:watch":"vitest","prepublishOnly":"npm test && npm run build"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/frankly.git","type":"git"},"_npmVersion":"10.9.3","description":"Change intelligence for AI coding agents. Every changed line should earn its place.","directories":{"doc":"docs","example":"examples"},"_nodeVersion":"22.19.0","dependencies":{"tsx":"^4.7.0","zod":"^3.22.4","typescript":"^5.3.3","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11","@types/node":"^26.4.0"},"_npmOperationalInternal":{"tmp":"tmp/frankly_0.1.2_1788241948201_0.8100864990661578","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@amrishkhan05/frankly","version":"1.0.0","keywords":["ai","code-review","mcp","claude-code","change-intelligence"],"author":{"name":"Amrish Khan","email":"amrishkhan05@gmail.com"},"license":"MIT","_id":"@amrishkhan05/frankly@1.0.0","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/frankly#readme","bugs":{"url":"https://github.com/amrishkhan05/frankly/issues"},"bin":{"frankly":"dist/integrations/cli/index.js"},"dist":{"shasum":"4f413b9cd070c46c31e39a19ad0fac95ed71cad2","tarball":"https://registry.npmjs.org/@amrishkhan05/frankly/-/frankly-1.0.0.tgz","fileCount":123,"integrity":"sha512-igWHwWKvJi+Huw5syksUOgjJ8nL4MDzzE3q7eZhGj1grFfg42QIAGou+vEXOmT8c6aaZIFoZ9m/rfTC96i0XkA==","signatures":[{"sig":"MEUCIA3qk08C4QkjKvfRmyQt/kXf0azskRk6W0+jK+A+52AWAiEA4V+DocOz7AH7Dr4DRgZRR0gWt4rIJp0qQR0w1igDyPQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":356965},"main":"index.js","type":"module","engines":{"node":">=20"},"gitHead":"3d8b20f4075de8c6c8ca4af9224a8087acece162","scripts":{"dev":"tsx src/integrations/cli/index.ts","mcp":"tsx src/integrations/mcp/index.ts","demo":"tsx src/integrations/cli/demo.ts","test":"vitest run","build":"tsc -p tsconfig.json","review":"tsx src/integrations/cli/index.ts review","verify":"tsx src/integrations/cli/index.ts verify","benchmark":"tsx benchmarks/run.ts","test:watch":"vitest","prepublishOnly":"npm test && npm run build"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/frankly.git","type":"git"},"_npmVersion":"10.9.3","description":"Change intelligence for AI coding agents. Every changed line should earn its place.","directories":{"doc":"docs","example":"examples"},"_nodeVersion":"22.19.0","dependencies":{"tsx":"^4.7.0","zod":"^3.22.4","typescript":"^5.3.3","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11","@types/node":"^26.4.0"},"_npmOperationalInternal":{"tmp":"tmp/frankly_1.0.0_1788242452862_0.23599972257330482","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@amrishkhan05/frankly","version":"1.0.1","keywords":["ai","code-review","mcp","claude-code","change-intelligence"],"author":{"name":"Amrish Khan","email":"amrishkhan05@gmail.com"},"license":"MIT","_id":"@amrishkhan05/frankly@1.0.1","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/frankly#readme","bugs":{"url":"https://github.com/amrishkhan05/frankly/issues"},"bin":{"frankly":"dist/integrations/cli/index.js"},"dist":{"shasum":"075579948c2732d6e40214808f678173c92c411b","tarball":"https://registry.npmjs.org/@amrishkhan05/frankly/-/frankly-1.0.1.tgz","fileCount":124,"integrity":"sha512-OseVEkj4nLmrf5ltpjsV5KGx3hNq/GuSNYfIzOhZU7KBRsbwbLz3Mw4I9nMk7/P5BqNlZ64I0Qfh8cNXUnLczw==","signatures":[{"sig":"MEYCIQDI6CH3IggGnF3zcmh91GIXyKScuj1VZ3n1AJrtN++WrgIhALOHkq0IkiQYHkkSyjzPWOBLlXPmAoHUXpztH+EH7xpD","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":356174},"main":"index.js","type":"module","engines":{"node":">=20"},"gitHead":"9a09debd20488a920d999ef6c85c4d2da0d35211","scripts":{"dev":"tsx src/integrations/cli/index.ts","mcp":"tsx src/integrations/mcp/index.ts","demo":"tsx src/integrations/cli/demo.ts","test":"vitest run","build":"tsc -p tsconfig.json","review":"tsx src/integrations/cli/index.ts review","verify":"tsx src/integrations/cli/index.ts verify","benchmark":"tsx benchmarks/run.ts","test:watch":"vitest","prepublishOnly":"npm test && npm run build"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/frankly.git","type":"git"},"_npmVersion":"10.9.3","description":"Change intelligence for AI coding agents. Every changed line should earn its place.","directories":{"doc":"docs","example":"examples"},"_nodeVersion":"22.19.0","dependencies":{"tsx":"^4.7.0","zod":"^3.22.4","typescript":"^5.3.3","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11","@types/node":"^26.4.0"},"_npmOperationalInternal":{"tmp":"tmp/frankly_1.0.1_1788254557886_0.6768546003115541","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@amrishkhan05/frankly","version":"1.0.2","description":"Change intelligence for AI coding agents. Every changed line should earn its place.","type":"module","bin":{"frankly":"dist/integrations/cli/index.js"},"scripts":{"dev":"tsx src/integrations/cli/index.ts","build":"tsc -p tsconfig.json","test":"vitest run","test:watch":"vitest","mcp":"tsx src/integrations/mcp/index.ts","review":"tsx src/integrations/cli/index.ts review","verify":"tsx src/integrations/cli/index.ts verify","demo":"tsx src/integrations/cli/demo.ts","benchmark":"tsx benchmarks/run.ts","prepublishOnly":"npm test && npm run build"},"engines":{"node":">=20"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","tsx":"^4.7.0","typescript":"^5.3.3","zod":"^3.22.4"},"devDependencies":{"@types/node":"^26.4.0","vitest":"^4.1.11"},"keywords":["ai","code-review","mcp","claude-code","change-intelligence"],"repository":{"type":"git","url":"git+https://github.com/amrishkhan05/frankly.git"},"homepage":"https://github.com/amrishkhan05/frankly#readme","bugs":{"url":"https://github.com/amrishkhan05/frankly/issues"},"license":"MIT","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"author":{"name":"Amrish Khan","email":"amrishkhan05@gmail.com"},"main":"index.js","directories":{"doc":"docs","example":"examples"},"gitHead":"f5380e81cf31192e0b64f9e78153fa68afbbe3a1","_id":"@amrishkhan05/frankly@1.0.2","_nodeVersion":"22.23.2","_npmVersion":"12.0.2","dist":{"integrity":"sha512-zci9PqF+KRT4kWdrvK4ogKg1sd3cgT09a+Hr5mg9S36G+k98uHD7MbQvftZwkiQVvGDWQkYT2c/Np3MdQ4rTrw==","shasum":"b67e0cce0f3137c980c068bc65e8725110dca2d8","tarball":"https://registry.npmjs.org/@amrishkhan05/frankly/-/frankly-1.0.2.tgz","fileCount":124,"unpackedSize":355985,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amrishkhan05%2ffrankly@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC8mgJDUjlPDv9nJ7s5XDw0b4xA4IApxssyZvVeBMHV2wIhAJ+Ca87CM2yNNwuKip25AjtEEyohLjcSqKGEREq/JZH+"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e0243a96-1bdb-4cf9-b2d0-281226bff038"}},"maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/frankly_1.0.2_1788255853217_0.10835653998701877"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-01T05:40:00.684Z","modified":"2026-09-01T09:44:13.842Z","0.1.0":"2026-09-01T05:40:01.034Z","0.1.1":"2026-09-01T05:48:13.296Z","0.1.2":"2026-09-01T05:52:28.357Z","1.0.0":"2026-09-01T06:00:53.020Z","1.0.1":"2026-09-01T09:22:38.031Z","1.0.2":"2026-09-01T09:44:13.358Z"},"bugs":{"url":"https://github.com/amrishkhan05/frankly/issues"},"author":{"name":"Amrish Khan","email":"amrishkhan05@gmail.com"},"license":"MIT","homepage":"https://github.com/amrishkhan05/frankly#readme","keywords":["ai","code-review","mcp","claude-code","change-intelligence"],"repository":{"type":"git","url":"git+https://github.com/amrishkhan05/frankly.git"},"description":"Change intelligence for AI coding agents. Every changed line should earn its place.","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"readme":"<img src=\"https://raw.githubusercontent.com/amrishkhan05/frankly/main/assets/banner.jpg\" alt=\"Frankly banner\" width=\"800\" />\n\n# Frankly\n\n#### Your AI writes code. Frankly reviews it, frankly.\n\n<div align=\"center\">\n\n[![GitHub stars](https://img.shields.io/github/stars/amrishkhan05/frankly?style=for-the-badge&logo=github)](https://github.com/amrishkhan05/frankly/stargazers)\n[![License](https://img.shields.io/github/license/amrishkhan05/frankly?style=for-the-badge)](https://github.com/amrishkhan05/frankly/blob/main/LICENSE)\n[![npm version](https://img.shields.io/npm/v/@amrishkhan05%2Ffrankly?style=for-the-badge)](https://www.npmjs.com/package/@amrishkhan05/frankly)\n\n</div>\n\n---\n\n## What is Frankly?\n\nFrankly is a **local‑first change‑intelligence engine** for coding agents. It inspects the current Git diff and your TypeScript/JavaScript project, then asks whether **every changed file and symbol earned its place**. No hidden LLM calls, no cloud dependencies – everything runs deterministically on your machine.\n\n---\n\n## Table of contents\n\n- [Quick start](#quick-start)\n- [The ten-second demo](#the-ten-second-demo)\n- [Claude Code plugin](#claude-code-plugin)\n- [Generic MCP](#generic-mcp)\n- [GitHub Copilot](#github-copilot)\n- [CLI reference](#cli-reference)\n- [MCP tool reference](#mcp-tool-reference)\n- [Configuration](#configuration)\n- [Privacy and security](#privacy-and-security)\n- [Contributing](#contributing)\n\n---\n\n## Quick start\n\n```bash\n# Clone the repo\ngit clone https://github.com/amrishkhan05/frankly.git\ncd frankly\n\n# Install dependencies (Node.js 20+ required)\nnpm install\n\n# Run the test suite\nnpm test\n\n# Build the project\nnpm run build\n```\n\nInstall the published package with `npm install @amrishkhan05/frankly`.\n\n---\n\n## Publishing the package (GitHub npm registry)\n\nYou can publish the **frankly** package to the GitHub Packages npm registry by adding a `publishConfig` entry in `package.json`:\n\n```json\n\"publishConfig\": {\n  \"registry\": \"https://npm.pkg.github.com\"\n}\n```\n\nMake sure the `repository` field matches your GitHub repository URL (e.g., `https://github.com/amrishkhan05/frankly.git`). Then run:\n\n```bash\nnpm publish\n```\n\nFor the public npm registry you can omit `publishConfig` or set `\"registry\": \"https://registry.npmjs.org/\"`.\n\n## The ten-second demo\n\n```text\nTask: Retry HTTP 429 responses\n\nFRANKLY · RED INK REVIEW\n{{ ... }}\n\nCORRECTION PASS (1/1)\nPreserve behavior and safety; remove or justify the red marks, then verify once.\n```\n\n## Claude Code plugin\n\nFrankly's public GitHub repository is also its Claude Code marketplace. Use the following commands:\n\n| Command | Description |\n|---|---|\n| `claude plugin marketplace add amrishkhan05/frankly` | Add Frankly to the Claude marketplace |\n| `claude plugin install frankly@frankly` | Install the Frankly plugin |\n\n\nThe marketplace catalog is [`.claude-plugin/marketplace.json`](https://github.com/amrishkhan05/frankly/blob/main/.claude-plugin/marketplace.json). It installs the plugin from this repository root (`\"source\": \"./\"`), which contains its manifest, MCP configuration, hooks, and skills. The plugin's explicit version is `0.1.0`; users receive future marketplace updates when that version changes.\n\nAfter an update, refresh the marketplace and plugin:\n\n| Command | Description |\n|---|---|\n| `claude plugin marketplace update frankly` | Update marketplace entry |\n| `claude plugin update frankly@frankly` | Update installed plugin |\n\n\nFor local development, validate and install the checkout as a marketplace:\n\n| Command | Description |\n|---|---|\n| `claude plugin validate .` | Validate plugin locally |\n| `claude plugin marketplace add ./` | Add current directory to marketplace |\n| `claude plugin install frankly@frankly` | Install the plugin |\n\n\nRun `/reload-plugins` when Claude Code asks for activation after installation or an update. `claude plugin list` shows the installed plugin and version.\n\nFor a one-session local checkout without marketplace installation:\n\n| Command | Description |\n|---|---|\n| `claude --plugin-dir /absolute/path/to/frankly` | Run Claude with the Frankly plugin directory |\n\n\nThe plugin bundles Frankly's MCP server and a `Stop` hook. At task completion it runs a Red Ink Review; when correction is warranted it returns exactly one constrained correction request. The second stop is allowed, preventing loops. Claude Code's current plugin layout and hook behavior are documented in the [official plugin reference](https://code.claude.com/docs/en/plugins-reference) and [hooks reference](https://code.claude.com/docs/en/hooks).\n\nThe first plugin run installs the package's declared runtime dependencies into Claude's plugin data directory. Repository analysis remains local and makes no external requests.\n\n## Generic MCP\n\nAfter building, start the stdio server with:\n\n```bash\nnode /absolute/path/to/frankly/dist/integrations/mcp/index.js\n```\n\nUse that command anywhere an MCP client accepts a local stdio server.\n\n### Codex\n\n```bash\ncodex mcp add frankly -- node /absolute/path/to/frankly/dist/integrations/mcp/index.js\n```\n\nCodex stores MCP settings in `~/.codex/config.toml` or trusted project `.codex/config.toml`, and its CLI, IDE extension, and desktop app share the configuration. See the [official OpenAI MCP documentation](https://developers.openai.com/codex/mcp).\n\nCodex does not expose Claude's Stop-hook lifecycle. Use the four MCP tools at plan, review, correction, and verification checkpoints.\n\n### Cursor\n\nCreate `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"frankly\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/frankly/dist/integrations/mcp/index.js\"]\n    }\n  }\n}\n```\n\nCursor's [current MCP documentation](https://docs.cursor.com/context/model-context-protocol) confirms project configuration at `.cursor/mcp.json`. Automatic lifecycle hooks are not assumed; invoke Frankly's tools from Agent mode.\n\n### GitHub Copilot\n\nFrankly includes a native Copilot plugin with `/frankly`, `/frankly-plan`, `/frankly-review`, `/frankly-verify`, and `/frankly-help` commands. Its manifest is at `.github/plugin/plugin.json`, with a marketplace descriptor at `.github/plugin/marketplace.json`.\n\nFor local development, build this checkout and install the repository directory with VS Code's Copilot plugin flow. The plugin registers a session-start instruction, its Frankly skill, and the slash commands. Reopen VS Code after installing or updating the plugin.\n\n```bash\nnpm install\nnpm run build\n```\n\nThis repository also includes `.vscode/mcp.json`. Copilot starts the local MCP server from `dist/integrations/mcp/index.js`, so the plugin can call `plan_change`, `analyze_change`, `minimize_change`, and `verify_change` against the current workspace.\n\nUse `/frankly-plan` before a change when scope is unclear. Use `/frankly-review` when implementation is complete, then `/frankly-verify` after the single permitted correction pass and any relevant tests.\n\n#### Copilot command reference\n\nAll commands accept a task description after the command. Give Frankly a concrete description of the requested behavior; a task such as `review` is too broad to produce useful intent evidence.\n\n| Command | Use | What Copilot does |\n| --- | --- | --- |\n| `/frankly <task>` | Run the complete change workflow. | Plans uncertain work, reviews the completed diff, permits one evidence-backed correction, and verifies the result. |\n| `/frankly-plan <task>` | Before editing when the expected scope is unclear. | Calls `plan_change` and reports likely touched areas, reusable code, expected scope, tests, and constraints. |\n| `/frankly-review <task>` | Review the current working-tree diff without changing it. | Calls `analyze_change` and reports the Red Ink verdict, findings, impact, contracts, and predicted tests. |\n| `/frankly-verify <task>` | Check the final diff after tests or a correction pass. | Calls `verify_change` and reports unresolved evidence-backed concerns. |\n| `/frankly-help` | View Frankly's workflow without reviewing or modifying the patch. | Explains the commands, the single-correction limit, and the difference between predicted and executed tests. |\n\nTypical Copilot session:\n\n```text\n/frankly-plan Retry HTTP 429 responses\n\n# Implement the requested change and run its relevant tests.\n\n/frankly-review Retry HTTP 429 responses\n\n# Only when the review has evidence-backed simplification findings:\n# make one correction pass, preserving behavior and safety.\n\n/frankly-verify Retry HTTP 429 responses\n```\n\n`/frankly-review` does not modify files. When it recommends a correction, Copilot calls `minimize_change` to obtain a constrained instruction. Frankly permits one correction pass only; it does not loop review and correction indefinitely.\n\nFrankly keeps predictions and results separate. Its related-test output identifies `LIKELY_AFFECTED` and `POSSIBLY_AFFECTED` tests. Tests are only reported as `PASSED`, `FAILED`, `SKIPPED`, or `NOT_RUN` when Copilot or the CLI supplies an actual execution result.\n\nCopilot's verified local plugin hook surface provides session-start and prompt lifecycle hooks, not a task-completion hook. Frankly therefore does not yet trigger a final review automatically in Copilot; use the slash command or have Copilot follow its session instruction. Claude Code's plugin retains its automatic Stop-hook checkpoint.\n\nIf you configure a different workspace manually, add `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"frankly\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/frankly/dist/integrations/mcp/index.js\"]\n    }\n  }\n}\n```\n\nSee GitHub's [MCP setup documentation](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp). Availability can depend on IDE and organization policy.\n\n### Kilo Code\n\nAdd to `.kilo/kilo.json`:\n\n```json\n{\n  \"mcp\": {\n    \"frankly\": {\n      \"type\": \"local\",\n      \"command\": [\"node\", \"/absolute/path/to/frankly/dist/integrations/mcp/index.js\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\nSee Kilo's [current MCP documentation](https://kilo.ai/docs/automate/mcp/using-in-kilo-code).\n\n## CLI fallback\n\nThe published `frankly` executable and the source checkout support the same subcommands. Run commands from the repository you want to analyze. The CLI reads its working-tree diff and its `frankly.config.json`.\n\n| Use case | Command |\n|---|---|\n| From a source checkout | `npm run dev -- <command> [options]` |\n| After building (package executable) | `frankly <command> [options]` |\n## CLI Reference\n\n### CLI command reference\n\n| Command | Description | Supported options |\n| --- | --- | --- |\n| `frankly help` | Prints the CLI command and option reference. Running `frankly` with no subcommand has the same result. | None. |\n| `frankly plan` | Produces a pre-change plan from the task text and local repository evidence. It estimates affected areas, reusable code, expected scope, and likely test needs. | `--task <text>` |\n| `frankly review` | Analyzes the current working-tree diff and prints a Red Ink Review. It does not modify the patch. | `--task <text>`, `--intensity <lite\\|full\\|ultra\\|off>`, `--personality <conservative\\|senior\\|witty>`, `--run-tests`, `--json`, `--markdown`, `--ci` |\n| `frankly verify` | Re-analyzes the current working-tree diff as a final verification. It exits nonzero when the verdict is not `CLEAN`. | `--task <text>`, `--intensity <lite\\|full\\|ultra\\|off>`, `--personality <conservative\\|senior\\|witty>`, `--run-tests` |\n| `frankly config` | Prints the active workspace path and Frankly's default configuration. `frankly config show` is equivalent. | `show` |\n| `frankly mcp` | Starts the stdio MCP server for an MCP-compatible client. It remains running until the client closes the connection. | None. |\n\n`--task` defaults to a generic task when omitted. Provide a concrete task description for meaningful intent matching. `--run-tests` runs the repository's `pnpm test`, `yarn test`, or `npm test` command and records that one real result. `--ci` emits CI JSON and exits nonzero unless the verdict is `CLEAN`. `--json` and `--markdown` apply to `review`; terminal output is the default.\n\nExamples:\n\n```bash\nnpm run dev -- plan --task \"Retry HTTP 429 responses\"\nnpm run review -- --task \"Retry HTTP 429 responses\"\nnpm run review -- --task \"Retry HTTP 429 responses\" --run-tests\nnpm run review -- --task \"Retry HTTP 429 responses\" --json\nnpm run review -- --task \"Retry HTTP 429 responses\" --markdown\nnpm run review -- --task \"Retry HTTP 429 responses\" --ci\nnpm run verify -- --task \"Retry HTTP 429 responses\" --run-tests\nnpm run dev -- config show\nnpm run dev -- help\n```\n\nCLI review is advisory by default. `--ci` exits non-zero for a non-clean verdict.\n\n### npm scripts\n\n| Script | Description |\n| --- | --- |\n| `npm run dev -- <command>` | Runs the CLI directly from TypeScript without building `dist/`. |\n| `npm run build` | Compiles TypeScript into `dist/`. Required before the bundled MCP configuration can start the server. |\n| `npm test` | Runs the full Vitest suite. |\n| `npm run test:watch` | Runs Vitest in watch mode. |\n| `npm run mcp` | Starts the MCP server directly from TypeScript. |\n| `npm run review -- [options]` | Shorthand for `frankly review`. |\n| `npm run verify -- [options]` | Shorthand for `frankly verify`. |\n| `npm run demo` | Creates and analyzes the bundled retry-429 fixture in a temporary Git repository. |\n| `npm run benchmark` | Runs the local benchmark harness using `benchmarks/tasks.example.json`. |\n\n## MCP tool reference\n\nThe MCP server exposes four tools. `task` is required for every tool. `repositoryRoot` is optional and defaults to the server's current working directory.\n\n| Tool | Use | Inputs | Output |\n| --- | --- | --- | --- |\n| `plan_change` | Before editing when scope is uncertain. | `task`, optional `repositoryRoot` | Expected scope, likely areas, reuse candidates, confidence, and concerns. |\n| `analyze_change` | Review the current diff. | `task`, optional `repositoryRoot`, `intensity`, `personality`, `executedTests` | Full Red Ink Review, findings, impact, contracts, predicted tests, and any correction guidance. |\n| `minimize_change` | Obtain the one permitted evidence-backed correction instruction after a review recommends it. | `task`, optional `repositoryRoot` | One correction instruction, or confirmation that no correction is warranted. |\n| `verify_change` | Verify the final diff after the correction pass and relevant tests. | `task`, optional `repositoryRoot`, `executedTests` | `CLEAN` confirmation or unresolved concerns. |\n\nFor `analyze_change` and `verify_change`, `executedTests` is an optional list of `{ path, name, status, duration? }` objects. Valid statuses are `PASSED`, `FAILED`, `SKIPPED`, and `NOT_RUN`.\n\nThe normal sequence is `plan_change` (when needed), `analyze_change`, one optional `minimize_change` correction, then `verify_change`.\n\nPredicted tests are `LIKELY_AFFECTED` or `POSSIBLY_AFFECTED`. Executed tests are only `PASSED`, `FAILED`, `SKIPPED`, or `NOT_RUN` when the caller supplies or the CLI records an actual run.\n\n## Configuration\n\nFrankly reads one repository format: `frankly.config.json`.\n\n```json\n{\n  \"trigger\": \"checkpoint\",\n  \"action\": \"correct\",\n  \"intensity\": \"full\",\n  \"personality\": \"senior\",\n  \"maxCorrectionPasses\": 1\n}\n```\n\nInvocation options override repository settings, which override defaults. Personality changes wording only; it does not change findings or severity.\n\n## Scoring\n\nChange Necessity is the percentage of classified changes with direct, supporting, test, or generated evidence, minus five points for each visible medium/high-confidence finding. Change Surface combines non-generated files, changed symbols, exported contracts, and cross-package impact. Scope Drift is the share of changed files classified as suspicious.\n\nThese are explainable heuristics, not universal measures. Read the findings and evidence before the number.\n\n## Test impact and false positives\n\nFrankly predicts related tests from import edges, changed-symbol references, and naming proximity. It does not claim coverage or failure without an executed result. Low-confidence guesses are not promoted to hard conclusions.\n\nThe v0.1 graph follows relative TypeScript/JavaScript imports. Package-alias resolution, runtime route graphs, coverage ingestion, and historical co-change weighting are future work; add them when fixtures demonstrate a credible improvement.\n\n## Benchmarks\n\n```bash\nnpm run benchmark\n```\n\nThe harness records measured files, changed lines, symbols, findings, drift, verdict, and duration for cases in `benchmarks/tasks.example.json`. No improvement percentage is claimed until agent-alone and agent-plus-Frankly runs are reproducibly measured.\n\n`npm run demo` executes the deliberately broad retry-429 candidate in [fixtures/retry-429](fixtures/retry-429) and shows the evidence Frankly reports.\n\n## Privacy and security\n\n- no account, telemetry, embeddings, vector database, code upload, or external AI API\n- Git commands use argument arrays rather than interpolated shell commands\n- optional `--run-tests` executes the repository's own test script\n- plugin bootstrap contacts npm only to install declared runtime dependencies\n\nSee [SECURITY.md](SECURITY.md).\n\n## Architecture\n\n```mermaid\ngraph LR\n    A[Git diff + task + TS/JS source] --> B[Deterministic engine]\n    B --> C[Evidence‑backed review]\n    C --> D1[Claude]\n    C --> D2[Generic MCP]\n    C --> D3[CLI/CI]\n```\n\nOne engine, thin adapters, no daemon, no database, no hidden model.\n\n## Roadmap\n\n- validate package aliases and framework-specific runtime boundaries with fixtures\n- ingest Jest/Vitest/Nx related-test output instead of only the repository test script\n- add historical before/after benchmark cases\n- publish the npm package and Claude marketplace listing\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Frankly is MIT licensed.\n\n## Author\n\nFrankly is created by Amrishkhan Sheik Abdullah.\n\n- GitHub: [@amrishkhan05](https://github.com/amrishkhan05)\n- Website: [amrishkhan.dev](https://amrishkhan.dev)\n","readmeFilename":"README.md"}