nota
A code review annotation tool for use with AI agents. Leave structured review comments in your source code, and let your AI agent extract, track, and address them.
Table of Contents
How It Works
- You leave review comments directly in your source code
- Run
/nota — comments are extracted into tracking files (.nota/) and removed from source code
- The agent reads each item and addresses it — fixing bugs, explaining decisions, or discussing tradeoffs
- Resolved items are marked in the tracking file
- Once done, clean up the tracking files
flowchart LR
A["Write comments\nin code"] --> B["Run /nota"]
B --> C["Extract to tracking\n& remove from code"]
C --> D["Agent addresses\neach item"]
D --> E["Mark resolved\n& clean up"]
Comment Syntax
Add review comments using your language's comment syntax with a tag prefix:
// review: this function silently swallows errors
// review(auth): check token expiry before proceeding
// discuss: should we use a mutex here instead?
// explain: why does this retry 3 times?
Tags
These tags are built in. Run nota behavior to see the full list with descriptions, or nota behavior <tag> for details on a specific tag.
| Tag | Purpose |
|---|
review | Bug or issue — the agent fixes it and proposes resolution |
discuss | Needs debate — the agent presents options, waits for agreement |
explain | Wants reasoning — the agent explains, may lead to discussion or change |
impl | Implementation request — the agent writes the code at the annotated location |
refactor | Refactoring — the agent restructures code, preserving behavior |
critique | Critical review — the agent challenges assumptions, finds edge cases |
propose | Request alternatives — the agent suggests options with tradeoffs |
test | Test request — the agent writes tests for the annotated code |
doc | Documentation — the agent writes or improves docs |
see | Cross-reference to a named group (no message) |
also | Cross-reference to a named group (no message) |
You can override any built-in tag or add custom ones. See Extensions.
Grouping
Use a name in parentheses to group related comments:
# review(auth): validate tokens before storing
def store_token(token):
db.save(token)
# review(auth): same issue here — no validation
def refresh_token(token):
db.update(token)
Both comments are grouped under auth and tracked together.
Multi-line Comments
Block comments:
Go/C/C++/Rust/Java... :
/* review(perf): this allocates on every call
consider using a sync.Pool or pre-allocating
the buffer outside the loop */
Consecutive line comments are merged automatically:
Go/C/C++/Rust/Java... :
// review(auth): token validation is missing here
// we need to check expiry and verify the signature
// before granting access
Bash/Python/...
# review(deploy): this assumes the container is already running
# add a health check before calling the endpoint
SQL:
-- review(query): this full table scan needs an index
-- add a composite index on (user_id, created_at)
HTML/Markdown:
<!-- review(docs): this section is outdated
the API changed in v2, update the examples -->
Installation
Claude Code Plugin
Add the marketplace and install the plugin in Claude Code:
/plugin marketplace add urso/nota
/plugin install nota@urso/nota
From Source
If you clone the repository, load the plugin directly:
claude --plugin-dir /path/to/nota
Or add it as a local marketplace for permanent installation:
/plugin marketplace add /path/to/nota
/plugin install nota@nota-plugins
CLI (Optional)
The CLI can be used standalone outside of Claude Code. Requires Go:
go install github.com/urso/nota/cmd/nota@latest
Run nota --help for usage.
Commands
All commands are available as slash commands in Claude Code after installing the plugin.
/nota
The main workflow. Extracts new comments from code, reads open reviews, and addresses each item. The agent triages by tag type — fixing review items, discussing discuss items, and explaining explain items. Pass an optional directive to focus on specific groups or items.
/nota focus on auth group
/nota-list
Peek at review comments in code without extracting. Read-only.
/nota-list --staged
/nota-delete
Delete all review comments from source code permanently without saving them. Asks for confirmation first.
/nota-evaluate