@prowi/deskcheck 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prowi ApS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# deskcheck
+
+Modular code review powered by Claude. Define what to check as markdown, deskcheck runs each check in a fresh AI agent, and aggregates the findings.
+
+![Run overview](docs/screenshots/run-overview.png)
+
+## Why deskcheck?
+
+Traditional code review tools leave a gap:
+
+- **Tests** verify behavior — they can't tell you "this controller has business logic that belongs in a service"
+- **Linters** verify syntax — they can't tell you "this endpoint is missing input validation"
+- **A single LLM** reviewing a whole branch suffers **context rot** — as its context fills up, it starts missing the patterns it's supposed to catch
+
+Deskcheck solves this by breaking every review into the smallest possible unit: **one file + one criterion + one fresh agent**. Each agent gets a clean context with only the code it needs and the specific rules to check. Results are aggregated mechanically.
+
+```
+Your code + Criteria → N executor agents → Aggregated findings
+                        (fresh context each)
+```
+
+## Quick Start
+
+```bash
+# Install
+npm install -g @prowi/deskcheck
+
+# Initialize in your project (creates criteria directory + config)
+deskcheck init
+
+# Review your branch changes against main
+deskcheck diff main
+
+# Review a specific file
+deskcheck "src/services/PaymentService.ts"
+
+# Open the web dashboard
+deskcheck serve
+```
+
+## How It Works
+
+### 1. You define criteria as markdown
+
+Each criterion is a markdown file with YAML frontmatter that says **what to check**, **which files to check**, and **how important it is**:
+
+```yaml
+---
+description: "Checks for common security vulnerabilities"
+severity: critical
+globs:
+  - "src/**/*.ts"
+  - "!src/**/*.test.ts"
+model: sonnet
+---
+
+You are a security reviewer. Check for:
+
+1. **Hardcoded secrets** — API keys, passwords, tokens in source code
+2. **SQL injection** — string concatenation in database queries
+3. **Missing input validation** — user input used without sanitization
+
+For each issue, report the severity, file, line number, and a fix suggestion.
+```
+
+Put criteria in `deskcheck/criteria/` — organize them however you like:
+
+```
+deskcheck/criteria/
+├── security/
+│   └── input-validation.md
+├── architecture/
+│   └── separation-of-concerns.md
+└── best-practices/
+    └── error-handling.md
+```
+
+### 2. Deskcheck matches criteria to your files
+
+Each criterion has `globs` that define which files it applies to. When you run `deskcheck diff main`, it gets the list of changed files and matches them against every criterion's globs. Each match becomes a **task**: one file + one criterion.
+
+### 3. Each task runs in a fresh agent
+
+Every task is executed by a new Claude agent with only:
+- The file content (or diff)
+- The criterion's instructions
+- Access to read tools (Read, Glob, Grep) for additional context
+
+No context leakage between tasks. A fresh agent reviewing one file against one set of rules catches issues with near-100% reliability.
+
+### 4. Findings are aggregated
+
+Results are grouped by file, criterion, and severity. You can browse them in the terminal, as markdown (for PR comments), as JSON (for tooling), or in the **web dashboard**:
+
+![File detail view](docs/screenshots/file-detail.png)
+
+## CLI Commands
+
+### `deskcheck diff [git-args...]`
+
+Deterministic review of git changes. No LLM planner — passes args directly to `git diff`.
+
+```bash
+deskcheck diff main                       # Changes vs main
+deskcheck diff --staged                   # Staged changes only
+deskcheck diff HEAD~3                     # Last 3 commits
+deskcheck diff main -- src/services/      # Scoped to a directory
+deskcheck diff main --dry-run             # Preview plan without executing
+deskcheck diff main --fail-on=critical    # Exit 1 if critical findings (for CI)
+deskcheck diff main --format=markdown     # Markdown output (for PR comments)
+```
+
+### `deskcheck "<prompt>"`
+
+Natural language review — an LLM agent interprets what you want to check.
+
+```bash
+deskcheck "src/services/OrderService.ts"
+deskcheck "check the auth module"
+deskcheck "the calculate method in Commission.ts"
+```
+
+### `deskcheck serve`
+
+Web dashboard with live updates. Shows all runs, task progress, usage/cost tracking, and findings with filtering.
+
+```bash
+deskcheck serve              # Start on default port (3000)
+deskcheck serve --port 8080  # Custom port
+```
+
+### `deskcheck show [plan-id]`
+
+Display results in the terminal.
+
+```bash
+deskcheck show                        # Latest run
+deskcheck show --format=markdown      # As markdown
+deskcheck show --format=json          # As JSON
+deskcheck show --fail-on=warning      # Exit 1 if warnings or worse
+```
+
+### `deskcheck watch [plan-id]`
+
+Live terminal tree view of a run in progress.
+
+### `deskcheck list`
+
+List all runs with status and finding counts.
+
+### `deskcheck init`
+
+Scaffold config and criteria directory for a new project.
+
+## Web Dashboard
+
+Start with `deskcheck serve` and open `http://localhost:3000`.
+
+**Run overview** — progress bar, usage/cost tracking, sortable task table with severity filters, and file coverage:
+
+![Run overview](docs/screenshots/run-overview.png)
+
+**File detail** — click any file to see all findings across criteria, with severity filtering and grouping options:
+
+![File detail](docs/screenshots/file-detail.png)
+
+The dashboard uses SSE for live updates — watch tasks complete in real time during execution.
+
+## Criterion Reference
+
+### Frontmatter Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `description` | Yes | — | Human-readable description shown in reports |
+| `severity` | Yes | — | Importance: `critical`, `high`, `medium`, `low` |
+| `globs` | Yes | — | File patterns to match. Prefix with `!` to exclude |
+| `mode` | No | `"One task per file"` | How to split files into tasks (natural language) |
+| `model` | No | `"haiku"` | Claude model: `haiku`, `sonnet`, `opus` |
+
+### Choosing the Right Model
+
+| Use Case | Model | Why |
+|----------|-------|-----|
+| Simple patterns (naming, imports, console.log) | `haiku` | Fast and cheap |
+| Architectural judgment (separation of concerns, DTOs) | `sonnet` | Good reasoning at moderate cost |
+| Security analysis, complex data flow | `opus` | Deep analysis for high-stakes checks |
+
+### The Detective Prompt
+
+The markdown body below the frontmatter is the **detective prompt** — instructions given to each executor agent. Include:
+
+- **What to check** — specific patterns and violations
+- **What NOT to check** — exclusions to reduce false positives
+- **Severity guidance** — when to report critical vs warning vs info
+
+The agent has read access to the project, so your prompt can reference other files:
+
+```markdown
+Read `.eslintrc.js` to understand the project's linting config.
+Then check for architectural patterns that ESLint can't catch.
+```
+
+## Configuration
+
+Configuration lives in `.deskcheck/config.json` (created by `deskcheck init`):
+
+```json
+{
+  "modules_dir": "deskcheck/criteria",
+  "storage_dir": ".deskcheck/runs",
+  "shared": {
+    "allowed_tools": ["Read", "Glob", "Grep"],
+    "mcp_servers": {}
+  },
+  "agents": {
+    "planner": { "model": "haiku" },
+    "executor": {},
+    "evaluator": { "model": "haiku" }
+  }
+}
+```
+
+The executor **model** comes from each criterion's `model` field, not from config. This lets cheap checks use `haiku` and important checks use `sonnet`.
+
+## CI Integration
+
+Use `--fail-on` to gate your pipeline:
+
+```bash
+# Fail if any critical findings
+deskcheck diff $BASE_BRANCH --fail-on=critical
+
+# Output as markdown for PR comments
+deskcheck diff $BASE_BRANCH --format=markdown > review.md
+gh pr comment $PR_NUMBER --body "$(cat review.md)"
+```
+
+Exit codes: `0` = no findings matching threshold, `1` = findings exceed threshold.
+
+## MCP Server
+
+Deskcheck can run as an MCP server for Claude Code integration:
+
+```json
+{
+  "mcpServers": {
+    "deskcheck": {
+      "command": "npx",
+      "args": ["deskcheck-mcp"]
+    }
+  }
+}
+```
+
+## Usage Tracking
+
+Every run tracks token usage and cost per task. The web dashboard shows totals (cost, input/output tokens) and per-task breakdowns, so you can see exactly how much each review costs and which criteria are most expensive.
+
+## Disclaimer
+
+This tool was vibe-coded in a single day using [Claude Code](https://claude.ai/claude-code). The architecture, implementation, web UI, and even this README were built through conversation with Claude Opus 4.6. It works, we use it, but it hasn't been battle-tested at scale. Expect rough edges. Contributions welcome.
+
+## License
+
+MIT

package/build/agents/executor-prompt.d.ts

@@ -0,0 +1,10 @@
+import type { ReviewTask } from "../core/types.js";
+/**
+ * Build the system prompt for an executor agent.
+ *
+ * The executor receives a single deskcheck task containing the detective prompt
+ * (from the criterion), the files to check, and the extracted context
+ * (diff, file content, or symbol). It outputs a JSON array of findings to stdout.
+ */
+export declare function buildExecutorPrompt(task: ReviewTask): string;
+//# sourceMappingURL=executor-prompt.d.ts.map

package/build/agents/executor-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor-prompt.d.ts","sourceRoot":"","sources":["../../src/agents/executor-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CA4B5D"}

package/build/agents/executor-prompt.js

@@ -0,0 +1,65 @@
+/**
+ * Build the system prompt for an executor agent.
+ *
+ * The executor receives a single deskcheck task containing the detective prompt
+ * (from the criterion), the files to check, and the extracted context
+ * (diff, file content, or symbol). It outputs a JSON array of findings to stdout.
+ */
+export function buildExecutorPrompt(task) {
+    const sections = [];
+    sections.push("You are a code review executor. Your job is to review code and report findings.");
+    // Criterion instructions (the detective prompt from the criterion)
+    sections.push(`## Review Instructions\n${task.prompt ?? "No instructions provided."}`);
+    // Files under review
+    const fileList = task.files.map((f) => `- ${f}`).join("\n");
+    sections.push(`## Files Under Review\n${fileList}`);
+    // Scope hint
+    sections.push(`## Scope Hint\n${task.hint ?? "No specific hint."}`);
+    // Review context
+    const contextHeader = `## Review Context\n**Context Type:** ${task.context_type}`;
+    const symbolLine = task.symbol ? `\n**Symbol:** ${task.symbol}` : "";
+    const contextBody = task.context ?? "No context provided.";
+    sections.push(`${contextHeader}${symbolLine}\n\n${contextBody}`);
+    // Instructions based on context type
+    sections.push(buildContextTypeGuidance(task.context_type));
+    // Output format instructions
+    sections.push(buildOutputInstructions());
+    return sections.join("\n\n");
+}
+/** Guidance on how to review based on the context type. */
+function buildContextTypeGuidance(contextType) {
+    const header = "## How to Review Based on Context Type";
+    switch (contextType) {
+        case "diff":
+            return `${header}\nYou are reviewing a **diff**. Focus on the changes — look at what was added, removed, or modified. Evaluate whether the changes are correct, follow best practices, and don't introduce regressions.`;
+        case "file":
+            return `${header}\nYou are reviewing **full file contents**. Review the code holistically — check structure, patterns, naming, potential bugs, and adherence to best practices.`;
+        case "symbol":
+            return `${header}\nYou are reviewing a **specific symbol** (function, class, or method). Focus on the named symbol — its implementation, correctness, error handling, and adherence to conventions.`;
+        default:
+            return `${header}\nReview the provided context for correctness and best practices.`;
+    }
+}
+/** Instructions for the executor's output format. */
+function buildOutputInstructions() {
+    return `## Your Task
+1. Read the review instructions carefully
+2. Analyze the code provided in the context
+3. Report findings as a JSON array to stdout
+
+Output ONLY a JSON array of findings. Each finding:
+\`\`\`json
+{"severity": "critical|warning|info", "file": "path", "line": null, "description": "...", "suggestion": null}
+\`\`\`
+
+- \`severity\`: "critical" for bugs/security issues, "warning" for code quality problems, "info" for suggestions
+- \`file\`: the file path where the issue was found
+- \`line\`: line number if applicable, or null
+- \`description\`: clear description of the issue
+- \`suggestion\`: suggested fix or improvement, or null
+
+If no issues found, output an empty array: []
+
+Do NOT output any text outside the JSON array. No explanations, no markdown, no commentary — just the JSON array.`;
+}
+//# sourceMappingURL=executor-prompt.js.map

package/build/agents/executor-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor-prompt.js","sourceRoot":"","sources":["../../src/agents/executor-prompt.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAgB;IAClD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,QAAQ,CAAC,IAAI,CAAC,iFAAiF,CAAC,CAAC;IAEjG,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,2BAA2B,IAAI,CAAC,MAAM,IAAI,2BAA2B,EAAE,CAAC,CAAC;IAEvF,qBAAqB;IACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,0BAA0B,QAAQ,EAAE,CAAC,CAAC;IAEpD,aAAa;IACb,QAAQ,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,IAAI,mBAAmB,EAAE,CAAC,CAAC;IAEpE,iBAAiB;IACjB,MAAM,aAAa,GAAG,wCAAwC,IAAI,CAAC,YAAY,EAAE,CAAC;IAClF,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,IAAI,sBAAsB,CAAC;IAC3D,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,GAAG,UAAU,OAAO,WAAW,EAAE,CAAC,CAAC;IAEjE,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAE3D,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEzC,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,2DAA2D;AAC3D,SAAS,wBAAwB,CAAC,WAAmB;IACnD,MAAM,MAAM,GAAG,wCAAwC,CAAC;IAExD,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,GAAG,MAAM,wMAAwM,CAAC;QAC3N,KAAK,MAAM;YACT,OAAO,GAAG,MAAM,gKAAgK,CAAC;QACnL,KAAK,QAAQ;YACX,OAAO,GAAG,MAAM,oLAAoL,CAAC;QACvM;YACE,OAAO,GAAG,MAAM,mEAAmE,CAAC;IACxF,CAAC;AACH,CAAC;AAED,qDAAqD;AACrD,SAAS,uBAAuB;IAC9B,OAAO;;;;;;;;;;;;;;;;;;kHAkByG,CAAC;AACnH,CAAC"}

package/build/agents/orchestrator.d.ts

@@ -0,0 +1,52 @@
+import type { ReviewConfig, TaskUsage } from "../core/types.js";
+/** Events yielded by the orchestrator's execute() async generator. */
+export type OrchestratorEvent = {
+    type: "task_started";
+    taskId: string;
+    reviewId: string;
+    model: string;
+    files: string[];
+} | {
+    type: "task_completed";
+    taskId: string;
+    reviewId: string;
+    files: string[];
+    findingCount: number;
+    usage: TaskUsage | null;
+} | {
+    type: "task_error";
+    taskId: string;
+    reviewId: string;
+    files: string[];
+    error: string;
+} | {
+    type: "batch_progress";
+    completed: number;
+    total: number;
+} | {
+    type: "complete";
+    totalFindings: number;
+};
+/**
+ * Executes a review plan by dispatching tasks to executor agents via the
+ * Claude Agent SDK and collecting their findings.
+ *
+ * Uses an async generator to yield progress events, allowing callers to
+ * react to task starts, completions, errors, and overall progress in real time.
+ */
+export declare class ReviewOrchestrator {
+    private readonly config;
+    private readonly projectRoot;
+    constructor(config: ReviewConfig, projectRoot: string);
+    /**
+     * Execute all pending tasks in a plan.
+     *
+     * Runs up to `maxConcurrent` executor agents at a time using a concurrency
+     * pool. Each executor receives a system prompt built from the task, uses
+     * the Claude Agent SDK to analyze the code, and outputs findings as JSON.
+     */
+    execute(planId: string, options?: {
+        maxConcurrent?: number;
+    }): AsyncGenerator<OrchestratorEvent>;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/build/agents/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agents/orchestrator.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,YAAY,EAEZ,SAAS,EACV,MAAM,kBAAkB,CAAC;AAM1B,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC1F;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE,GAC5H;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxF;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AA2IhD;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM;IAKrD;;;;;;OAMG;IACI,OAAO,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,cAAc,CAAC,iBAAiB,CAAC;CAqOrC"}