Set up with your agent

Copy the setup prompt and paste it into the coding agent that works in your project, such as Claude Code, Codex or Cursor. It installs NeedMark, creates needmark.config.ts, connects your development server and tells you how to start reviewing.

Set up NeedMark (https://github.com/mssh21/needmark) in this project. NeedMark is a development-only tool: I point at the UI in the browser and leave comments, which are saved as local files for a coding agent.

1. Run `node -v`. NeedMark needs Node.js 22.12 or newer; if it is older, stop and tell me.
2. Work in the app that has the development server (in a monorepo, that package's folder). Pick the package manager from the nearest lockfile: pnpm-lock.yaml → pnpm, yarn.lock → Yarn, package-lock.json or none → npm. The NeedMark command is then `pnpm exec needmark`, `yarn needmark` or `npx needmark`; below it is written as <needmark>.
3. Install it as a dev dependency: `pnpm add -D needmark`, `yarn add -D needmark` or `npm install -D needmark`.
4. If needmark.config.ts does not exist yet, initialize without questions and connect the development server:
   <needmark> init --language=en --share=local --capture=dom --connect=yes
   Use --share=git instead only if I asked to share feedback through Git.
5. Read the output of init. It adds needmark() to vite.config.* or astro.config.*, or runs a Next.js dev script through `needmark dev --`, and prints each changed line; keep those changes. If it says the development server was not detected, connect it by hand as described in https://github.com/mssh21/needmark/blob/main/docs/getting-started.md#connect-the-development-server. Make no other changes. NeedMark never enters production builds.
6. Run `<needmark> list` and check that it prints `[]`.
7. If you can use MCP servers, ask me whether to register NeedMark so you can read feedback and its screenshots directly. Only if I agree, register it from this folder, for example `claude mcp add needmark -- <needmark> mcp` or `codex mcp add needmark -- <needmark> mcp`.
8. Finish by telling me to start the development server with its usual command and open it as usual: the NeedMark toolbar appears at the bottom of the page. Mention that NEEDMARK=off starts it without NeedMark and `<needmark> remove` undoes the connection.

Install

Requires Node.js 22.12 or newer. In your application project:

pnpm add -D needmark
pnpm exec needmark init
pnpm dev

npm install -D needmark
npx needmark init
npm run dev

yarn add -D needmark
yarn needmark init
yarn dev

Open your app as usual; the NeedMark toolbar appears at the bottom of the page.

init first offers recommended settings: the review screen in your terminal's language, feedback kept on this computer, screenshots redrawn from the page and connecting your development server. Press Enter to accept them, or answer n to choose each one from a list that explains it. It lists every line it changes, and never touches your application source or production builds:

• Vite (React, Vue and others): adds needmark() to plugins in vite.config.*.
• Astro: adds needmark() to vite.plugins in astro.config.*.
• Next.js: starts the dev script through needmark dev --, so the usual port shows the toolbar.

NEEDMARK=off starts the development server without NeedMark for you, enabled: false in needmark.config.ts turns it off for everyone, and needmark remove undoes the connection. For other servers, see Connect the development server.

How you use it

1. Open your app in the development server and press Comment (+) in the toolbar, or Shift+C.
2. Click an element or drag an area. Shift+click selects several elements; Alt/Option+drag selects part of the text.
3. Write the comment, choose Fix, Discuss or Question, and save it with a screenshot or without one.
4. Open Comments, press Copy prompt and paste it into your agent.
5. The agent fixes the code and replies with how it checked the change. Check it yourself, then mark the comment resolved.

What gets saved

Every comment becomes a folder in your project, so any agent with access to the files can read it, and you can keep it local or share it through Git.

.needmark/feedback/<id>/
  comment.md       the comment, page and target
  context.json     selector, component and source location
  screenshot.png   optional, with passwords masked

Let your agent read it directly

Agents that support MCP, such as Claude Code, Codex and Gemini CLI, can list feedback, see its screenshot, reply, resolve and wait for new comments through needmark mcp. It needs no extra server or account and opens no network port.

# Claude Code
claude mcp add needmark -- pnpm exec needmark mcp
# Codex
codex mcp add needmark -- pnpm exec needmark mcp

# Claude Code
claude mcp add needmark -- npx needmark mcp
# Codex
codex mcp add needmark -- npx needmark mcp

# Claude Code
claude mcp add needmark -- yarn needmark mcp
# Codex
codex mcp add needmark -- yarn needmark mcp

Without MCP, the CLI does the same: needmark export, watch, reply and resolve.

Documentation