{
"markdown": "![\"Koda\"](\"extension/koda_logo.png\")
\n\n# Koda\n\n**Verification and memory for coding-agent workflows.** Install once, verify the changes that matter, remember what keeps breaking.\n\n   \n\n> **1,000+ downloads on Open VSX** — Koda is already watching commits in editors around the world.\n\n---\n\n| | |\n|---|---|\n| **npm** | `npm install -g koda-verify` ([npmjs.com](https://www.npmjs.com/package/koda-verify)) |\n| **IDE** | [Open VSX](https://open-vsx.org/extension/koda-dev/koda) — works in VS Code, Cursor, Windsurf, VSCodium |\n| **MCP** | [Registry](https://mcp.modelcontextprotocol.io/servers/io.github.aabxtract/koda) |\n| **Landing** | [aabxtract.github.io/koda](https://aabxtract.github.io/koda/) |\n\n## Why Koda exists\n\nCoding agents write features in minutes — but who verifies every commit? Full test suites are too slow to run per commit, so most verification happens late (or never). Koda closes that gap: **on every commit it verifies only what changed**, in seconds-to-minutes, and remembers what keeps breaking so your agent stops reintroducing old bugs.\n\nKoda never writes code. It orchestrates verification, remembers patterns, and reports — to both the human and the agent.\n\n## The three surfaces\n\n| Surface | Responsibility | Activation |\n|---|---|---|\n| **Core + CLI** | Verification, reports, memory, git hooks, CI generation | `koda init`, `koda run` |\n| **MCP server** | Agents call `koda_verify` / `koda_report` / `koda_memory` / `koda_setup_cicd` | MCP client configuration |\n| **IDE extension** | Ambient status bar, report viewer, one-click enable, Git watching | User clicks Enable |\n\n## How it works — the pipeline\n\n```\ngit commit\n │\n ▼\npre-commit ── secret guard (blocks committed API keys / private keys)\n │\n ▼\npost-commit ── koda run (background, never blocks you)\n │\n ▼\n1. Read diff ──────────── classify files: api / page / component / lib / config / test\n2. Impact analysis ────── agent-supplied (MCP) → Groq fallback → deterministic heuristics\n3. Kane browser flows ─── headless, scoped to changed UI only (page/component changes)\n4. Endpoint checks ────── GET / HEAD / OPTIONS only; regressions flagged (200 → 500)\n5. Integration tests ──── Jest / Vitest / Mocha / node:test, matched to changed files\n6. Report ─────────────── JSON (agent-readable) + Markdown (human-readable)\n7. Memory ─────────────── recurring patterns, resolution history, time-to-fix\n```\n\nMost commits never launch a browser: API/config/test-only changes verify with endpoints + tests in **seconds**. Browser flows fire only when UI files change.\n\n---\n\n## Quick start\n\n```bash\nnpm install -g koda-verify\ncd your-project\nkoda init # creates .koda/, installs git hooks, detects your app's port\nkoda doctor # verifies: git, config, Kane CLI, target URL, directories\n```\n\nThen just keep committing — verification runs in the background on every commit.\n\n### One-time browser setup (optional, per user)\n\nBrowser flows are powered by the [Kane CLI](https://www.npmjs.com/package/@testmuai/kane). The **IDE extension onboards it for you**: click *Enable* and Koda offers to install Kane and connect your account. Or do it manually:\n\n```bash\nnpm install -g @testmuai/kane-cli\nkane-cli login --oauth # opens your browser — use (or create) YOUR OWN Kane account\n```\n\n### About Kane accounts — yours, not ours\n\nKoda ships **zero credentials**. Every Koda user authenticates their **own** Kane account:\n\n- The extension's OAuth flow opens the Kane login in *your* browser; new users register there\n- Your session lives locally in `~/.testmuai/` on your machine — never synced, never proxied\n- Browser-flow credits come from *your* Kane account, not the developer's\n- In CI, each repo configures its own `KANE_USERNAME` / `KODA_ACCESS_KEY`-style secrets\n\n**No Kane? No problem.** Koda runs in degraded mode: endpoint checks, integration tests, memory, and reports all work; browser flows are honestly marked `SKIPPED` — never faked.\n\n---\n\n## Target URLs — localhost, LAN, or hosted\n\nKoda verifies whatever your app points at. The default is auto-detected at `koda init` (probes common dev ports: 3000, 5173, 8080, 8000, 4200, 5000…). Override it three ways:\n\n```bash\nkoda target https://myapp.vercel.app # permanent — hosted URL, https auto-detected\nkoda target 192.168.1.5:8080 # LAN IP, http auto-detected\nkoda run --target https://preview-123.example.com # one-off run\nKODA_TARGET=https://staging.example.com # per-session / CI via env\n```\n\nPrecedence: `--target` flag → `KODA_TARGET` env → `.koda/config.json` → auto-detected default.\n\n## CLI reference\n\n| Command | What it does |\n|---|---|\n| `koda init [--force]` | Create `.koda/`, install non-destructive git hooks, detect target |\n| `koda run [--project ] [--commit ] [--target ] [--max-flows ]` | Verify a commit now |\n| `koda report` | Show the latest report |\n| `koda memory` | Dump project memory (patterns, history, fixes) |\n| `koda target ` | Validate, save, and health-check a new target URL |\n| `koda cicd [--force]` | Generate a validated GitHub Actions workflow (refuses overwrite) |\n| `koda doctor [--kane]` | Environment check; `--kane` empirically probes the Kane schema |\n| `koda mcp` | Start the MCP server (stdio) |\n\n## Agent integration (MCP)\n\n```bash\nclaude mcp add koda -- npx koda-verify mcp\n```\n\nWorks with any MCP client: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Zed. In a development checkout: `claude mcp add koda node /absolute/path/to/koda/mcp/server.js`.\n\n### MCP tools\n\n| Tool | Purpose |\n|---|---|\n| `koda_verify` | Run focused verification. The agent **supplies its own impact analysis** (`flows`, `endpoints`, `target`, `commit`, `max_flows`) — it already read your code, so no LLM cost and no guessing. Groq is only a fallback for non-MCP runs |\n| `koda_report` | Latest full JSON report — verdicts, coverage, evidence paths |\n| `koda_memory` | Project memory — recurring failures, fix confidence, time-to-fix |\n| `koda_setup_cicd` | Generate a validated GitHub Actions workflow |\n\n### The agent loop\n\n```\nagent edits code → commits → hook fires koda run → report written\n→ agent calls koda_verify (its own flows) / koda_report via MCP\n→ reads the verdict → fixes what failed → commits again\n→ memory marks the failure RESOLVED (with time-to-fix recorded)\n```\n\nReports record `analysis_source: 'agent'` when the agent supplied flows — verifiable proof the loop is agent-driven.\n\n---\n\n## Reports\n\nEvery run writes a timestamped pair to `.koda/reports/`:\n\n```\n.koda/reports/2026-08-30T14-35-28-909Z-9416b29.json ← agent-readable\n.koda/reports/2026-08-30T14-35-28-909Z-9416b29.md ← human-readable\n```\n\nThe JSON includes: commit metadata, `analysis_source` (`agent` / `llm-fallback` / `fallback`), risk level, per-check results with evidence file paths, memory context (similar failures, patterns, fix confidence), and `action_required` with priority and suggested focus. Markdown renders PASS / FAIL / SKIPPED distinctly with coverage status.\n\nRaw Kane session events are preserved per-flow under `.koda/evidence/`.\n\n## Memory — remembers what keeps breaking\n\n- Every failed check gets a **stable key**; failures that recur 2+ times become **patterns**\n- When a fix lands and the check passes, the failure is marked **resolved** with `time_to_fix_ms`\n- Coverage-gap findings (\"no tests cover `app/page.js`\") resolve automatically once a passing test covers those files\n- Skipped checks (app offline) never pollute memory\n- Writes are atomic; corrupt memory files are quarantined, not deleted\n\n## Safety guarantees\n\n- **Non-destructive hooks** — existing pre-commit/post-commit/pre-push hooks are backed up before appending; Husky respected; idempotent via marker\n- **Read-only HTTP by default** — only GET / HEAD / OPTIONS; mutating methods require explicit opt-in (`allow_mutating_methods: true`) plus agent-declared endpoints\n- **Honest results** — if the app is down, checks are `SKIPPED`, never reported as failures; skipped checks never enter memory\n- **No secrets shipped** — the package contains zero credentials; the pre-commit guard blocks accidentally committed keys\n\n## CI/CD\n\n```bash\nkoda cicd\n```\n\nGenerates `.github/workflows/koda.yml` from a validated template: Node setup, `npm ci`, build-if-present, Kane CLI install + auth via GitHub secrets (`KANE_USERNAME`, `KANE_ACCESS_KEY`), app start, wait-on target, `koda run --commit ${{ github.sha }}`. Template-first — no LLM-generated YAML. Refuses to overwrite without `--force`.\n\n---\n\n## Configuration reference (`.koda/config.json`)\n\n```json\n{\n \"kane\": {\n \"target\": \"http://localhost:3000\",\n \"headless\": true,\n \"max_steps\": 30,\n \"timeout_ms\": 300000\n },\n \"tests\": {\n \"browser_flows\": true,\n \"endpoint_tests\": true,\n \"integration_tests\": true,\n \"allow_mutating_methods\": false,\n \"expected_statuses\": { \"GET /api/health\": [200] }\n },\n \"notify\": { \"telegram\": false, \"discord\": false }\n}\n```\n\n## Environment variables\n\nOptional — Koda works without any of these. Loaded from the project `.env`, falling back to `~/.koda/.env` (configure once, use everywhere):\n\n```bash\nGROQ_API_KEY= # Groq fallback impact analysis (agent runs skip this entirely)\nKODA_TARGET= # override target URL (flag > env > config)\nKODA_TEST_TOKEN= # bearer token for authenticated endpoint checks\nKODA_PROJECT= # default project path for CLI/MCP\nTELEGRAM_BOT_TOKEN= # notifications\nTELEGRAM_CHAT_ID=\nDISCORD_WEBHOOK_URL=\n```\n\n## Development\n\n```bash\nnpm install\nnpm run check # syntax-check all sources\nnpm test # node:test suite\nnpm link # local koda binary for development\n```\n\nSee [koda-v3-build-guide.md](./koda-v3-build-guide.md) for the full implementation contract.\n\n## License\n\nMIT\n",
"bytes": 10065,
"sha": "256bdeed7aa5fd2f269db6523081fd8562a1910a104dc99337d966102d37f554",
"repo_slug": "aabxtract/koda",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_aabxtract_koda_f190b950/readme"
}