surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

		@@ -1,0 +1,24 @@
	1	+# Mods
	2	+
	3	+A mod is a Claude Code plugin whose behaviour lives in a hooks module: one
	4	+`register(on, options)` entry that hooks the engine's events as functions
	5	+`($, e, next)`. These three ship inside Claude Code; this folder is their
	6	+source, published as it is built into the binary.
	7	+
	8	+\| Mod \| What it does \| Seated \|
	9	+\| --- \| --- \| --- \|
	10	+\| [`sec-default`](sec-default) \| Keeps an organization's classic hooks, prompt content, managed settings and tool policy out of reach of the plugins a person installs; adds no policy of its own. \| Outermost, on a machine with managed settings or for a Team or Enterprise organization, unless managed `prependPlugins` says otherwise \|
	11	+\| [`diff`](diff) \| `/diff`: the session's uncommitted changes in a pane beside the transcript, file by file with their hunks, refreshed as Claude edits files and runs commands. \| Built in \|
	12	+\| [`telemetry`](telemetry) \| Adds `$.telemetry` (`log`, `mark`) in the `engine.create` fold so a plugin can record an event as a first-party analytics row; sends nothing wherever Claude Code's analytics are off. \| Built in \|
	13	+
	14	+Each folder is a complete plugin: `.claude-plugin/plugin.json`, a
	15	+`hooks/hooks.json` naming the module, and TypeScript under `hooks/` typed
	16	+against the declarations `/plugin-types` writes (`import type … from
	17	+'claude-code'`). To read one running from source:
	18	+
	19	+ claude --plugin-dir mods/diff
	20	+
	21	+Early access: hooks modules load only where function hooks are enabled, and
	22	+the API these mods are written against may change between releases without
	23	+notice. They are not listed in this repository's marketplace; the copies that
	24	+matter are the ones already in your Claude Code.

		@@ -1,0 +1,8 @@
	1	+{
	2	+ "name": "diff",
	3	+ "version": "0.1.0",
	4	+ "description": "The diff pane as a plugin: /diff opens the session's uncommitted changes beside the transcript, file by file with their hunks, refreshed as Claude edits and runs commands; the first edit opens it where the terminal is wide enough, and a file's ask button rides its hunks on the next prompt.",
	5	+ "author": {
	6	+ "name": "Anthropic"
	7	+ }
	8	+}

		@@ -1,0 +1,54 @@
	1	+# diff
	2	+
	3	+The diff pane as a plugin: `/diff` opens the session's uncommitted changes
	4	+beside the transcript, one row per changed file and the selected file's
	5	+hunks beneath, and closes it again. The pane refreshes as Claude edits,
	6	+runs shell commands and finishes turns, and while it is open it polls the
	7	+repository's HEAD so a commit or checkout made elsewhere shows too. The
	8	+first successful edit of a session opens the pane by itself where the
	9	+terminal is wide enough (144 columns when the person never chose, 110 when
	10	+they kept it open before; a person who closed it is left alone). A file's
	11	+ask button arms that file: its hunks ride the next prompt as context, once.
	12	+
	13	+The pane compares the working tree against HEAD, split at the session's
	14	+start (the default), against HEAD plainly, or against the merge-base with
	15	+the default branch; the choice is kept per repository in the plugin's
	16	+store. A second picker shows one earlier turn's edits instead of the
	17	+working tree, read from the session's messages. Files that changed before
	18	+the session started, and noise (lockfiles, generated and test files), are
	19	+listed apart and folded until asked for. Outside a git repository `/diff`
	20	+says so and does nothing else.
	21	+
	22	+`hooks/register.ts` is the module; everything under `hooks/` is its parts.
	23	+
	24	+## What it hooks
	25	+
	26	+\| event \| what the hook does \|
	27	+\| --- \| --- \|
	28	+\| `session.start` \| Binds the engine once, registers `/diff` (a session where another `/diff` is listed leaves the plugin idle), and pins the repository. \|
	29	+\| `ui.render` of `PromptHint` \| Reads the terminal's width, which decides whether the first edit opens the pane. \|
	30	+\| `ui.render` of `Pane` \| Draws the pane: header, the file list, the toggles, the base and source pickers, and the selected file's hunks. \|
	31	+\| `command.run` of `diff` \| Opens or closes the pane and remembers the choice. \|
	32	+\| `command.run` of `clear`, `resume` \| Closes the pane and forgets the session's state. \|
	33	+\| `tool.call` of `Edit`, `Write`, `NotebookEdit` \| After the edit, refreshes an open pane; the session's first successful edit opens it. \|
	34	+\| `tool.call` of `Bash`, `PowerShell` \| After the command, refreshes an open pane. \|
	35	+\| `turn.complete` \| Refreshes an open pane. \|
	36	+\| `prompt.submit` \| Adds the armed file's hunks to the prompt's context and disarms. \|
	37	+
	38	+## What it calls on `$`
	39	+
	40	+`clock.after`, `clock.every`, `clock.now`, `clock.sleep`, `command.register`,
	41	+`fs.list`, `fs.read`, `fs.stat`, `process.run` (git, read-only), `session.messages`,
	42	+`store.get`, `store.set`, `telemetry.log`, `telemetry.mark`, `ui.close`,
	43	+`ui.invalidate`, `ui.log`, `ui.open`, `ui.resolve`, `ui.status`.
	44	+
	45	+`$.telemetry` is the telemetry plugin's noun; where it is absent the rows
	46	+are dropped and nothing else changes.
	47	+
	48	+## Try it
	49	+
	50	+```sh
	51	+claude --plugin-dir /path/to/diff
	52	+```
	53	+
	54	+then `/diff` inside a git repository with a modified file.

		@@ -1,0 +1,9 @@
	1	+/**
	2	+ * A value a tool stored as the array it is, or an empty one when it is
	3	+ * anything else.
	4	+ *
	5	+ * @param value a field of a tool's input or result
	6	+ * @returns the array's items, unknown each
	7	+ */
	8	+export const arrayOf = (value: unknown): readonly unknown[] =>
	9	+ Array.isArray(value) ? value : []

		@@ -1,0 +1,3 @@
	1	+export * from './array-of.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,9 @@
	1	+/**
	2	+ * The file the person asked about from the pane: its path and its diff as
	3	+ * text, held until the next prompt carries it as context.
	4	+ */
	5	+export type ArmedAsk = {
	6	+ path: string
	7	+ text: string
	8	+ lines: number
	9	+}

		@@ -1,0 +1,3 @@
	1	+export type * from './armed-ask.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,31 @@
	1	+import type Git from '../git'
	2	+import Limits from '../limits'
	3	+import type { ArmedAsk } from './armed-ask'
	4	+
	5	+/**
	6	+ * A file's diff as the context block the next prompt carries when the
	7	+ * person presses ask.
	8	+ *
	9	+ * A line saying where it came from, then the hunks in unified form, cut at
	10	+ * MAX_LINES_PER_FILE lines.
	11	+ *
	12	+ * @param path the file's repository-relative path
	13	+ * @param hunks its hunks as the pane shows them
	14	+ * @returns the armed ask
	15	+ */
	16	+export function armedAskOf(path: string, hunks: readonly Git.Hunk[]): ArmedAsk {
	17	+ const body = hunks
	18	+ .flatMap(hunk => [
	19	+ `@@ -${hunk.oldStart} +${hunk.newStart} @@`,
	20	+ ...hunk.lines,
	21	+ ])
	22	+ .slice(0, Limits.MAX_LINES_PER_FILE)
	23	+
	24	+ return {
	25	+ path,
	26	+ text:
	27	+ `The user attached the diff of ${path} from the diff pane to this ` +
	28	+ `prompt:\n${body.join('\n')}`,
	29	+ lines: body.length,
	30	+ }
	31	+}

		@@ -1,0 +1,4 @@
	1	+export * from './armed-ask'
	2	+export * from './armed-ask-of.js'
	3	+
	4	+export * as default from '.'

		@@ -1,0 +1,7 @@
	1	+/**
	2	+ * A `/`-separated path's last segment: the file's own name.
	3	+ *
	4	+ * @param path the repository-relative path
	5	+ * @returns the base name
	6	+ */
	7	+export const baseNameOf = (path: string) => path.split('/').at(-1) ?? path

		@@ -1,0 +1,28 @@
	1	+/**
	2	+ * Path segments of build output, vendored code, caches and snapshots, the
	3	+ * engine's excluded directories, matched against `/<path>`.
	4	+ */
	5	+export const GENERATED_DIRECTORIES = [
	6	+ '/dist/',
	7	+ '/build/',
	8	+ '/out/',
	9	+ '/output/',
	10	+ '/node_modules/',
	11	+ '/vendor/',
	12	+ '/vendored/',
	13	+ '/third_party/',
	14	+ '/third-party/',
	15	+ '/external/',
	16	+ '/.next/',
	17	+ '/.nuxt/',
	18	+ '/.svelte-kit/',
	19	+ '/coverage/',
	20	+ '/__pycache__/',
	21	+ '/.tox/',
	22	+ '/venv/',
	23	+ '/.venv/',
	24	+ '/target/release/',
	25	+ '/target/debug/',
	26	+ '.generated/',
	27	+ '/__snapshots__/',
	28	+] as const

		@@ -1,0 +1,21 @@
	1	+/**
	2	+ * File-name shapes of generated code, the engine's excluded file-name
	3	+ * patterns: minified, bundled, stubs, specs, snapshots.
	4	+ */
	5	+export const GENERATED_FILENAME_PATTERNS: readonly RegExp[] = Object.freeze([
	6	+ /\.min\.[a-z]+$/i,
	7	+ /-min\.[a-z]+$/i,
	8	+ /\.bundle\.[a-z]+$/i,
	9	+ /\.generated\.[a-z]+$/i,
	10	+ /\.gen\.[a-z]+$/i,
	11	+ /\.auto\.[a-z]+$/i,
	12	+ /_generated\.[a-z]+$/i,
	13	+ /_gen\.[a-z]+$/i,
	14	+ /\.pb\.(?:go\|js\|ts\|py\|rb)$/i,
	15	+ /_pb2?\.py$/i,
	16	+ /\.pb\.h$/i,
	17	+ /\.grpc\.[a-z]+$/i,
	18	+ /\.swagger\.[a-z]+$/i,
	19	+ /\.openapi\.[a-z]+$/i,
	20	+ /\.snap$/i,
	21	+])

		@@ -1,0 +1,18 @@
	1	+/**
	2	+ * File names (lowercase) that are lockfiles or shrinkwraps, never hand
	3	+ * written, so their churn is noise in a diff.
	4	+ */
	5	+export const GENERATED_FILENAMES: ReadonlySet<string> = new Set([
	6	+ 'package-lock.json',
	7	+ 'yarn.lock',
	8	+ 'pnpm-lock.yaml',
	9	+ 'bun.lockb',
	10	+ 'bun.lock',
	11	+ 'composer.lock',
	12	+ 'gemfile.lock',
	13	+ 'cargo.lock',
	14	+ 'poetry.lock',
	15	+ 'pipfile.lock',
	16	+ 'shrinkwrap.json',
	17	+ 'npm-shrinkwrap.json',
	18	+])

		@@ -1,0 +1,15 @@
	1	+/**
	2	+ * Extensions, simple and compound (lowercase), of minified, bundled or
	3	+ * generated output, the engine's excluded extensions.
	4	+ */
	5	+export const GENERATED_SUFFIXES = [
	6	+ '.lock',
	7	+ '.min.js',
	8	+ '.min.css',
	9	+ '.min.html',
	10	+ '.bundle.js',
	11	+ '.bundle.css',
	12	+ '.generated.ts',
	13	+ '.generated.js',
	14	+ '.d.ts',
	15	+] as const

		@@ -1,0 +1,3 @@
	1	+export * from './base-name-of.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,7 @@
	1	+export * from './base-name-of'
	2	+export * from './is-generated-file'
	3	+export * from './is-noise-file.js'
	4	+export * from './is-test-file'
	5	+export * from './rooted-path-of'
	6	+
	7	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export * from './generated-directories.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export * from './generated-filename-patterns.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export * from './generated-filenames.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export * from './generated-suffixes.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,7 @@
	1	+export * from './generated-directories'
	2	+export * from './generated-filename-patterns'
	3	+export * from './generated-filenames'
	4	+export * from './generated-suffixes'
	5	+export * from './is-generated-file.js'
	6	+
	7	+export * as default from '.'

		@@ -1,0 +1,28 @@
	1	+import { baseNameOf } from '../base-name-of'
	2	+import { rootedPathOf } from '../rooted-path-of'
	3	+import { GENERATED_DIRECTORIES } from './generated-directories'
	4	+import { GENERATED_FILENAME_PATTERNS } from './generated-filename-patterns'
	5	+import { GENERATED_FILENAMES } from './generated-filenames'
	6	+import { GENERATED_SUFFIXES } from './generated-suffixes'
	7	+
	8	+/**
	9	+ * Whether a repository-relative path names generated or vendored content,
	10	+ * by the Linguist-style rules the engine's own diff panel applies.
	11	+ *
	12	+ * @param path the file's path from the repository root, `/`-separated
	13	+ * @returns whether the diff pane counts it among the tests and generated files
	14	+ */
	15	+export function isGeneratedFile(path: string) {
	16	+ const name = baseNameOf(path).toLowerCase()
	17	+ const rooted = rootedPathOf(path)
	18	+ const hasGeneratedSuffix = GENERATED_SUFFIXES.some(suffix =>
	19	+ name.endsWith(suffix),
	20	+ )
	21	+
	22	+ return (
	23	+ GENERATED_FILENAMES.has(name) \|\|
	24	+ hasGeneratedSuffix \|\|
	25	+ GENERATED_DIRECTORIES.some(directory => rooted.includes(directory)) \|\|
	26	+ GENERATED_FILENAME_PATTERNS.some(pattern => pattern.test(name))
	27	+ )
	28	+}

		@@ -1,0 +1,12 @@
	1	+import { isGeneratedFile } from './is-generated-file'
	2	+import { isTestFile } from './is-test-file'
	3	+
	4	+/**
	5	+ * Whether a changed file is hidden behind the pane's tests-and-generated
	6	+ * line until the person asks to see it.
	7	+ *
	8	+ * @param path the file's path from the repository root
	9	+ * @returns whether it is a test or a generated file
	10	+ */
	11	+export const isNoiseFile = (path: string) =>
	12	+ isTestFile(path) \|\| isGeneratedFile(path)

		@@ -1,0 +1,5 @@
	1	+export * from './is-test-file.js'
	2	+export * from './test-directories'
	3	+export * from './test-filename-patterns'
	4	+
	5	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export * from './test-directories.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,16 @@
	1	+/**
	2	+ * Path segments of tests, specs, mocks and fixtures, the engine's test
	3	+ * directories, matched against `/<path>`.
	4	+ */
	5	+export const TEST_DIRECTORIES = [
	6	+ '/test/',
	7	+ '/tests/',
	8	+ '/spec/',
	9	+ '/specs/',
	10	+ '/__tests__/',
	11	+ '/__mocks__/',
	12	+ '/__snapshots__/',
	13	+ '/__fixtures__/',
	14	+ '/fixtures/',
	15	+ '/testdata/',
	16	+] as const

		@@ -1,0 +1,11 @@
	1	+/**
	2	+ * File-name shapes of test files and snapshots, the engine's test file-name
	3	+ * patterns.
	4	+ */
	5	+export const TEST_FILENAME_PATTERNS: readonly RegExp[] = Object.freeze([
	6	+ /\.test\.[a-z]+$/i,
	7	+ /\.spec\.[a-z]+$/i,
	8	+ /_test\.[a-z]+$/i,
	9	+ /_spec\.[a-z]+$/i,
	10	+ /\.snap$/i,
	11	+])

		@@ -1,0 +1,3 @@
	1	+export * from './rooted-path-of.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,8 @@
	1	+/**
	2	+ * A path with exactly one leading `/`, so a directory pattern like `/test/`
	3	+ * matches at the start of a relative path too.
	4	+ *
	5	+ * @param path the repository-relative path
	6	+ * @returns the rooted path
	7	+ */
	8	+export const rootedPathOf = (path: string) => `/${path.replace(/^\/+/, '')}`

		@@ -1,0 +1,10 @@
	1	+import Names from '../names'
	2	+
	3	+/**
	4	+ * What `session.start` hands `$.command.register`: the one place the
	5	+ * `/diff` spec is built, where a later CommandSpec field joins.
	6	+ */
	7	+export const COMMAND_SPEC = {
	8	+ name: Names.COMMAND_NAME,
	9	+ description: Names.COMMAND_DESCRIPTION,
	10	+} as const

		@@ -1,0 +1,3 @@
	1	+export * from './command-spec.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,10 @@
	1	+/**
	2	+ * How many items of a list pass a test, without the intermediate array a
	3	+ * filter would build.
	4	+ *
	5	+ * @param items the list
	6	+ * @param passes the test
	7	+ * @returns the number of passing items
	8	+ */
	9	+export const countOf = <T>(items: readonly T[], passes: (item: T) => boolean) =>
	10	+ items.reduce((total, item) => total + (passes(item) ? 1 : 0), 0)

		@@ -1,0 +1,3 @@
	1	+export * from './count-of.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,17 @@
	1	+import type Git from '../git'
	2	+import type { Host } from '../host'
	3	+
	4	+/**
	5	+ * A directory's entries by name with their own kinds, through the host's
	6	+ * listing (no link followed); null when it cannot be listed.
	7	+ *
	8	+ * @param engine the bound host
	9	+ * @returns the probe (GitDeps `entryKindsOf`)
	10	+ */
	11	+export const entryKindsOf =
	12	+ (engine: Host) =>
	13	+ (dir: string): Promise<ReadonlyMap<string, Git.EntryKind> \| null> =>
	14	+ engine.listDir(dir).then(
	15	+ entries => new Map(entries.map(entry => [entry.name, entry.kind])),
	16	+ () => null,
	17	+ )