naming-conventions

Naming Conventions

The pattern

Claude Code uses a set of naming conventions that encode the role of a file or identifier in its name. A file named BashTool.tsx is a Tool implementation with UI concerns. A file named BashTool.ts is a Tool implementation with no UI. A function named isConcurrencySafe returns a boolean about concurrency. A function named getBranch fetches a value. A constant named MAX_STATUS_CHARS is a numeric limit. These are not accidental — reading the name tells you the role without reading the implementation.

Why this matters

At ~512K lines across 1,884 files, Claude Code is too large for any individual to hold in memory. Naming conventions serve as a file-system-level type system: you can predict what's in a file before opening it. AgentTool/AgentTool.tsx will export a Tool<Input, Output> that has UI progress output. state/AppStateStore.ts will export the AppState type and initial state. hooks/useCanUseTool.ts will export a React hook returning a permission-checking function.

How to apply it

Files:

• Tools: src/tools/[Name]Tool/[Name]Tool.ts[x] — .tsx if the tool renders JSX output
• Commands: src/commands/[kebab-name]/index.ts or src/commands/[kebab-name].ts
• React hooks: src/hooks/use[Name].ts — always prefixed with use
• React components: src/components/[Name].tsx
• Utilities: src/utils/[name].ts — lowercase, describe the domain (e.g., git.ts, path.ts)
• Types: src/types/[name].ts — lowercase file, PascalCase exports

Identifiers:

• Types, interfaces, classes: PascalCase (e.g., ToolUseContext, AppState, PermissionResult)
• Functions: camelCase starting with a verb (e.g., createTaskStateBase, normalizeMessages, getGitStatus)
• Booleans and boolean-returning functions: is/has prefix (e.g., isConcurrencySafe, isReadOnly, hasWorktreeChanges, isENOENT)
• Event handlers and callbacks: on[Event] prefix (e.g., onProgress, onChangeAppState, onCompactProgress)
• Constants: UPPER_SNAKE_CASE for numeric/string limits; PascalCase for object constants (e.g., MAX_STATUS_CHARS, IDLE_SPECULATION_STATE)
• Tool exports: named constant matching the file name (e.g., export const BashTool, export const FileReadTool)
• Async functions: same naming as sync — the Promise return type is the indicator, not a naming convention