Skip to content
Projects

Code-Notes

Tool to summarise all code annotation like TODO or FIXME

code-notes

Status: Actively maintained. The has around 190 stars and was last pushed in August 2026.

code-notes is a node.js version of Rails' "rake notes" functionality. It scans your source for annotation comments (NOTE, OPTIMIZE, TODO, HACK, XXX, FIXME, BUG) and summarises them across your whole project, so the promises buried in your codebase actually surface somewhere.

Why a fork

code-notes started life as a fork of , with some inspiration from . fixme did the core job well, but I kept hitting the same walls in real projects: I could not control which directories were scanned, and I could not exclude paths with any flexibility. On any non-trivial codebase, that means either scanning node_modules or not using the tool.

So the fork exists to make scanning scope a first-class concern:

  • Flexibility in defining the source scanning directory
  • Exclude patterns compatible with globbing
  • The ability to read the exclusion list straight from a .gitignore file, so the tool skips exactly what git does
  • Include-only patterns that overwrite any exclusions, for scanning just one slice of a project

code-notes also exits with proper error codes: it terminates with an error code if any annotations are found, which makes it usable as a CI gate ("no FIXMEs reach master").

Installation and usage

npm install code-notes -g

The core options are the scanning-scope ones:

# Exclude any pattern inside of the .gitignore file and ignore hidden files and foldersnotes -g .gitignore -h true
# Exclude everything under src/ and node_modules/, plus any .md filenotes -x src/ -x node_modules/ -x "*.md"
# Only scan .md filesnotes -i "*.md"

Two things to keep in mind: directory exclusions need a trailing slash (node_modules/, not node_modules), and some extension patterns like *.md or *.html have to be wrapped in quotes to reach the tool unexpanded; if a pattern does not seem to work, quote it. The full list of flags (encoding, line-length limits, and so on) is in the .

What the output looks like

Given comments like these somewhere in a file:

// NOTE: This is the sample output for a note!// TODO: This is the sample output for a todo!// FIXME (Mr Author): This is the sample output for a fixme! Seriously fix this...

you get an annotated summary per file:

- path/to/your/directory/file.js [3 messages]:  [Line   1]  ✐ NOTE: This is here because sometimes an intermittent issue appears.  [Line   9]  ✓ TODO: Add a check here to ensure these are always strings.  [Line 136]  ☠ FIXME from Mr Author: We sometimes get an undefined index in this array.

Authors in parentheses, as in // NOTE(Mr Author): ..., are picked up and displayed with the message.

Extending code-notes

If you want annotations beyond the built-in seven, add a definition to lib/messageChecks.js:

todo: {	regex: /[\/\/][\/\*]\s*TODO\s*(?:\(([^:]*)\))*\s*:?\s*(.*)/i,	label: ' ✓ TODO',	colorer: chalk.magenta}

Each definition has three fields: regex extracts the line containing the annotation, label defines what is printed in the console, and colorer takes any valid option. Binary and log file extensions are skipped by default; the skip lists live in lib/notes.js if you need to adjust them.