codiff -w defaults to HEAD if there are no local changes.

Author: cpojer

README.md

@@ -58,15 +58,18 @@ Full GitHub and GitLab review URLs are also supported. GitLab hosts and nested p
 derived from the URL or local Git remote and authenticated through `glab`; Codiff does not require
 instance-specific configuration.
 
-Start with an LLM-generated narrative walkthrough:
+Start with an LLM-generated narrative walkthrough. When generating a walkthrough without an
+explicit target, Codiff uses local changes when present and falls back to `HEAD` when the working
+tree is clean:
 
 ```bash
 codiff -w
 codiff -w a1b2c3d
 ```
 
 When walkthrough sharing is available for your Git identity, generate and upload the same
-walkthrough without opening Codiff. The command prints the final URL:
+walkthrough without opening Codiff. The same default applies to generated walkthroughs, and the
+command prints the final URL:
 
 ```bash
 codiff --share

bin/arguments.js

@@ -46,7 +46,7 @@ export const flagDefinitions = [
     type: 'string',
   },
   {
-    description: 'Generate and share a narrative walkthrough, then print its URL.',
+    description: 'Generate and share a walkthrough, then print its URL; use HEAD when clean.',
     name: 'share',
     type: 'boolean',
   },
@@ -57,7 +57,7 @@ export const flagDefinitions = [
     type: 'boolean',
   },
   {
-    description: 'Start with an LLM-generated narrative walkthrough.',
+    description: 'Start an LLM walkthrough; use HEAD when there are no local changes.',
     name: 'walkthrough',
     short: 'w',
     type: 'boolean',
@@ -89,9 +89,9 @@ export const usageExamples = [
   { command: "codiff '#75'", description: 'Review pull request #75.' },
   { command: 'codiff pr 75', description: 'Review pull request #75 (alternate syntax).' },
   { command: 'codiff mr 75', description: 'Review GitLab merge request !75.' },
-  { command: 'codiff -w', description: 'Start with an LLM narrative walkthrough.' },
+  { command: 'codiff -w', description: 'Walk through local changes, or HEAD when clean.' },
   { command: 'codiff -w a1b2c3d', description: 'Generate a narrative walkthrough for a commit.' },
-  { command: 'codiff --share', description: 'Share an LLM narrative walkthrough.' },
+  { command: 'codiff --share', description: 'Share local changes, or HEAD when clean.' },
   { command: 'codiff --share HEAD', description: 'Share a walkthrough for a commit.' },
 ];
 

bin/codiff-app

@@ -39,9 +39,9 @@ show_help() {
   printf '  %-38s%s%s%s\n' "--help, -h" "$gray" "Show this help message and exit." "$reset"
   printf '  %-38s%s%s%s\n' "--opencode-session <id>" "$gray" "Attach OpenCode session metadata to a walkthrough." "$reset"
   printf '  %-38s%s%s%s\n' "--pi-session <id>" "$gray" "Attach Pi session metadata to a walkthrough." "$reset"
-  printf '  %-38s%s%s%s\n' "--share" "$gray" "Generate and share a narrative walkthrough, then print its URL." "$reset"
+  printf '  %-38s%s%s%s\n' "--share" "$gray" "Generate and share a walkthrough, then print its URL; use HEAD when clean." "$reset"
   printf '  %-38s%s%s%s\n' "--version, -v" "$gray" "Show version number and exit." "$reset"
-  printf '  %-38s%s%s%s\n' "--walkthrough, -w" "$gray" "Start with an LLM-generated narrative walkthrough." "$reset"
+  printf '  %-38s%s%s%s\n' "--walkthrough, -w" "$gray" "Start an LLM walkthrough; use HEAD when there are no local changes." "$reset"
   printf '  %-38s%s%s%s\n' "--walkthrough-context <file>" "$gray" "Seed a walkthrough with Codex conversation context JSON." "$reset"
   printf '  %-38s%s%s%s\n' "--walkthrough-file <file>" "$gray" "Open a pre-authored narrative walkthrough JSON file." "$reset"
   printf '  %-38s%s%s%s\n' "--walkthrough-guide" "$gray" "Print the narrative walkthrough authoring guide and schema, then exit." "$reset"
@@ -54,9 +54,9 @@ show_help() {
   printf '  %-22s%s%s%s\n' "codiff '#75'" "$gray" "Review pull request #75." "$reset"
   printf '  %-22s%s%s%s\n' "codiff pr 75" "$gray" "Review pull request #75 (alternate syntax)." "$reset"
   printf '  %-22s%s%s%s\n' "codiff mr 75" "$gray" "Review GitLab merge request !75." "$reset"
-  printf '  %-22s%s%s%s\n' "codiff -w" "$gray" "Start with an LLM narrative walkthrough." "$reset"
+  printf '  %-22s%s%s%s\n' "codiff -w" "$gray" "Walk through local changes, or HEAD when clean." "$reset"
   printf '  %-22s%s%s%s\n' "codiff -w a1b2c3d" "$gray" "Walkthrough a specific commit." "$reset"
-  printf '  %-22s%s%s%s\n' "codiff --share" "$gray" "Share an LLM narrative walkthrough." "$reset"
+  printf '  %-22s%s%s%s\n' "codiff --share" "$gray" "Share local changes, or HEAD when clean." "$reset"
   printf '  %-22s%s%s%s\n' "codiff --share HEAD" "$gray" "Share a walkthrough for a commit." "$reset"
 }
 

bin/codiff.js

@@ -164,7 +164,7 @@ const run = async () => {
           ? { ref: commitRef, type: 'commit' }
           : branchRef
             ? { ref: branchRef, type: 'branch' }
-            : { type: 'working-tree' };
+            : undefined;
 
     try {
       const commonOptions = {

core/__tests__/codiff-cli.test.ts

@@ -1022,7 +1022,7 @@ test('formatHelpText styles titles and descriptions', () => {
   expect(text).toContain('\u001b[90mShow this help message and exit.\u001b[0m');
   expect(text).toContain('  codiff -w');
   expect(text).not.toContain('\u001b[1;34mcodiff -w\u001b[0m');
-  expect(text).toContain('\u001b[90mStart with an LLM narrative walkthrough.\u001b[0m');
+  expect(text).toContain('\u001b[90mWalk through local changes, or HEAD when clean.\u001b[0m');
 });
 
 test('codiff-app prints help text and exits 0', async () => {

core/__tests__/codiff-share-cli.test.ts

@@ -180,7 +180,7 @@ test('headless share uploads the canonical snapshot and prints its URL', async (
   }
 });
 
-test('codiff --share generates a walkthrough for HEAD and prints only its URL', async () => {
+test('codiff --share falls back to HEAD for a clean working tree and prints only its URL', async () => {
   const directory = await mkdtemp(join(tmpdir(), 'codiff-generate-share-'));
   const repositoryPath = join(directory, 'repo');
   const fakeCodexPath = join(directory, 'codex');
@@ -285,7 +285,7 @@ exit 1
     const origin = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
     const { stderr, stdout } = await execFileAsync(
       process.execPath,
-      [resolve('bin/codiff.js'), '--share', 'HEAD', repositoryPath],
+      [resolve('bin/codiff.js'), '--share', repositoryPath],
       {
         encoding: 'utf8',
         env: {

core/__tests__/git-state.test.ts

@@ -85,6 +85,11 @@ type GitStateModule = {
     source?: ReviewSource,
     options?: { showWhitespace?: boolean },
   ) => Promise<RepositoryState>;
+  readWalkthroughRepositoryState: (
+    launchPath: string,
+    source?: ReviewSource,
+    options?: { showWhitespace?: boolean },
+  ) => Promise<RepositoryState>;
   readWorkingTreeState: (
     launchPath: string,
     options?: { eagerContents?: boolean; showWhitespace?: boolean },
@@ -116,6 +121,7 @@ const {
   readDiffSectionContent,
   readRepositoryChangeSignature,
   readRepositoryState,
+  readWalkthroughRepositoryState,
   readWorkingTreeState,
   resolvePullRequestContentRefs,
   selectUnresolvedReviewComments,
@@ -694,6 +700,35 @@ test('readRepositoryState and history handle fresh repositories', async () => {
   });
 });
 
+test('readWalkthroughRepositoryState falls back to HEAD only for a clean implicit source', () =>
+  withRepo(async (repo) => {
+    await writeRepoFile(repo, 'example.txt', 'before\n');
+    await commitAll(repo, 'initial commit');
+    await writeRepoFile(repo, 'example.txt', 'after\n');
+    await commitAll(repo, 'update example');
+
+    const cleanState = await readWalkthroughRepositoryState(repo);
+    expect(cleanState.source).toMatchObject({ type: 'commit' });
+    expect(cleanState.commitMetadata?.subject).toBe('update example');
+
+    const explicitWorkingTreeState = await readWalkthroughRepositoryState(repo, {
+      type: 'working-tree',
+    });
+    expect(explicitWorkingTreeState.source).toEqual({ type: 'working-tree' });
+    expect(explicitWorkingTreeState.files).toEqual([]);
+
+    await writeRepoFile(repo, 'example.txt', 'local\n');
+    const dirtyState = await readWalkthroughRepositoryState(repo);
+    expect(dirtyState.source).toEqual({ type: 'working-tree' });
+  }));
+
+test('readWalkthroughRepositoryState keeps a fresh repository on the working tree', () =>
+  withRepo(async (repo) => {
+    const state = await readWalkthroughRepositoryState(repo);
+    expect(state.source).toEqual({ type: 'working-tree' });
+    expect(state.files).toEqual([]);
+  }));
+
 test('readRepositoryState reports commit metadata for root commits', async () => {
   await withRepo(async (repo) => {
     await writeRepoFile(repo, 'notes/todo.txt', 'write tests\nship polish\n');

electron/__tests__/window-identity.test.ts

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -28,6 +28,8 @@ const { findMatchingWindowIdentity, getWindowIdentity, parseGitHubPullRequestUrl
               type: 'pull-request';
               url: string;
             };
+        walkthrough?: boolean;
+        walkthroughFile?: string;
       },
     ) => { key: string; repositoryRoot: string; sourceKey: string } | null;
     parseGitHubPullRequestUrl: (value: string) => {
@@ -91,6 +93,32 @@ test('window identities resolve commit refs to the same commit sha', async () =>
   }
 });
 
+test('implicit walkthrough identities use HEAD only when the working tree is clean', async () => {
+  const repositoryPath = await createRepository();
+
+  try {
+    const headIdentity = getWindowIdentity(repositoryPath, {
+      source: { ref: 'HEAD', type: 'commit' },
+    });
+    expect(getWindowIdentity(repositoryPath, { walkthrough: true })?.key).toBe(headIdentity?.key);
+
+    await writeFile(join(repositoryPath, 'local.txt'), 'change\n');
+    expect(getWindowIdentity(repositoryPath, { walkthrough: true })?.sourceKey).toBe(
+      'working-tree',
+    );
+
+    await rm(join(repositoryPath, 'local.txt'));
+    expect(
+      getWindowIdentity(repositoryPath, {
+        walkthrough: true,
+        walkthroughFile: '/tmp/walkthrough.json',
+      })?.sourceKey,
+    ).toBe('working-tree');
+  } finally {
+    await rm(repositoryPath, { force: true, recursive: true });
+  }
+});
+
 test('window identities distinguish branch history launches', async () => {
   const repositoryPath = await createRepository();
 

electron/git-state.cjs

@@ -81,6 +81,25 @@ const readRepositoryState = async (launchPath, source = { type: 'working-tree' }
   return { ...state, branch };
 };
 
+/**
+ * An implicit walkthrough reviews local changes when present and otherwise
+ * reviews the current commit. Explicit sources always retain their semantics.
+ *
+ * @param {string} launchPath
+ * @param {ReviewSource} [source]
+ * @param {{showWhitespace?: boolean}} [options]
+ * @returns {Promise<RepositoryState>}
+ */
+const readWalkthroughRepositoryState = async (launchPath, source, options = {}) => {
+  const state = await readRepositoryState(launchPath, source, options);
+  if (source || state.source.type !== 'working-tree' || state.files.length > 0) {
+    return state;
+  }
+
+  const head = (await gitOrEmpty(state.root, ['rev-parse', '--verify', 'HEAD'])).trim();
+  return head ? readRepositoryState(launchPath, { ref: 'HEAD', type: 'commit' }, options) : state;
+};
+
 /** @param {Extract<ReviewSource, {type: 'pull-request'}>} source */
 const isGitLabReviewSource = (source) =>
   source.provider === 'gitlab' || parseReviewUrl(source.url)?.provider === 'gitlab';
@@ -170,6 +189,7 @@ module.exports = {
   readCommitState,
   readPullRequestState,
   readRepositoryState,
+  readWalkthroughRepositoryState,
   readWorkingTreeState,
   resolvePullRequestContentRefs,
   submitPullRequestComment: (launchPath, request) =>

electron/headless-walkthrough-share.cjs

@@ -5,7 +5,11 @@ const { userInfo } = require('node:os');
 const { getAgent } = require('./agent.cjs');
 const { readConfig, writeConfig } = require('./config.cjs');
 const { createCloudflareAccessClient } = require('./cloudflare-access.cjs');
-const { readGitIdentity, readRepositoryState } = require('./git-state.cjs');
+const {
+  readGitIdentity,
+  readRepositoryState,
+  readWalkthroughRepositoryState,
+} = require('./git-state.cjs');
 const {
   normalizeNarrativeWalkthrough,
   readNarrativeWalkthrough,
@@ -106,6 +110,19 @@ const readShareState = async (repositoryPath, source, config) =>
     readGitIdentity(repositoryPath),
   ]);
 
+/**
+ * @param {string} repositoryPath
+ * @param {ReviewSource | undefined} source
+ * @param {ReturnType<typeof readConfig>} config
+ */
+const readGeneratedShareState = async (repositoryPath, source, config) =>
+  Promise.all([
+    readWalkthroughRepositoryState(repositoryPath, source, {
+      showWhitespace: config.settings.showWhitespace,
+    }),
+    readGitIdentity(repositoryPath),
+  ]);
+
 /**
  * @param {{
  *   agent?: 'claude' | 'codex' | 'opencode' | 'pi';
@@ -181,12 +198,12 @@ const generateAndShareWalkthrough = async ({
   piSessionId,
   repositoryPath,
   serviceUrlOverride,
-  source = { type: 'working-tree' },
+  source,
   walkthroughContextPath,
 }) => {
   const config = readConfig();
   const agent = getAgent(agentOverride || config.settings.agentBackend);
-  const [state, uploader] = await readShareState(repositoryPath, source, config);
+  const [state, uploader] = await readGeneratedShareState(repositoryPath, source, config);
   const sessionIds = {
     claudeSessionId,
     codexSessionId,