Annotator

Annotator is a local review and annotation product for working directories, files, plans, code changes, remote pages, and live localhost applications.

It keeps the mature document editor, code-review surface, live selector, diff providers, drafts, keyboard behavior, and responsive interface already proven in this repository. Annotator adds one product identity, permanent review packages, a public SDK, a language-neutral control protocol, and a managed extension system.

Install

npm install --global @astxrtys/annotator

Annotator requires Node.js 22 or newer. Browser-based review workflows currently also require Bun 1.3 or newer; the command explains this clearly if Bun is unavailable.

Open a workspace

cd /path/to/project
annotator

The bare command opens the current directory. It shows the workspace file tree and lets you open supported files without restarting the process.

Open a specific file, folder, or URL:

annotator annotate README.md
annotator annotate docs/specification.md

Review code

annotator review

The code-review workflow retains the repository's existing Git, GitButler, Jujutsu, Perforce, GitHub, and GitLab behavior where available.

Annotate a live application

annotator app

When one web app is running on a standard development port, Annotator finds it automatically. You can still choose an explicit address with annotator app http://localhost:3000 when more than one app is running or the app uses an unusual port.

Annotator mirrors the loopback application through its protected live proxy, keeps supported WebSockets and hot reload working, and preserves precise component selection and anchors.

Retrieve saved reviews

Save and Submit create immutable review packages with permanent UUIDv7 identifiers under Annotator's data directory.

annotator reviews list
annotator reviews get <uuid>
annotator reviews get <uuid> --json
annotator reviews acknowledge <uuid>
annotator reviews export <uuid> --format directory

Retrieving a review does not mark it acknowledged unless you request acknowledgment explicitly.

The default data directory is ~/.annotator, or $XDG_DATA_HOME/annotator when XDG_DATA_HOME is an absolute path. Set ANNOTATOR_DATA_DIR to choose another location.

Use the SDK

Imports do not start servers, open browsers, inspect the current directory, load extensions, or write configuration.

import { createAnnotatorRuntime } from "@astxrtys/annotator/sdk";

const runtime = await createAnnotatorRuntime();
const session = await runtime.sessions.create({
  mode: "plan-review",
  source: { kind: "plan", markdown: "# Proposed change" },
  presentation: { kind: "headless" },
});

await session.addAnnotation({
  type: "comment",
  text: "Clarify the recovery behavior.",
  target: { sourceId: "plan", selectedText: "Proposed change" },
});

const { reviewId } = await session.save({ idempotencyKey: crypto.randomUUID() });
const review = await runtime.reviews.get(reviewId);

await session.dispose();
await runtime.dispose();

The in-memory SDK profile writes nothing to disk. Select filesystem storage explicitly when an embedding application wants Annotator's default persistent adapters.

Embed the complete frontend

React applications can mount the same full plan-review and code-review interface used by Annotator itself. The component chooses the correct mature interface from the session mode; it is not a simplified replacement UI.

import { createRoot } from "react-dom/client";
import { EmbeddedAnnotator } from "@astxrtys/annotator/ui/react";
import "@astxrtys/annotator/ui/styles.css";

createRoot(document.getElementById("root")!).render(
  <EmbeddedAnnotator session={session} />,
);

Use AnnotatorSessionApp when you prefer the descriptive component name; EmbeddedAnnotator is its shorter alias. A host that wants a materially different interface can use @astxrtys/annotator/client or the custom-frontend reference extension and stay entirely on the public session protocol.

Product boundaries

• Core owns sessions, commands, review-package rules, trust, persistence semantics, and lifecycle.
• The SDK lets another application create and operate Annotator runtimes.
• The client connects another frontend or process to an existing runtime.
• Extensions join Annotator through a managed lifecycle and documented contribution registries.
• External product adapters are separate installations and are not shipped as first-party integrations.

Canonical Plannotator remains an upstream source of selected implementation improvements and repository history. It is not installed, launched, or required as a second runtime product.

Development

Use Bun throughout the repository:

bun install
bun test
bun run typecheck
bun run build

bun run build creates the exact npm package contents. The package acceptance suite installs the resulting tarball in an unrelated directory and checks that no command, import, web asset, or schema resolves through the source checkout.

License

MIT or Apache-2.0, at your option. Upstream-derived code retains its applicable notices and provenance.