🥕 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.
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. See the OpenCode adapter for the by-hand equivalents, for pinning a version in OpenCode's plugin array (plugin on v1, plugins on v2), and for what each agent's install touches; the Claude Code adapter covers the hooks caret registers there.

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 (optionally also switching the session into accept-edits or auto mode) 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 both agents — review_plan in Claude Code (from the plugin's MCP server) and caret_review_plan in OpenCode. The tool is for plans only; see doc/ARCHITECTURE.md.

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.
• CLAUDE.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.