🥕 caret

caret is a plugin that replaces the terminal plan-approval prompt with a local web UI. When your agent presents a plan, caret opens it in your browser so you can read it as rendered HTML, annotate passages inline (Google-Docs style), and approve or request changes. Your feedback flows straight back to the agent. A single local daemon is shared across concurrent sessions, so several in-flight plans can be reviewed from one browser tab via a switcher.

Want to develop caret rather than use it? Start with CONTRIBUTING.md.

Screenshots

Check out a short demo here!

Install

bunx --no-cache @macintacos/caret@latest install

Note

caret supports macOS and Linux, where the review UI can run as a long-lived login service. Windows is best-effort and runs caret on demand only. See doc/CONFIGURING.md for what differs on each platform and what to fall back on.

Assuming that you installed it as a long-lived service (the default), you can navigate to http://caret.localhost:42718 to see the caret UI.

After installing:

1. Restart the agent. OpenCode installs the plugin package on its next start; in pi, run /reload or restart it.
2. Run /caret:demo. It presents a short demo plan that points at files in the repo you run it from, so you can exercise the whole flow before a real one arrives.
3. Run /caret:plan <what you want done> to plan a real change and review it in caret before the agent implements it.

Running caret yourself

If you'd rather caret not start at login, answer I'll run it myself when caret install asks. That removes the service if one is registered. Then, whenever you want the review UI up, run:

bunx @macintacos/caret@latest serve

This will keep the UI up at http://caret.localhost:42718 until the process is terminated.

Updating and uninstalling

Both are the install command with one flag:

bunx --no-cache @macintacos/caret@latest install --refresh    # update
bunx --no-cache @macintacos/caret@latest install --uninstall  # remove

--refresh restarts the caret service on the newest caret installed, never older than the one you ran; caret keeps a copy of it under ~/.local/state/caret/roots/.

caret's UI is designed to check for updates, at most once a day. When a newer caret is out, the review UI says so once: a toast on load that opens What's new (the skipped release notes or trunk commits), a mark on the settings button, and a Settings → Updates pane naming the version and the exact command to take it.

Turn the check off from that same pane, or by hand in config.toml:

[updates]
check = false

caret supports OpenCode v1 1.3.4 or later and v2 2.0.29 or later; an older v2 still loads caret but can't review a plan file the agent wrote, so the agent sends the plan text instead. See the OpenCode adapter for the by-hand equivalents, for pinning a version in OpenCode's plugin array (plugin on v1, plugins on v2); caret install covers what each agent's install touches; the Claude Code adapter covers the hooks caret registers there. caret install also installs into pi 1.5.0 or later when pi is on your PATH; run /reload in pi or restart it to pick caret up. caret install and caret doctor manage only pi's user-scope packages and ignore a project-scope install (pi install -l). OpenCode and pi both load caret from its npm package, which runs on bun, so bun must be on the PATH they run with. See the pi adapter for the by-hand equivalents.

Using caret

Whenever your agent presents a plan, caret should intercept it and opens the plan in your browser instead of the terminal prompt. There you:

• Read the plan as rendered HTML.
• Annotate — select any passage to attach an inline comment.
• Decide — Approve — with any comments you've left, applied without another planning round (optionally also switching the session into accept-edits or auto mode, or, on OpenCode v2 from the plan agent, to the build agent) or Request changes, which sends your comments back to the agent to revise and re-present.

Tip

You don't have to wait to be intercepted: /caret:plan <what you want done> asks the agent for a plan and routes it straight to the review UI. In OpenCode it runs on the plan agent, so switch to build to implement once you approve. A skill of your own can do the same with the plan-review tool caret gives each agent — review_plan in Claude Code (from the plugin's MCP server) and caret_review_plan in OpenCode and pi. The tool is for plans only; see doc/ARCHITECTURE.md. In OpenCode v2, /caret or <leader>p (ctrl+x p by default) opens the plan waiting in the session; rebind the key as caret.open under OpenCode's keybinds.

Using caret in pi

pi has no plan mode of its own, so caret brings a small one:

1. /caret:plan <what you want done> turns on planning mode. The agent researches, writes its plan into pi's plans folder (~/.pi/agent/plans by default), and sends it to caret. Until you approve, caret blocks the agent's edit and write tools outside that folder; shell commands are only discouraged. While planning, /caret:plan with no task turns planning off. Outside planning, a bare /caret:plan plans what you asked for earlier in the session.
2. While a review waits, a notice sits above the editor and the footer reads ^ plan waiting. /caret or ctrl+alt+o opens the plan in your browser. In Terminal.app or iTerm2, set Option to act as Meta (Esc+) for the shortcut to reach pi.
3. Approve, and the agent implements. Request changes, and it revises and resubmits. Esc in pi cancels a waiting review, and the agent is told not to implement the plan.

/caret:demo presents a demo plan, and /caret:doctor runs caret doctor and shows its report in the session (see Diagnostics).

Configuration

caret runs with sensible defaults and needs no configuration. To tune it — the daemon port, the review timeout, the log level — it reads an optional config.toml and CARET_* environment variables. Every key, every variable, and their defaults are in doc/CONFIGURING.md. To open the review UI from another device, such as a phone or a laptop, see Reaching caret from another device. Only the machine that serves the review UI runs caret as a service; the other devices need only a browser and the login link.

Documentation

doc/README.md maps the doc/ directory — start there and it routes you to the reference page that answers your question.

Two more live at the repo root:

• CONTRIBUTING.md — develop caret locally: setup, the mise workflow, and where tests live.
• AGENTS.md — for coding agents: routes a change to the rules-of-the-road that govern it.

Diagnostics

• /caret:doctor runs caret doctor: a one-shot, read-only check of your install — what's wrong, how to fix it, and the state it read that from. Always redacted, and it never contains plan, prompt, or feedback bodies, nor any log message, error or stack text.
• caret doctor --bundle archives the raw logs and review records when a maintainer needs them. That archive is not redacted, so caret asks before writing it.

License

MIT — see LICENSE. Vendored third-party code and assets are itemized, with their licenses, in THIRD_PARTY_LICENSES.md.