filepath-comments
v1.0.0
Published
Add file path comments to the top of every source file. Great for LLM context, docs, and code reviews.
Maintainers
rayan-mansoorReadme
Filepath-Comments
A CLI tool that automatically adds file path comments to the top of every source file in your project. Useful for providing context when sharing code with LLMs, in documentation, or during code reviews.
What it does
Running filepath-comments on your project adds a comment with the relative file path as the first line of each supported file:
// src/utils/helpers.js
export function formatDate(date) { ... }# lib/parser.py
import json<!-- templates/index.html -->
<!DOCTYPE html>It automatically detects the correct comment syntax for 30+ file types including JavaScript, TypeScript, Python, Ruby, Go, Rust, HTML, CSS, SQL, and more.
Install
npm install -g filepath-commentsOr run directly with npx:
npx filepath-comments .Usage
# Add path comments to all files in current directory
filepath-comments
# Target a specific directory
filepath-comments src/
# Preview changes without writing
filepath-comments --dry-run
# Remove previously added path comments
filepath-comments --remove
# Combine flags
filepath-comments src/ --dry-run --removeConfiguration
The script includes a CONFIG object at the top of the file that you can edit before running. Here's the full reference:
Path Format
| Option | Default | Description |
| --------------- | -------- | -------------------------------------------------------------------- |
| pathSeparator | "unix" | "unix" for forward slashes always, "os" for OS-native separators |
| pathPrefix | "" | Prepended to every path (e.g. "@/" → // @/src/index.ts) |
| pathSuffix | "" | Appended after the path, before the comment closer |
Existing Path Comment Handling
| Option | Default | Description |
| ---------------------- | --------- | --------------------------------------------------------------------------------------------------------- |
| replaceWrongPath | true | If a file has a path comment but the path is wrong (e.g. file was moved), replace it with the correct one |
| overwriteCorrectPath | false | If the path comment is already correct, rewrite it anyway (true) or skip it (false) |
| pathDetectionMode | "exact" | How to detect existing path comments — see Detection Modes |
Blank Line Handling
| Option | Default | Description |
| ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
| blankLineAfterComment | true | Add an empty line after the path comment for visual separation |
| leadingBlankLines | "strip" | When a path comment is found after blank lines: "strip" removes the blank lines, "preserve" keeps them |
File Traversal
| Option | Default | Description |
| ------------------- | ------- | ---------------------------------------------------------- |
| extraSkipDirs | [] | Additional directories to skip (merged with built-in list) |
| extraSkipFiles | [] | Additional files to skip (merged with built-in list) |
| onlyExtensions | [] | Only process these extensions (empty = all supported) |
| excludeExtensions | [] | Skip files with these extensions |
| maxFileSize | 0 | Skip files larger than this (in bytes). 0 = no limit |
Output
| Option | Default | Description |
| --------- | ------- | --------------------------------------- |
| verbose | false | Show individual skipped files in output |
Example Configurations
Prefix all paths with @/:
pathPrefix: "@/",
// Result: // @/src/components/Button.tsxOnly process TypeScript and JavaScript:
onlyExtensions: ["ts", "tsx", "js", "jsx"],Strict mode — never touch existing comments:
replaceWrongPath: false,
overwriteCorrectPath: false,Add blank line after path comment:
blankLineAfterComment: true,
// Result:
// // src/utils/helpers.js
//
// export function formatDate(date) { ... }Detection Modes
The script can detect whether a file already has a path comment, even if it wasn't added by this tool. The pathDetectionMode config controls how this works:
"exact" (default)
Only considers a line a path comment if it exactly matches the format this tool would generate. Any other comment (even one that looks like a path) is left alone.
This mode is useful when:
- Your files have first-line comments that happen to look like paths but aren't
- You want to be conservative and only touch comments you're sure came from this tool
"heuristic"
Matches any first-line comment that looks like a relative file path — it checks if the comment content contains / or \ and ends with a known file extension. Also catches root-level files like // index.js.
This mode is useful when:
- You've moved files and the old path comments are now wrong
- Path comments were added manually or by a different tool
- You want the script to clean up inconsistent path comments
Behavior
- Shebang-aware — if a file starts with
#!, the path comment is inserted on line 2. - Blank-line tolerant — detects existing path comments even if there are leading blank lines before them. Configurable to strip or preserve those blank lines.
- Idempotent — running it multiple times won't add duplicate comments.
- Smart replacement — detects wrong/outdated path comments and replaces them (e.g. after moving a file). Controlled by
replaceWrongPath. - Non-destructive removal —
--removedetects and strips path comments using the same detection logic, including through leading blank lines. - Auto-skips common directories (
node_modules,.git,.next,dist,build,vendor,__pycache__,.idea,.vscode) and files (package-lock.json,yarn.lock,.DS_Store).
Supported Languages
| Comment Style | Extensions |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| // path | js, jsx, ts, tsx, java, kt, kts, swift, go, rs, c, cpp, h, hpp, cs, dart, scala, groovy, php, scss, sass, less |
| # path | py, rb, sh, bash, zsh, yml, yaml, toml, pl, r |
| <!-- path --> | html, htm, xml, svg, vue |
| /* path */ | css |
| -- path | sql, lua |
License
MIT