### Run OpenTUI Diff Examples

Source: https://github.com/modem-dev/hunk/blob/main/examples/7-opentui-component/README.md

Execute the OpenTUI diff examples from the command line using Bun. One example loads diffs from files, and the other loads from a patch.

```bash
bun run examples/7-opentui-component/from-files.tsx
```

```bash
bun run examples/7-opentui-component/from-patch.tsx
```

--------------------------------

### Install Binary

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Install the compiled Hunk binary to the system.

```bash
bun run install:bin
```

--------------------------------

### Basic Session Broker Daemon Setup with Bun

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker-bun/README.md

Demonstrates the basic setup for creating and serving a SessionBrokerDaemon using the @hunk/session-broker-bun package with Bun.serve. Ensure you have the necessary broker and daemon configurations.

```typescript
import { SessionBroker, createSessionBrokerDaemon } from "@hunk/session-broker";
import { serveSessionBrokerDaemon } from "@hunk/session-broker-bun";

const broker = new SessionBroker({
  parseRegistration,
  parseSnapshot,
});

const daemon = createSessionBrokerDaemon({
  broker,
  capabilities: { version: 1, name: "example-broker" },
});

const server = serveSessionBrokerDaemon({
  daemon,
  hostname: "127.0.0.1",
  port: 47657,
});
```

--------------------------------

### Quick Start with HunkDiffView

Source: https://github.com/modem-dev/hunk/blob/main/docs/opentui-component.md

Demonstrates how to use HunkDiffView to display a diff between two file versions. This example sets up a CLI renderer and renders the diff view with specified layout and theme.

```tsx
import { createCliRenderer } from "@opentui/core";
import { createRoot } from "@opentui/react";
import { HunkDiffView, createHunkDiffFile, parseDiffFromFile } from "hunkdiff/opentui";

const metadata = parseDiffFromFile(
  {
    cacheKey: "before",
    contents: "export const value = 1;\n",
    name: "example.ts",
  },
  {
    cacheKey: "after",
    contents: "export const value = 2;\nexport const added = true;\n",
    name: "example.ts",
  },
  { context: 3 },
  true,
);

const renderer = await createCliRenderer({
  useAlternateScreen: true,
  useMouse: true,
  exitOnCtrlC: true,
});
const root = createRoot(renderer);

root.render(
  <HunkDiffView
    diff={createHunkDiffFile({
      id: "example",
      metadata,
      language: "typescript",
      path: "example.ts",
    })}
    layout="split"
    width={88}
    theme="midnight"
  />,
);

```

--------------------------------

### Install Dependencies

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Installs project dependencies using Bun. Ensure Bun 1.3+ is installed.

```bash
bun install
```

--------------------------------

### Run OpenTUI Component Example from Files

Source: https://github.com/modem-dev/hunk/blob/main/examples/README.md

This command demonstrates embedding `HunkDiffView` in OpenTUI by reading from files.

```bash
bun run examples/7-opentui-component/from-files.tsx
```

--------------------------------

### Install Nix Package Manager

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

This command installs the Nix package manager. It is a one-time setup required for the `nix:update-lock` script.

```bash
curl -L https://nixos.org/nix/install | sh
```

--------------------------------

### Run OpenTUI Component Example from Patch

Source: https://github.com/modem-dev/hunk/blob/main/examples/README.md

This example demonstrates embedding `HunkDiffView` in OpenTUI using raw unified diff text instead of `before` and `after` file contents.

```bash
bun run examples/7-opentui-component/from-patch.tsx
```

--------------------------------

### Show Hunk Help and Version

Source: https://github.com/modem-dev/hunk/blob/main/README.md

Basic commands to display help information or the installed version of the Hunk CLI.

```bash
hunk           # show help
hunk --version # print the installed version
```

--------------------------------

### Run Benchmark Suite with Competitor Comparisons

Source: https://github.com/modem-dev/hunk/blob/main/benchmarks/README.md

Includes comparisons against other tools in the benchmark suite. Ensure competitor tools are installed before running.

```bash
bun run bench -- --samples 3 --include-competitors --out benchmarks/results/local-with-competitors.json
```

--------------------------------

### Install Hunk with Homebrew

Source: https://github.com/modem-dev/hunk/blob/main/README.md

Install Hunk using Homebrew on macOS or Linux. Ensure you have Homebrew installed.

```bash
brew install hunk
```

--------------------------------

### Install Hunk with npm

Source: https://github.com/modem-dev/hunk/blob/main/README.md

Install Hunk globally using npm. This is the primary method for Node.js environments.

```bash
npm i -g hunkdiff
```

--------------------------------

### Run OpenTUI Primitives Demo

Source: https://github.com/modem-dev/hunk/blob/main/examples/8-opentui-primitives/README.md

Execute the OpenTUI primitives demo application using Bun. This command starts the custom app built from lower-level Hunk components.

```bash
bun run examples/8-opentui-primitives/primitives-demo.tsx
```

--------------------------------

### Initiate Hunk Review Session

Source: https://github.com/modem-dev/hunk/blob/main/skills/hunk-review/SKILL.md

Start a hunk review session in JSON mode to understand the file and hunk structure. Use `--include-patch` only for specific files requiring raw diff content. This command is the first step in guiding a user through a changeset.

```bash
hunk session review --json
```

--------------------------------

### List, Get, Context, and Review Hunk Sessions

Source: https://github.com/modem-dev/hunk/blob/main/skills/hunk-review/SKILL.md

Commands to list all sessions, get details of a specific session, retrieve its context, or initiate a review. The `--json` flag outputs results in JSON format. `get` provides `Path` and `Repo` for selecting sessions.

```bash
hunk session list [--json]
```

```bash
hunk session get (--repo . | <id>) [--json]
```

```bash
hunk session context (--repo . | <id>) [--json]
```

```bash
hunk session review (--repo . | <id>) [--json] [--include-patch]
```

--------------------------------

### Install OpenTUI and React Dependencies

Source: https://github.com/modem-dev/hunk/blob/main/docs/opentui-component.md

Install the hunkdiff package along with its peer dependencies, OpenTUI core and React. Ensure you have React installed in your application.

```bash
npm i hunkdiff @opentui/core@^0.1.88 @opentui/react@^0.1.88 react
```

--------------------------------

### Use Hunk Package in Home Manager

Source: https://github.com/modem-dev/hunk/blob/main/nix/README.md

Add the Hunk package to your Home Manager configuration. This installs Hunk for your user.

```nix
{ 
  home.packages = [ 
    inputs.hunk.packages.${pkgs.stdenv.hostPlatform.system}.hunk 
  ];
}
```

--------------------------------

### Run Hunk Directly with Nix

Source: https://github.com/modem-dev/hunk/blob/main/nix/README.md

Execute Hunk using the `nix run` command with a flake reference. Useful for testing or running without a full installation.

```bash
nix run github:modem-dev/hunk -- --help
```

--------------------------------

### Build and Smoke-test Prebuilt NPM Packages

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Builds prebuilt npm packages for the current host and performs a smoke test after installation. This is for testing the distribution.

```bash
bun run build:prebuilt:npm
bun run check:prebuilt-pack
bun run smoke:prebuilt-install
```

--------------------------------

### Create a Session Broker Daemon with HTTP API

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker/README.md

Enable the raw broker HTTP API by setting `exposeHttpApi: true` during daemon creation. This allows the host application to expose generic list, get, and dispatch command surfaces.

```typescript
const daemon = createSessionBrokerDaemon({
  broker,
  capabilities: {
    version: 1,
    name: "example-broker",
  },
  exposeHttpApi: true,
});
```

--------------------------------

### Get current repository session

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Confirms which live session matches the current repository. Essential for ensuring you are interacting with the correct session.

```bash
hunk session get --repo .
```

--------------------------------

### Serve Session Broker Daemon with Node HTTP

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker-node/README.md

Use this snippet to start the session broker daemon using Node's HTTP server. Ensure you have the necessary imports and have instantiated the SessionBroker and created the daemon.

```typescript
import { SessionBroker, createSessionBrokerDaemon } from "@hunk/session-broker";
import { serveSessionBrokerDaemon } from "@hunk/session-broker-node";

const broker = new SessionBroker({
  parseRegistration,
  parseSnapshot,
});

const daemon = createSessionBrokerDaemon({
  broker,
  capabilities: { version: 1, name: "example-broker" },
});

const server = await serveSessionBrokerDaemon({
  daemon,
  hostname: "127.0.0.1",
  port: 47657,
});
```

--------------------------------

### Run Hunk Diff with Pager for Scrolling

Source: https://github.com/modem-dev/hunk/blob/main/examples/README.md

Use this command to test line scrolling, paging, and hunk jumps. The example is intentionally taller than a typical terminal viewport.

```bash
hunk diff --pager examples/5-pager-tour/before.ts examples/5-pager-tour/after.ts
```

--------------------------------

### Run Release Benchmark Suite

Source: https://github.com/modem-dev/hunk/blob/main/benchmarks/release/README.md

Execute the benchmark suite for the current version in package.json to generate a new snapshot. This is a prerequisite before pushing a release tag.

```bash
bun run bench:release
```

--------------------------------

### Build Binary

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Compile the project into a standalone binary executable.

```bash
bun run build:bin
```

--------------------------------

### Run Screenshot Demo

Source: https://github.com/modem-dev/hunk/blob/main/examples/6-readme-screenshot/README.md

Execute the screenshot-optimized demo. Use this command to generate the visual output described in the README.

```bash
hunk patch examples/6-readme-screenshot/change.patch \
  --agent-context examples/6-readme-screenshot/agent-context.json \
  --mode split \
  --theme midnight
```

--------------------------------

### Prepare Multi-Platform Release

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Prepares release directories for multiple platforms from downloaded artifacts and performs a dry-run of the publish order. This is a crucial step before publishing.

```bash
bun run build:prebuilt:artifact
bun run stage:prebuilt:release
bun run check:prebuilt-pack
bun run publish:prebuilt:npm -- --dry-run
```

--------------------------------

### Build Hunk with Nix

Source: https://github.com/modem-dev/hunk/blob/main/nix/README.md

Build the Hunk package using `nix build`. The resulting binary will be located in the `./result/bin/hunk` path.

```bash
nix build
```

--------------------------------

### Run Default Local Benchmark Suite

Source: https://github.com/modem-dev/hunk/blob/main/benchmarks/README.md

Executes the default local benchmark suite and outputs results to a JSON file. Adjust the number of samples as needed.

```bash
bun run bench -- --samples 3 --out benchmarks/results/local.json
```

--------------------------------

### Create HunkDiffFile with Path and Language

Source: https://github.com/modem-dev/hunk/blob/main/docs/opentui-component.md

Demonstrates creating a normalized `HunkDiffFile` with explicit path and language settings using `createHunkDiffFile` and `parseDiffFromFile`.

```tsx
import { createHunkDiffFile, parseDiffFromFile } from "hunkdiff/opentui";

const file = createHunkDiffFile({
  id: "example",
  metadata: parseDiffFromFile(beforeFile, afterFile, { context: 3 }, true),
  path: "example.ts",
  language: "typescript",
});
```

--------------------------------

### Regenerate Nix Dependency Lockfile

Source: https://github.com/modem-dev/hunk/blob/main/nix/README.md

Update the Nix dependency lockfile when JavaScript or Bun dependencies change. This script uses `bun2nix` and requires Nix to be installed.

```bash
bun run nix:update-lock
```

--------------------------------

### Run Project Tests

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Execute all unit and integration tests for the project.

```bash
bun test
```

--------------------------------

### Run Hunk from Source

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Executes the Hunk application directly from the source code. Requires Bun.

```bash
bun run src/main.tsx -- diff
```

--------------------------------

### Compare Release Benchmark Snapshot

Source: https://github.com/modem-dev/hunk/blob/main/benchmarks/release/README.md

Compare the newly generated benchmark snapshot against the latest stable release snapshot. This command helps identify regressions.

```bash
bun run bench:release:compare
```

--------------------------------

### Raw Broker API Request Body Shapes

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker/README.md

These are the expected request body shapes for interacting with the raw broker HTTP API. They define actions like listing sessions, getting session details, or dispatching commands.

```typescript
{ action: "list" }
```

```typescript
{ action: "get", selector: { sessionId: "..." } }
```

```typescript
{ action: "dispatch", selector: { sessionId: "..." }, command: "...", input: {...} }
```

--------------------------------

### Review a Commit from Source

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Inspect a specific commit from the source code using the `show` command.

```bash
bun run src/main.tsx -- show HEAD~1
```

--------------------------------

### Generate Release Benchmark Snapshot

Source: https://github.com/modem-dev/hunk/blob/main/benchmarks/README.md

Commands to generate the committed release benchmark snapshot, typically used during release preparation.

```bash
bun run bench:release
```

```bash
bun run bench:release:compare
```

--------------------------------

### Create HunkDiffFile from File Contents

Source: https://github.com/modem-dev/hunk/blob/main/docs/opentui-component.md

Shows how to create a `HunkDiffFile` when you have the old and new file contents available, using `parseDiffFromFile`.

```tsx
import { createHunkDiffFile, parseDiffFromFile } from "hunkdiff/opentui";

const file = createHunkDiffFile({
  id: "example",
  metadata: parseDiffFromFile(beforeFile, afterFile, { context: 3 }, true),
});
```

--------------------------------

### Enable Hunk Home Manager Module

Source: https://github.com/modem-dev/hunk/blob/main/nix/README.md

Configure Hunk using its dedicated Home Manager module. This allows managing Hunk's settings and enabling Git integration.

```nix
{ 
  imports = [ 
    inputs.hunk.homeManagerModules.default 
  ];

  programs.hunk = { 
    enable = true;
    enableGitIntegration = true; # Optional: set hunk as default git pager
    settings = { 
      theme = "graphite";
      mode = "split";
      line_numbers = true;
    };
  };
}
```

--------------------------------

### Format Project Code

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Apply code formatting rules to the entire project.

```bash
bun run format
```

--------------------------------

### Serve Session Broker Daemon with Bun Adapter

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker/README.md

Use the `@hunk/session-broker-bun` adapter to serve the SessionBrokerDaemon over HTTP/WebSockets using Bun. Specify the hostname and port for the server.

```typescript
import { serveSessionBrokerDaemon } from "@hunk/session-broker-bun";

const server = serveSessionBrokerDaemon({
  daemon,
  hostname: "127.0.0.1",
  port: 47657,
});
```

--------------------------------

### Hunk Review CLI Workflow

Source: https://github.com/modem-dev/hunk/blob/main/skills/hunk-review/SKILL.md

This sequence outlines the typical workflow for interacting with Hunk sessions using the CLI. It covers listing sessions, inspecting session details, reviewing file and hunk structures, and adding comments.

```text
1. hunk session list                                    # find live sessions
2. hunk session get --repo .                            # inspect path / repo / source
3. hunk session review --repo . --json                  # inspect file/hunk structure first
4. hunk session review --repo . --include-patch --json  # opt into raw diff text only when needed
5. hunk session context --repo .                        # check current focus when needed
6. hunk session navigate ...                            # move to the right place
7. hunk session reload -- <command>                     # swap contents if needed
8. hunk session comment add ...                         # leave one review note
9. hunk session comment apply ...                       # apply many agent notes in one stdin batch
```

--------------------------------

### Create a Session Broker Instance

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker/README.md

Instantiate a SessionBroker with custom parsers for session registration and snapshot envelopes. This is useful for defining how session metadata and state are interpreted.

```typescript
import {
  SessionBroker,
  brokerWireParsers,
  parseSessionRegistrationEnvelope,
  parseSessionSnapshotEnvelope,
} from "@hunk/session-broker";

interface SessionInfo {
  title: string;
}

interface SessionState {
  selectedIndex: number;
}

function parseInfo(value: unknown): SessionInfo | null {
  const record = brokerWireParsers.asRecord(value);
  if (!record) {
    return null;
  }

  const title = brokerWireParsers.parseRequiredString(record.title);
  return title === null ? null : { title };
}

function parseState(value: unknown): SessionState | null {
  const record = brokerWireParsers.asRecord(value);
  if (!record) {
    return null;
  }

  const selectedIndex = brokerWireParsers.parseNonNegativeInt(record.selectedIndex);
  return selectedIndex === null ? null : { selectedIndex };
}

const broker = new SessionBroker({
  parseRegistration: (value) => parseSessionRegistrationEnvelope(value, parseInfo),
  parseSnapshot: (value) => parseSessionSnapshotEnvelope(value, parseState),
});
```

--------------------------------

### Typecheck Project

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Run the type checking process for the entire project.

```bash
bun run typecheck
```

--------------------------------

### Create Session Broker Connection

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker/README.md

Use this helper when an app window or live process needs to stay registered with the broker. It handles initial registration, snapshot updates, heartbeats, command replies, and command queuing.

```typescript
import { createSessionBrokerConnection } from "@hunk/session-broker";

const connection = createSessionBrokerConnection({
  url: "ws://127.0.0.1:47657/session",
  createSocket: (url) => new WebSocket(url),
  registration,
  snapshot,
  bridge: {
    dispatchCommand: async (message) => {
      return handleCommand(message);
    },
  },
});

connection.start();
```

--------------------------------

### Navigate to a specific file and hunk

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Jumps the live Hunk window to a specified file and hunk number. The `--hunk` parameter is 1-based.

```bash
hunk session navigate --repo . --file src/App.tsx --hunk 2
```

--------------------------------

### Generic Agent Prompt for Hunk Skill

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Use this prompt to instruct an agent to load and utilize the Hunk review skill for inspecting and interacting with a live Hunk session. Ensure the agent can execute `hunk skill path` to retrieve the necessary skill path.

```text
Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path.
```

--------------------------------

### Build and Verify NPM Package

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Builds the npm package for Hunk and verifies its integrity. This is part of the release process.

```bash
bun run build:npm
bun run check:pack
```

--------------------------------

### Run Benchmarks

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Executes various benchmark scripts to measure performance. Scripts cover bootstrap load, highlight prefetching, and large stream processing.

```bash
bun run bench:bootstrap-load
bun run bench:highlight-prefetch
bun run bench:large-stream
bun run bench:large-stream-profile
```

--------------------------------

### Run Benchmark Suite with Huge Fixture Tier

Source: https://github.com/modem-dev/hunk/blob/main/benchmarks/README.md

Enables the opt-in huge fixture tier for benchmarks, which includes approximately 1k files and over 300k diff lines, plus one large file. This can be time-consuming and is excluded by default. Alternatively, set the environment variable HUNK_BENCH_INCLUDE_HUGE=1.

```bash
bun run bench -- --samples 1 --include-huge --out benchmarks/results/local-with-huge.json
```

--------------------------------

### Review session structure with patch (JSON)

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Includes the raw unified diff text in the JSON output. Only add `--include-patch` when an agent truly needs this detailed diff information.

```bash
hunk session review --repo . --include-patch --json
```

--------------------------------

### Generate a Changeset for Release Notes

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Use this command to create a new changeset for user-visible changes. Follow the prompts to select the package and the type of change (patch, minor, or major).

```bash
bun run changeset
```

--------------------------------

### Review session structure (JSON)

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Returns the loaded file and hunk structure in JSON format without dumping the full raw patch. Useful for programmatic access to review details.

```bash
hunk session review --repo . --json
```

--------------------------------

### Load Agent Comments from File

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Use `--agent-context` to render agent-written rationale or notes from a JSON sidecar file beside the diff. This is useful when you already have agent comments prepared.

```bash
hunk diff --agent-context notes.json
```

```bash
hunk patch change.patch --agent-context notes.json
```

--------------------------------

### Create a Session Broker Daemon Engine

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker/README.md

Initialize a SessionBrokerDaemon with the created broker instance and capabilities. This engine handles health requests, message processing, and session management.

```typescript
import { createSessionBrokerDaemon } from "@hunk/session-broker";

const daemon = createSessionBrokerDaemon({
  broker,
  capabilities: {
    version: 1,
    name: "example-broker",
  },
});
```

--------------------------------

### Lint Project Code

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Run the linter to check for code style and potential errors.

```bash
bun run lint
```

--------------------------------

### List active Hunk sessions

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Shows the active Hunk windows. Use this to understand the current state of Hunk sessions.

```bash
hunk session list
```

--------------------------------

### Create HunkDiffFiles from Patch Text

Source: https://github.com/modem-dev/hunk/blob/main/docs/opentui-component.md

Illustrates creating multiple `HunkDiffFile` objects from a multi-file patch string using `createHunkDiffFilesFromPatch`.

```tsx
import { createHunkDiffFilesFromPatch } from "hunkdiff/opentui";

const files = createHunkDiffFilesFromPatch(patchText, "example:patch");
```

--------------------------------

### Architecture Overview

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

A diagram illustrating the flow of data and control within the application, from CLI input to the terminal renderer.

```text
CLI input
  -> parse runtime + config-backed view options
  -> normalize into one Changeset / DiffFile model
  -> App shell coordinates state, layout, and review navigation
  -> pane components render review UI
  -> Pierre-backed terminal renderer draws diff rows
```

--------------------------------

### Apply Hunk Patch for README Screenshot

Source: https://github.com/modem-dev/hunk/blob/main/examples/README.md

This command generates a README screenshot with agent notes, using a patch file, agent context, split mode, and the midnight theme.

```bash
hunk patch examples/6-readme-screenshot/change.patch --agent-context examples/6-readme-screenshot/agent-context.json --mode split --theme midnight
```

--------------------------------

### Use Hunk Package in NixOS

Source: https://github.com/modem-dev/hunk/blob/main/nix/README.md

Include the Hunk package in your NixOS system environment. This makes the Hunk binary available system-wide.

```nix
{ 
  environment.systemPackages = [ 
    inputs.hunk.packages.${pkgs.stdenv.hostPlatform.system}.hunk 
  ];
}
```

--------------------------------

### Run UI Polish Diff

Source: https://github.com/modem-dev/hunk/blob/main/examples/4-ui-polish/README.md

Execute the 'hunk diff' command to compare two versions of a TSX file and view the UI polish changes.

```bash
hunk diff examples/4-ui-polish/before.tsx examples/4-ui-polish/after.tsx
```

--------------------------------

### Run TTY Smoke Test

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Perform a smoke test simulating a real TTY environment.

```bash
bun run test:tty-smoke
```

--------------------------------

### Apply multiple comments from stdin

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Applies multiple notes from a JSON payload via stdin. Each payload item requires `filePath`, `summary`, and a target like `newLine`. Use `--focus` to make the UI jump to the new note.

```bash
printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' \
  | hunk session comment apply --repo . --stdin
```

--------------------------------

### Create Git Diff Alias with Hunk

Source: https://github.com/modem-dev/hunk/blob/main/README.md

Set up opt-in aliases for Git diff and show commands to use Hunk as the pager, without replacing the default Git pager.

```bash
git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff"
git config --global alias.hshow "-c core.pager=\"hunk pager\" show"
```

--------------------------------

### Run Hunk Diff on Two Files

Source: https://github.com/modem-dev/hunk/blob/main/examples/README.md

Use this command for the fastest first run when comparing two specific files.

```bash
hunk diff examples/1-hello-diff/before.ts examples/1-hello-diff/after.ts
```

--------------------------------

### Fast Smoke Test with File Diff

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

Perform a fast smoke test by comparing two files using the `diff` command.

```bash
bun run src/main.tsx -- diff /tmp/before.ts /tmp/after.ts
```

--------------------------------

### Import Core Primitives

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker-core/README.md

Import shared session envelope types and parsing helpers from the core package. Use this package directly only when working on broker internals.

```typescript
import {
  brokerWireParsers,
  parseSessionRegistrationEnvelope,
  parseSessionSnapshotEnvelope,
  SessionBrokerState,
} from "@hunk/session-broker-core";
```

--------------------------------

### GitHub Release Body Format

Source: https://github.com/modem-dev/hunk/blob/main/CLAUDE.md

This is the standard format for the GitHub release body. It includes a 'What's Changed' section and a link to the full changelog.

```markdown
## What's Changed

- <change title> by @<author> in <PR URL>
- ...

**Full Changelog**: https://github.com/modem-dev/hunk/compare/<previous-tag>...<new-tag>
```

--------------------------------

### Run Hunk Patch with Agent Context

Source: https://github.com/modem-dev/hunk/blob/main/examples/3-agent-review-demo/README.md

Execute a Hunk patch file and provide agent context for inline rationale. Ensure the patch and agent context files are correctly specified.

```bash
hunk patch examples/3-agent-review-demo/change.patch \
  --agent-context examples/3-agent-review-demo/agent-context.json
```

--------------------------------

### Configure Hunk Theme and Mode

Source: https://github.com/modem-dev/hunk/blob/main/README.md

Persist Hunk preferences like theme, diff mode, and VCS integration to a TOML configuration file. Supports built-in and custom themes.

```toml
theme = "github-dark-default" # any built-in theme id, auto, or custom
mode = "auto"        # auto, split, stack
vcs = "git"          # git, jj, sl
watch = false
exclude_untracked = false
line_numbers = true
wrap_lines = false
menu_bar = true
agent_notes = false
transparent_background = false
```

--------------------------------

### Serve Session Broker Daemon with Node Adapter

Source: https://github.com/modem-dev/hunk/blob/main/packages/session-broker/README.md

Use the `@hunk/session-broker-node` adapter to serve the SessionBrokerDaemon over HTTP/WebSockets using Node.js. This is an asynchronous operation.

```typescript
import { serveSessionBrokerDaemon } from "@hunk/session-broker-node";

const server = await serveSessionBrokerDaemon({
  daemon,
  hostname: "127.0.0.1",
  port: 47657,
});
```

--------------------------------

### Navigate to the next comment

Source: https://github.com/modem-dev/hunk/blob/main/docs/agent-workflows.md

Moves the live Hunk window to the next comment. Handy when an agent is walking the user through existing notes.

```bash
hunk session navigate --repo . --next-comment
```

--------------------------------

### Update Nix Dependency Lockfile

Source: https://github.com/modem-dev/hunk/blob/main/CONTRIBUTING.md

Run these commands after changing JavaScript or Bun dependencies to regenerate the Nix dependency lockfile. Ensure to add the updated lockfiles to git.

```bash
bun install
bun run nix:update-lock
git add bun.lock nix/bun.lock.nix package.json
```

--------------------------------

### Run Focused Benchmark Scripts

Source: https://github.com/modem-dev/hunk/blob/main/benchmarks/README.md

Executes specific, focused benchmark scripts for targeted performance analysis during development iterations.

```bash
bun run bench:bootstrap-load
```

```bash
bun run bench:working-tree-load
```

```bash
bun run bench:changeset-parse
```

```bash
bun run bench:render-layout
```

```bash
bun run bench:highlight-prefetch
```

```bash
bun run bench:large-stream
```

```bash
bun run bench:interaction-latency
```

```bash
bun run bench:non-ascii-stream
```

```bash
bun run bench:huge-stream
```

```bash
bun run bench:large-stream-profile
```

```bash
bun run bench:memory
```

```bash
bun run bench:navigation-memory
```

```bash
bun run bench:resize-memory
```

```bash
bun run bench:competitors
```

--------------------------------

### Build Named Hunk Package

Source: https://github.com/modem-dev/hunk/blob/main/nix/README.md

Explicitly build the Hunk package using `nix build .#hunk`. This is useful when you have multiple packages defined in your flake.

```bash
nix build .#hunk
```

--------------------------------

### Review Patch from Stdin with Hunk

Source: https://github.com/modem-dev/hunk/blob/main/README.md

Pipe Git diff output to Hunk to review a patch from standard input.

```bash
git diff --no-color | hunk patch -          # review a patch from stdin
```

--------------------------------

### Apply Multiple Comments from Stdin to a Hunk Session

Source: https://github.com/modem-dev/hunk/blob/main/skills/hunk-review/SKILL.md

Apply a batch of comments from JSON payload via stdin to a hunk session. Each comment payload requires `filePath`, `summary`, and a line target. Validates the entire batch before applying. Use `--focus` to jump to the first note.

```bash
printf '%s
' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin [--focus]
```

--------------------------------

### Apply Hunk Patch to Files

Source: https://github.com/modem-dev/hunk/blob/main/examples/README.md

This command is suitable for realistic multi-file reviews using a patch file.

```bash
hunk patch examples/2-mini-app-refactor/change.patch
```

--------------------------------

### Run Hunk Diff for UI Polish

Source: https://github.com/modem-dev/hunk/blob/main/examples/README.md

This command is ideal for generating screenshot-friendly TSX diffs.

```bash
hunk diff examples/4-ui-polish/before.tsx examples/4-ui-polish/after.tsx
```

--------------------------------

### Hunk Test Directory Structure

Source: https://github.com/modem-dev/hunk/blob/main/test/README.md

Outlines the hierarchical structure of the `test/` directory in the Hunk project, detailing the purpose of each subdirectory.

```text
test/
  helpers/   shared unit-test fixtures
  cli/       black-box CLI contracts
  session/   daemon, broker, and session-CLI flows
  pty/       live PTY-driven UI integration
  smoke/     thin terminal transcript sanity checks
```