Comments

A comment is a note pinned to an element: “this heading wraps badly on phones”, with a screenshot if you like. What makes it useful is what’s saved with it. Each comment records where its element is written, as file:line:col, so whoever reads it (you, a teammate, a coding agent) knows which line it’s about.

Comments work in every project midcode can open, including the ones it can show but not edit.

Leave a comment

1. 1

   Press C, or click “Comment” in the toolbar. The pointer becomes a crosshair and the left panel shows “Comments”.

2. 2

   Click an element in any frame. A blue pin marks the spot.

3. 3

   Write in “New comment”, in the right panel. The element and its file:line are shown above the text.

4. 4

   Press ⌘↵, or click “Comment”.

To attach files, click “Attach”, drop them on the panel, or paste an image into the text. A comment can be only files.

You stay in the comment tool, so you can click the next element right away. Press V to go back to inspecting. Esc gets there too: it first closes the comment that’s open, then puts the tool away.

Two other ways in, without changing tool: select an element and click “Comment on this element” at the top of the right panel, or right-click an element and choose “Comment”. These pin the comment to the middle of the element.

A comment belongs to the page it was made on, and remembers the breakpoint and its width: /pricing, Phone, 390 px. Made while editing a component, it belongs to the page the component is shown on.

Pins

Each comment has a numbered pin where you clicked. Pins show while the comment tool is on or the “Comments” list is open, and hide otherwise, so the page stays clean while you design.

Click a pin to open its comment. A pin follows its element: it’s placed by where the element is now, at the same spot inside it, in every breakpoint’s frame.

Read, resolve and delete

The “Comments” list replaces the left panel’s tab while it’s open. Close it with the ✕, Esc, or by leaving the comment tool. The comment button in the toolbar shows how many are open.

• –

  The menu at the top switches between “This page” and “All pages”.

• –

  “Resolved” also lists the resolved ones, struck through.

• –

  Click a comment to open it. If it’s on another page, the canvas goes there.

The open comment fills the right panel: its text, its attachments, and its element with file:line, which opens the code.

Comments aren’t part of the undo history: ⌘Z doesn’t bring a deleted comment back.

Hand comments to an agent

There are three ways, depending on where your agent is.

In midcode’s agent panel. In the chat, type @ in the prompt (or use the +) and pick “Open comments”. In the terminal view, click “Send the open comments to the agent”. Either adds every open comment as one line each, element first, and tells the agent where the full list is:

Address these comments on the site (they're in .midcode/comments.json, with the element each one points at):
- src/components/Pricing.tsx:42:9: This heading wraps badly on phones. Two lines at most.
- src/components/Hero.tsx:18:11: Use the new product shot here.

See Your agent in midcode.

Anywhere else, by pasting. The “Copy open comments for your agent” button at the top of the list puts a Markdown brief of the open comments it lists (this page’s, or every page’s) on the clipboard. “Copy for your agent” on one comment copies that comment’s part of it, from its ### heading down.

# 1 comment on acme-site

Left in midcode on the live preview. Paths are relative to the project root (`/Users/ana/code/acme-site`); attachments are files in the repo.

## /pricing

### 1. /pricing · Phone 390px · open

- **Element:** `<h2>` · "Simple pricing for teams of every size"
- **Written at:** `src/components/Pricing.tsx:42:9`
- **Inside:** `src/app/pricing/page.tsx:12:7`
- **Where on it:** 42% across, 50% down

> This heading wraps badly on phones. Two lines at most.

- 📎 Screenshot 2026-10-05.png (image/png, 184 KB) → `.midcode/attachments/ab12cd34-Screenshot-2026-10-05.png`

Without midcode at all. The comments are files in the repository. An agent working there can read .midcode/comments.json directly: tell it to, or let the midcode skill do it.

What midcode writes

Comments live in the project, in .midcode/:

.midcode/
  README.md
  comments.json
  attachments/
    ab12cd34-Screenshot-2026-10-05.png

comments.json is a list, in the order the comments were made. A comment’s number is its place in that list.

[
  {
    "id": "5e1f0c2a",
    "createdAt": 1791230400000,
    "resolvedAt": null,
    "page": "/pricing",
    "breakpoint": "phone",
    "viewportWidth": 390,
    "anchor": {
      "ref": {
        "mc": "src/components/Pricing.tsx:42:9",
        "mci": null,
        "i": 0,
        "sel": "body > main > section:nth-of-type(3) > div > h2",
        "mcu": null
      },
      "tag": "h2",
      "component": null,
      "text": "Simple pricing for teams of every size",
      "context": [
        "src/app/pricing/page.tsx:12:7"
      ],
      "fx": 0.42,
      "fy": 0.5
    },
    "body": "This heading wraps badly on phones. Two lines at most.",
    "attachments": [
      {
        "id": "ab12cd34",
        "name": "Screenshot 2026-10-05.png",
        "path": ".midcode/attachments/ab12cd34-Screenshot-2026-10-05.png",
        "type": "image/png",
        "size": 184213
      }
    ]
  }
]

Inside anchor:

README.md is a few lines that explain the folder to whoever opens it, agents included. midcode writes it when it isn’t there and never changes one that is.

In git

.midcode/ is ordinary files. Commit them and the comments travel with the repository: a teammate who opens the project in midcode sees the same pins. Or add .midcode/comments.json and .midcode/attachments/ to .gitignore to keep them to yourself. To git they are changed files like any other: when you publish, include them or leave them out.

What midcode adds to your project covers the rest of the folder.

Limits

• –

  anchor.ref.mc is the line the element was on when the comment was made. It isn’t updated when the code above it changes, so after edits the pin can point at a neighbour, or disappear until its line holds an element again. The comment’s tag and text say what it was about.

• –

  A comment has one text. There are no replies and no authors: the file doesn’t record who wrote what.

• –

  Pins show in the breakpoints’ frames, not on what floats on the free canvas.

• –

  A deleted comment is gone, with its attachments.