How Claude HUD Extracts Path Levels (1-3 Directories) from the Current Working Directory

Claude HUD extracts 1-3 directory levels from the current working directory by splitting the path on forward and back slashes, then slicing the last N segments based on the configurable pathLevels setting.

The open-source Claude HUD plugin for Claude Code displays a condensed project path on the status line to keep terminal output readable. According to the jarrodwatts/claude-hud source code, this feature tokenizes the current working directory (cwd) and renders only the deepest directories as specified by user configuration.

How Path Extraction Works in Claude HUD

The extraction logic follows a five-step pipeline implemented in the renderer modules:

1. Read cwd from stdin – The plugin receives the current working directory via ctx.stdin.cwd from the JSON data that Claude Code sends to the plugin (see src/types.ts line 6).

2. Split into path segments – The code splits the string on both forward (/) and back-slash (\) characters to ensure cross-platform compatibility between Unix and Windows systems:

const segments = ctx.stdin.cwd.split(/[/\\]/).filter(Boolean);

(See src/render/session-line.ts lines 56-58.)

3. Determine how many levels to keep – The configuration object (ctx.config) may specify pathLevels with a value of 1, 2, or 3. If omitted, the default is 1, defined in src/config.ts (pathLevels: 1, lines 43 and 81).

4. Select the last N segments – Using Array.slice(-pathLevels), the implementation keeps only the deepest N directories:

const projectPath = segments.length > 0
    ? segments.slice(-pathLevels).join('/')
    : '/';

(See src/render/session-line.ts lines 60-63 and render/lines/project.ts lines 24-25.)

5. Render the result – The shortened path is colored via yellow(projectPath) and appended to the status line (see src/render/session-line.ts line 63).

Implementation Details in the Source Code

Parsing the Current Working Directory from stdin

The renderer accesses the current working directory through the stdin context object. In src/types.ts line 6, the type definition specifies cwd as a string property on the stdin object. The render functions receive this via ctx.stdin.cwd, ensuring the plugin always displays the active directory where Claude Code is executing.

Tokenizing Paths for Cross-Platform Support

Claude HUD handles both Unix and Windows path separators using a regular expression split. The code in src/render/session-line.ts lines 56-58 splits on / or \ and filters out empty strings to handle trailing slashes or root paths consistently:

const segments = ctx.stdin.cwd.split(/[/\\]/).filter(Boolean);

This produces an array of directory names regardless of the operating system's path format.

Configuring the pathLevels Setting

Users control the display depth through the pathLevels configuration option. Defined in src/config.ts lines 43 and 81, the setting accepts values 1, 2, or 3, defaulting to 1 when unspecified. The configuration flows through the context object (ctx.config) to the render functions, allowing dynamic adjustment of how many parent directories appear in the HUD.

Slicing and Formatting the Output

The final extraction occurs in src/render/session-line.ts lines 60-63. After validating that segments exist, the code uses negative indexing to capture the tail of the array:

const projectPath = segments.length > 0
    ? segments.slice(-pathLevels).join('/')
    : '/';

The same logic appears in render/lines/project.ts lines 24-25 for the dedicated project line renderer. The result is joined with forward slashes for consistent display formatting, then passed to the yellow() color utility before rendering.

Practical Code Example

To display the last two directories of a deep path:

// Example stdin: { "cwd": "/Users/alice/projects/awesome-app/src/components" }
// Configuration: { "pathLevels": 2 }

const cwd = "/Users/alice/projects/awesome-app/src/components";
const segments = cwd.split(/[/\\]/).filter(Boolean);
// Result: ['Users', 'alice', 'projects', 'awesome-app', 'src', 'components']

const pathLevels = 2;
const displayed = segments.slice(-pathLevels).join('/');
// Result: "src/components"

console.log(displayed); // → src/components

Changing to three levels would capture awesome-app/src/components instead.

Summary

• Claude HUD receives the current working directory via ctx.stdin.cwd from Claude Code's stdin JSON.
• The path is tokenized using .split(/[/\\]/) to support both Unix and Windows filesystems.
• The pathLevels configuration option (default: 1, max: 3) controls how many directory levels display.
• The implementation uses Array.slice(-pathLevels) to extract the deepest segments from the path array.
• Source files src/render/session-line.ts and render/lines/project.ts contain the core extraction logic, while src/config.ts defines the default settings.

Frequently Asked Questions

What is the default number of path levels displayed in Claude HUD?

The default is 1 directory level. This is defined in src/config.ts lines 43 and 81, where the pathLevels property defaults to 1 if the user does not specify an alternative in their configuration.

How does Claude HUD handle Windows paths with backslashes?

The code uses a regular expression /[/\\]/ to split the path string on both forward slashes and backslashes (see src/render/session-line.ts line 57). This ensures the extraction works correctly across Unix, macOS, and Windows operating systems.

Can I display more than 3 directory levels in Claude HUD?

No, the configuration is designed to accept only 1, 2, or 3 levels as defined in the TypeScript types and configuration schema. The default of 1 and maximum of 3 keeps the status line concise regardless of project depth.

Where is the path extraction logic located in the repository?

The primary implementation resides in src/render/session-line.ts lines 56-63, with an additional implementation in render/lines/project.ts lines 24-25. Configuration defaults are set in src/config.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}