diffcop 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Estrada
+
+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

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+<!--
+README strategy: this file is for humans deciding whether to use diffcop and getting it running.
+- Open with what it is and why in one or two sentences, then a quick start that works when you paste it.
+- Show usage by example, not by listing every flag. `diffcop review --help` holds the full reference.
+- Give contributors only the single entry point (`bun run check`). Scripts and config files document themselves.
+- Agent instructions go in AGENTS.md. Don't duplicate them here.
+- If a section grows past a screen, move it to its own doc and link it.
+-->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/branding/lockup-dark.svg">
+    <img src="docs/branding/lockup.svg" alt="diffcop" width="324">
+  </picture>
+</p>
+
+# diffcop
+
+An opinionated, local-first AI code reviewer that runs on the coding agent you already use.
+
+diffcop reviews your branch from the terminal through an agent harness, using the subscription
+you already pay for, so a review doesn't have to cost you API tokens. It supports Claude Code
+today, and support for [Pi](https://github.com/earendil-works/pi),
+[Codex](https://github.com/openai/codex) and [OpenCode](https://opencode.ai) is planned.
+
+The agent reviews your diff with read-only tools, a second pass double-checks every finding, and
+the same review can run on every pull request as a [GitHub Action](#github-action).
+
+## Quick start
+
+Requires [Bun](https://bun.com) and [Claude Code](https://claude.com/product/claude-code) logged in
+with your subscription. Where you can't log in, run `claude setup-token` to get a long-lived token
+for your subscription and set it as `CLAUDE_CODE_OAUTH_TOKEN`. To pay per token instead, set
+`ANTHROPIC_API_KEY`.
+
+```bash
+cd your-repo
+bunx diffcop review "review this code"
+```
+
+To keep `diffcop` on your PATH, install it with `bun add --global diffcop`. It runs on Bun, so
+`npx diffcop` works only where Bun is installed.
+
+## Usage
+
+```bash
+diffcop review "focus on error handling"
+diffcop review "review this code" --base origin/develop   # default: origin/HEAD, then main
+diffcop review "review this code" --cwd ../other-repo
+diffcop review "quick pass" --effort low                  # faster, shallower review
+diffcop review "review this code" --reporter json | jq .findings
+```
+
+`diffcop review --help` lists every option.
+
+diffcop warns when a diff is too big to review well (over 1,000 changed lines or 20 files, not
+counting lockfiles) and suggests splitting it. Change the limits with `--maxLines` and
+`--maxFiles`.
+
+## GitHub Action
+
+The action reviews each pull request and keeps the result in a single PR comment.
+
+Run `claude setup-token` to get a token for your Claude subscription and add it as a
+`CLAUDE_CODE_OAUTH_TOKEN` repo secret, or add an `ANTHROPIC_API_KEY` secret to pay per token. Then
+add this workflow:
+
+```yaml
+# .github/workflows/review.yml
+name: Review
+
+on:
+  pull_request:
+    # edited covers a retargeted base; other edits are skipped below.
+    types: [opened, synchronize, reopened, ready_for_review, edited]
+
+concurrency:
+  # A title or body edit gets its own group so it can't cancel a running review.
+  group: review-${{ github.event.action == 'edited' && !github.event.changes.base && github.run_id || github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    # Fork PRs don't get secrets, so there's nothing to authenticate with.
+    if: ${{ !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository && (github.event.action != 'edited' || github.event.changes.base) }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0 # diffcop needs the merge base with the PR's base branch
+          persist-credentials: false
+
+      - uses: BrianEstrada/diffcop@main
+        with:
+          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+```
+
+| Input                     | Default                                                              | Description                                           |
+| ------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
+| `anthropic-api-key`       |                                                                      | Set this or `claude-code-oauth-token`.                |
+| `claude-code-oauth-token` |                                                                      | From `claude setup-token`, for Claude subscriptions.  |
+| `github-token`            | `github.token`                                                       | Reads the PR and posts the comment.                   |
+| `prompt`                  | Review this pull request for bugs, security issues, and regressions. | What to ask the reviewer.                             |
+| `effort`                  | `high`                                                               | `low` to `max`. Empty uses Claude Code's default.     |
+| `debug`                   | `false`                                                              | Also log the reviewer's tool calls and thinking time. |
+
+The action installs Bun, Node and pnpm on the runner, so later steps in the same job see those
+versions.
+
+## How a review works
+
+The first pass looks for bugs the diff introduced, plus a few nits, and on a PR checks that the
+description matches the code. A second, fresh session then tries to disprove each finding, and
+only what survives is reported.
+
+The review opens with one headline:
+
+- 🔴 **N issues found**: high or medium bugs the diff introduced.
+- 🟡 **Description doesn't match the diff**: the PR claims something the code doesn't do.
+- 🟡 **Only nits**: nothing serious.
+- ✅ **All good**: nothing found.
+
+Below it, collapsible sections list the findings, bugs that predate the diff, what verification
+dropped and why, and the files the reviewer read.
+
+On a PR, the reviewer also sees the title, description, labels, comments and reviews, sanitized
+before they reach the prompt. It treats the description as the author's claims, not as proof.
+
+## Contributing
+
+`bun install` also sets up the git hooks. Run `bun run check` (typecheck, lint, format, tests)
+before you open a PR. CI runs the same check on every PR.
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org), e.g.
+`feat(cli): add --json flag`. The commit-msg hook runs commitlint and rejects anything else.

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "diffcop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An opinionated, local-first AI code reviewer that runs on the coding agent you already use.",
+  "keywords": [
+    "ai",
+    "claude-code",
+    "cli",
+    "code-review"
+  ],
+  "homepage": "https://github.com/BrianEstrada/diffcop#readme",
+  "bugs": "https://github.com/BrianEstrada/diffcop/issues",
+  "license": "MIT",
+  "author": "Brian Estrada",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrianEstrada/diffcop.git"
+  },
+  "bin": {
+    "diffcop": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "tsconfig.json"
+  ],
+  "type": "module",
+  "imports": {
+    "#package.json": "./package.json"
+  },
+  "scripts": {
+    "diffcop": "bun src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "check": "bun run typecheck && bun run lint && bun run fmt:check && bun test --pass-with-no-tests",
+    "changelog": "if grep -qF \"## [$npm_package_version]\" CHANGELOG.md; then echo \"CHANGELOG.md already has $npm_package_version\"; exit 1; fi; git-cliff --unreleased --tag v$npm_package_version --prepend CHANGELOG.md && oxfmt CHANGELOG.md",
+    "release-notes": "git-cliff --unreleased --strip all"
+  },
+  "dependencies": {
+    "@ai-sdk/harness": "1.0.148",
+    "@ai-sdk/harness-claude-code": "1.0.152",
+    "@ai-sdk/provider-utils": "5.0.58",
+    "@octokit/core": "7.0.8",
+    "@octokit/plugin-paginate-rest": "16.0.0",
+    "@octokit/plugin-retry": "8.1.1",
+    "@octokit/request-error": "7.1.2",
+    "ai": "7.0.137",
+    "ai-sdk-sandbox-local": "0.1.2",
+    "citty": "0.2.2",
+    "ws": "8.22.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-conventional": "21.2.3",
+    "@types/bun": "1.4.2",
+    "git-cliff": "2.14.2",
+    "lefthook": "2.2.1",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.87.0",
+    "oxlint-plugin-deslopify": "0.5.0",
+    "oxlint-tsgolint": "7.0.2004",
+    "typescript": "7.0.2"
+  }
+}

package/src/agent/claude-code/claude-code-agent.ts

@@ -0,0 +1,174 @@
+import { HarnessAgent } from "@ai-sdk/harness/agent";
+import { createClaudeCode } from "@ai-sdk/harness-claude-code";
+import { Output } from "ai";
+import { createLocalSandbox } from "ai-sdk-sandbox-local";
+import { z } from "zod";
+import { ExplorationLog, explorationCall } from "@/agent/explored";
+import type {
+  AgentResult,
+  AgentRun,
+  ReviewerAgent,
+  RunStats,
+} from "@/agent/reviewer-agent";
+
+export const EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+
+export type Effort = (typeof EFFORTS)[number];
+
+export interface ClaudeCodeReviewerAgentOptions {
+  model?: string;
+  maxTurns?: number;
+  effort?: Effort;
+}
+
+function leaseLocalPort() {
+  const listener = Bun.listen({
+    hostname: "127.0.0.1",
+    port: 0,
+    socket: { data: function () {} },
+  });
+  const { port } = listener;
+  listener.stop(true);
+  return port;
+}
+
+// Claude Code reports its cost estimate only on the turn's `finish` part, which
+// the harness sends with `providerMetadata` though the AI SDK type leaves it
+// out. The non-deprecated `finalStep.providerMetadata` never has it.
+export const finishCost = z
+  .object({
+    providerMetadata: z.object({
+      "claude-code": z.object({ costUsd: z.number() }),
+    }),
+  })
+  .transform((part) => {
+    return part.providerMetadata["claude-code"].costUsd;
+  });
+
+// Read-only by design: never add write or shell tools here. Under
+// "allow-reads" any other tool waits for an approval nothing grants.
+export const REVIEWER_TOOLS = ["read", "glob", "grep"] as const;
+
+// diffcop never answers approval requests, so the run would end without a
+// review; fail instead of posting an empty one.
+export function approvalRequestError(toolName: string) {
+  return new Error(
+    `The reviewer asked to use ${toolName}, which needs an approval diffcop can't give. Only ${REVIEWER_TOOLS.join(", ")} are allowed.`,
+  );
+}
+
+export class ClaudeCodeReviewerAgent implements ReviewerAgent {
+  readonly #options: ClaudeCodeReviewerAgentOptions;
+
+  constructor(options: ClaudeCodeReviewerAgentOptions = {}) {
+    this.#options = options;
+  }
+
+  async run<T>({
+    cwd,
+    prompt,
+    output,
+    reporter,
+    abortSignal,
+  }: AgentRun<T>): Promise<AgentResult<T>> {
+    const startedAt = performance.now();
+    const port = leaseLocalPort();
+    const agent = new HarnessAgent({
+      harness: createClaudeCode({
+        maxTurns: this.#options.maxTurns,
+        effort: this.#options.effort,
+        // The local sandbox predates `getPortEndpoint`, so pass the bridge port
+        // and endpoint explicitly.
+        port: port,
+        portEndpoint: { url: `ws://127.0.0.1:${port}` },
+      }),
+      model: this.#options.model,
+      instructions: prompt.instructions,
+      permissionMode: "allow-reads",
+      activeTools: [...REVIEWER_TOOLS],
+      // Root the session at `cwd` itself, not a per-session subdirectory.
+      sandboxConfig: { workDir: "." },
+      // Claude Code's `outputFormat`: the final answer is a schema-checked object.
+      output: Output.object({ schema: output }),
+    });
+
+    const sandboxSession = await createLocalSandbox({
+      cwd: cwd,
+    }).createSession();
+    const session = await agent.createSession({
+      sandboxSession: sandboxSession,
+    });
+
+    try {
+      const result = await agent.stream({
+        session: session,
+        abortSignal: abortSignal,
+        messages: [
+          {
+            role: "user",
+            content: prompt.content.map((text) => {
+              return {
+                type: "text",
+                text: text,
+              };
+            }),
+          },
+        ],
+      });
+
+      // Text before the structured answer is narration, so only progress is reported.
+      let toolCalls = 0;
+      let thinkingSince: number | undefined;
+      let costUsd: number | undefined;
+      const exploration = new ExplorationLog(cwd);
+      for await (const part of result.stream) {
+        switch (part.type) {
+          case "tool-call": {
+            toolCalls++;
+            const call = explorationCall.safeParse(part);
+            if (call.success) {
+              exploration.record(call.data);
+            }
+            reporter.toolCall(part.toolName, JSON.stringify(part.input));
+            break;
+          }
+          case "reasoning-start":
+            thinkingSince = performance.now();
+            break;
+          case "reasoning-end":
+            if (thinkingSince !== undefined) {
+              reporter.thinking(performance.now() - thinkingSince);
+              thinkingSince = undefined;
+            }
+            break;
+          case "tool-approval-request":
+            throw approvalRequestError(part.toolCall.toolName);
+          case "finish":
+            costUsd = finishCost.safeParse(part).data;
+            break;
+          case "error":
+            throw part.error;
+        }
+      }
+
+      const [usage, answer] = await Promise.all([result.usage, result.output]);
+      const stats: RunStats = {
+        durationMs: performance.now() - startedAt,
+        toolCalls: toolCalls,
+        inputTokens: usage.inputTokens,
+        cacheReadTokens: usage.inputTokenDetails.cacheReadTokens,
+        outputTokens: usage.outputTokens,
+        costUsd: costUsd,
+      };
+      return {
+        // Model output, so checked here too rather than trusting the harness's check.
+        output: output.parse(answer),
+        stats: stats,
+        explored: exploration.explored(),
+      };
+    } finally {
+      await session.destroy();
+      await sandboxSession.destroy();
+    }
+  }
+}

package/src/agent/explored.ts

@@ -0,0 +1,93 @@
+import { relative, resolve } from "node:path";
+import { z } from "zod";
+
+export interface Search {
+  pattern: string;
+  path?: string;
+}
+
+export interface Explored {
+  filesRead: string[];
+  searches: Search[];
+}
+
+const searchInput = z.object({
+  pattern: z.string(),
+  path: z.string().optional(),
+});
+
+// Claude Code's read, glob and grep tool calls, as they come off the stream.
+export const explorationCall = z.discriminatedUnion("toolName", [
+  z.object({
+    toolName: z.literal("read"),
+    input: z.object({ file_path: z.string() }),
+  }),
+  z.object({
+    toolName: z.enum(["glob", "grep"]),
+    input: searchInput,
+  }),
+]);
+
+export type ExplorationCall = z.infer<typeof explorationCall>;
+
+function searchKey({ pattern, path }: Search) {
+  return JSON.stringify([pattern, path]);
+}
+
+function uniqueSearches(searches: Search[]) {
+  const byKey = new Map<string, Search>();
+  for (const search of searches) {
+    if (!byKey.has(searchKey(search))) {
+      byKey.set(searchKey(search), search);
+    }
+  }
+  return [...byKey.values()];
+}
+
+export function mergeExplored(a: Explored, b: Explored): Explored {
+  return {
+    filesRead: [...new Set([...a.filesRead, ...b.filesRead])],
+    searches: uniqueSearches([...a.searches, ...b.searches]),
+  };
+}
+
+// Collects what a run read and searched from its tool calls, in first-seen order.
+export class ExplorationLog {
+  readonly #cwd: string;
+  readonly #filesRead: string[] = [];
+  readonly #searches: Search[] = [];
+
+  constructor(cwd: string) {
+    this.#cwd = cwd;
+  }
+
+  record(call: ExplorationCall) {
+    if (call.toolName === "read") {
+      this.#filesRead.push(this.#relative(call.input.file_path));
+      return;
+    }
+    this.#searches.push(this.#search(call.input));
+  }
+
+  explored(): Explored {
+    return {
+      filesRead: [...new Set(this.#filesRead)],
+      searches: uniqueSearches(this.#searches),
+    };
+  }
+
+  #search({ pattern, path }: Search): Search {
+    const relativePath = path === undefined ? "" : this.#relative(path);
+    if (!relativePath) {
+      return { pattern: pattern };
+    }
+    return {
+      pattern: pattern,
+      path: relativePath,
+    };
+  }
+
+  #relative(path: string) {
+    return relative(this.#cwd, resolve(this.#cwd, path));
+  }
+}

package/src/agent/reviewer-agent.ts

@@ -0,0 +1,51 @@
+import type { z } from "zod";
+import type { ReviewPrompt } from "@/prompt/review-prompt-builder";
+import type { ReviewReporter } from "@/reporter/review-reporter";
+import type { Explored } from "@/agent/explored";
+
+export interface RunStats {
+  durationMs: number;
+  toolCalls: number;
+  inputTokens?: number;
+  cacheReadTokens?: number;
+  outputTokens?: number;
+  costUsd?: number;
+}
+
+export interface AgentRun<T> {
+  cwd: string;
+  prompt: ReviewPrompt;
+  // The agent answers with an object matching this schema.
+  output: z.ZodType<T>;
+  reporter: ReviewReporter;
+  abortSignal?: AbortSignal;
+}
+
+export interface AgentResult<T> {
+  output: T;
+  stats: RunStats;
+  explored: Explored;
+}
+
+export interface ReviewerAgent {
+  run<T>(run: AgentRun<T>): Promise<AgentResult<T>>;
+}
+
+// A count only one run reported is left out rather than understated.
+function sumKnown(a: number | undefined, b: number | undefined) {
+  if (a === undefined || b === undefined) {
+    return undefined;
+  }
+  return a + b;
+}
+
+export function sumStats(a: RunStats, b: RunStats): RunStats {
+  return {
+    durationMs: a.durationMs + b.durationMs,
+    toolCalls: a.toolCalls + b.toolCalls,
+    inputTokens: sumKnown(a.inputTokens, b.inputTokens),
+    cacheReadTokens: sumKnown(a.cacheReadTokens, b.cacheReadTokens),
+    outputTokens: sumKnown(a.outputTokens, b.outputTokens),
+    costUsd: sumKnown(a.costUsd, b.costUsd),
+  };
+}

package/src/cli.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from "citty";
+import pkg from "#package.json";
+
+const main = defineCommand({
+  meta: {
+    name: "diffcop",
+    version: pkg.version,
+    description: "Local AI code reviewer",
+  },
+  subCommands: {
+    review: () => {
+      return import("@/commands/review").then((m) => {
+        return m.default;
+      });
+    },
+  },
+});
+
+// runMain catches its own errors and exits non-zero, so there's nothing to await.
+void runMain(main);