# Review Comments AI

*[Deutsch](README.de.md) · [日本語](README.ja.md)*

Review comments for Obsidian, built for **working with the AI tools already on your
machine**. Highlight a passage, write what bothers you, and let Claude Code, an editor
assistant or a local LLM do the work: the whole discussion lives inside the `.md` file as
[CriticMarkup](http://criticmarkup.com/), so the tool reads the note, follows the thread,
edits the text and answers in place. No export, no side database, nothing leaves your vault.

The plugin itself has no network access — it only prepares the ground for whatever tool you
already trust: an instruction block your agent can follow, a review report you can hand over,
and a panel that shows what is still waiting for you.

> Fork of [shotashirai1719/obsidian-review-comments](https://github.com/shotashirai1719/obsidian-review-comments)
> by Shota Shirai (AGPL-3.0). It uses its own plugin id (`review-comments-ai`) so both can
> be installed side by side and an update of the original never overwrites this fork.

## What this fork changes

**Resolving means replying, not deleting.** In the original, “Resolve” removed the comment
from the file — the reasoning was gone, and an AI could no longer tell what the passage was
about. Here every reply appends another block to the same thread:

```markdown
{==She walked slowly to the door.==}{>>you|2026-08-23|EDIT: too tame, needs tension<<}{>>AI|2026-08-23|REPLY: rewrote it, the hesitation now sits in the rhythm<<}{>>you|2026-08-23|DONE: good<<}
```

The thread stays in the note until you deliberately clear it — one by one, per note, or
across the whole vault.

| | |
|---|---|
| **Reply threads** | Any number of replies per passage, resolved threads can be reopened |
| **Suggestion mode** | `{++insert++}`, `{--delete--}`, `{~~old~>new~~}` with accept/reject |
| **Selectable scope** | The panel covers this note, the folder, or the entire vault |
| **Filters** | Open (your turn), waiting for a reply, all open, resolved — plus type, author, full-text search |
| **Review report** | All open items as a markdown file or on the clipboard — ready to hand to an AI |
| **Three languages** | German, English and Japanese interface, optionally following Obsidian’s language |

Bugs fixed from the original: resolving matched the first identical piece of text rather
than the known position; resolving rewrote the whole document via `setValue()`, discarding
undo history and cursor position; the panel re-parsed the entire note on every keystroke.

## Usage

1. Select text → pick a type from the floating bar (❓ Ask, ✏️ Edit, 👍 Praise, 💬 Note) or a
   suggestion (➕ ➖ 🔁).
2. Open the panel (ribbon icon or the **Open comments panel** command).
3. Per card: **Jump**, **Reply**, **Done**, **Clear**.

Useful hotkeys: `Ctrl + Shift + M` for “Edit comment”, `Ctrl + Shift + R` for “Reply to
comment at cursor”.

### Commands

- Add a comment of the four types to the selection
- Reply to / resolve the comment at the cursor
- Suggest insertion / deletion / substitution · accept or reject at the cursor
- Clear resolved threads (this note / whole vault)
- Export the review report or copy it to the clipboard
- Copy the AI working instructions to the clipboard, or save them as a note in the vault

## The format

```
{==highlighted passage==}{>>author|date|TYPE: text<<}[{>>author|date|REPLY: …<<}…]
```

- **Types that open a thread:** `ASK`, `EDIT`, `PRAISE`, `NOTE`
- **Types that get appended:** `REPLY`, `DONE`
- **A thread is open until someone closes it with a `DONE`** — that is the whole state, and
  a block written after a `DONE` opens it again. Who wrote last is not a state but a point of
  view: the panel's **Open** filter hides threads where you wrote last, because those are
  waiting on someone else. The block type never affects any of this, so a reply phrased as a
  question cannot go missing.
- Suggestions: `{++insert++}`, `{--delete--}`, `{~~old~>new~~}` — each optionally followed by
  a comment block giving the reason.

Comments written by the original plugin (`{>>author|date: text<<}`) are still read.

## Working with AI agents

The plugin ships the instructions an agent needs. **Copy AI working instructions to
clipboard** puts them on the clipboard, **Save AI working instructions as a note** drops them
into the vault, and every exported review report carries a short version in its header.

The gist: comments stay in the note, an agent works as `Agent` (configurable) by appending a
block, and marks a thread `DONE` once the change is really in the text — nothing is ever
deleted. If it needs a decision it answers instead, which hands the thread back to you. Its
work is every open thread where you wrote last; everything it answered lands on your side. The full text is in [`AI-PROMPT.md`](AI-PROMPT.md), generated from
`src/agent-instructions.ts`.

## The bridge: let your AI tool work through the threads

`bridge/review-bridge.mjs` hands the open threads of a vault to the `claude` CLI already on
your machine — or to any other command — and writes the answers back as CriticMarkup:

```bash
node bridge/review-bridge.mjs --vault ~/Vaults/MyNovel --author Alex --dry-run
```

It picks exactly the threads waiting on an answer: open, and you wrote last. Proposed wording
is never written into your prose directly but placed **inside** the highlight as a CriticMarkup
substitution, so you accept or reject it with one click. Every touched note is backed up first.

The bridge bundles the plugin's own parser and instructions at runtime — one format, one
implementation. Details in [`bridge/README.md`](bridge/README.md).

## Installation

From a release: download `main.js`, `manifest.json` and `styles.css` from the
[latest release](https://github.com/mikeGafert/obsidian-review-comments-ai/releases/latest)
into `<vault>/.obsidian/plugins/review-comments-ai/`, then enable the plugin in
Settings → Community plugins.

From source:

```bash
npm install
npm run build
# copy main.js, manifest.json and styles.css into
# <vault>/.obsidian/plugins/review-comments-ai/
```

For several vaults at once: copy `deploy-targets.example.json` to `deploy-targets.json`, list
your vault paths (that file is gitignored), then run `npm run deploy`.

## Development

```bash
npm run dev     # esbuild in watch mode
npm run build   # production build
npm test        # parser tests, no Obsidian required
```

Sources under `src/`: `parser.ts` (format and mutations), `main.ts` (plugin and commands),
`view.ts` (panel), `decorations.ts` (live preview and reading mode), `modals.ts`,
`settings.ts`, `i18n.ts`, `types.ts`, `locales/`.

Interface strings live in `src/locales/`. German is the source language; English and
Japanese are derived from it. Corrections to the translations are welcome.

## AI disclosure

This fork was developed with substantial assistance from a large language model (Claude).
The English interface strings and the translated READMEs are **machine-translated** from the
German source and have not been reviewed by a native speaker.

Japanese is mixed: wording that already existed in the original plugin comes from its author
and was carried over unchanged — everything this fork added on top is machine-translated.
The header of `src/locales/ja.ts` says which is which. Please report anything that reads
wrong.

The plugin itself sends nothing anywhere: it has no network access, no telemetry, and stores
its data exclusively in your own notes and in the plugin’s `data.json`.

## Licence

AGPL-3.0-or-later, like the original. © Shota Shirai (original work), modifications
© Mike Stephan.