@macintacos/caret 0.1.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "caret",
+  "version": "0.1.1",
+  "description": "Review, annotate, and approve Claude Code plans in a local web UI.",
+  "author": { "name": "macintacos" },
+  "homepage": "https://github.com/macintacos/caret",
+  "repository": "https://github.com/macintacos/caret",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "plan-review",
+    "code-review",
+    "hooks",
+    "approval",
+    "annotation"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julian Torres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# 🥕 caret
+
+> ⚠️ **Prototype.** caret is an early prototype and may change substantially over the next
+> little while — interfaces, hooks, storage, and the install flow are all still settling.
+> Expect rough edges and breaking changes.
+
+caret is a Claude Code (and OpenCode) 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](CONTRIBUTING.md).
+
+## Screenshots
+
+<!-- TODO(EXC-666): review-UI screenshots — plan view + inline annotation,
+request-changes flow, multi-session switcher. -->
+
+_Review-UI screenshots coming soon._
+
+## Install
+
+caret needs [`bun`](https://bun.sh) on your `PATH` — it runs from a `bun` bundle — plus
+the [`claude`](https://claude.com/claude-code) CLI you already have.
+
+### Claude Code
+
+caret installs from its GitHub-based plugin marketplace. From inside Claude Code:
+
+```sh
+/plugin marketplace add macintacos/caret
+/plugin install caret@caret
+```
+
+This fetches the published plugin — a self-contained `bun` bundle plus the prebuilt UI —
+into Claude Code's plugin cache. No `git clone`, no compile step, no
+`claude --plugin-dir`. Then restart Claude Code (or run `/reload-plugins`) and try it:
+
+```sh
+/caret:demo    # presents a short fake plan to exercise the flow
+```
+
+**Update** with `/plugin marketplace update caret` (then `/reload-plugins`). **Uninstall**
+with:
+
+```sh
+claude plugin uninstall caret@caret
+claude plugin marketplace remove caret
+```
+
+### OpenCode
+
+caret also installs into [OpenCode](https://opencode.ai), as an auto-loaded plugin. The
+script installer detects OpenCode (and, if you also have Claude Code, asks which to
+install into — or set `CARET_AGENTS`):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/macintacos/caret/trunk/scripts/install.sh \
+  | CARET_AGENTS=opencode bash
+```
+
+The installer drops a `caret.ts` plugin plus the `/caret:demo`, `/caret:discovery`, and
+`/caret:debug` commands into your OpenCode config dir, along with a `package.json` for its
+one dependency (`@opencode-ai/plugin`) — it never touches your existing `plugin` config
+array. **Restart OpenCode once** after installing (plugins load at startup), then
+`/caret:demo` works. Approving or requesting changes flows back exactly as in Claude Code.
+**Update** by re-running the installer; **uninstall** with
+`caret install-opencode --uninstall` (which also removes that `package.json` entry). See
+[`doc/ADVANCED.md`](doc/ADVANCED.md#the-opencode-adapter) for how the integration works.
+
+## Using caret
+
+Whenever your agent presents a plan — Claude Code's `ExitPlanMode`, or the Plan agent in
+OpenCode — caret intercepts it and opens it 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.
+
+A single local daemon serves every session, so concurrent plans queue up in one tab behind
+a switcher.
+
+## Configuration
+
+caret runs with sensible defaults and needs no configuration. To tune it, it reads an
+optional `config.toml` and `CARET_*` environment variables (for example the daemon port or
+the review timeout); logs are written raw by default. The full list of keys, their
+defaults, and the environment variables is in
+[`doc/ADVANCED.md`](doc/ADVANCED.md#configuration).
+
+## Reporting bugs
+
+- `caret discovery` prints a one-shot, read-only diagnostics snapshot of your install —
+  ready to paste into a bug report (`caret discovery --json` for machine-readable output).
+- `/caret:debug` reviews the current session's plans and recent errors.
+
+Details, plus how to scrub logs with `caret redact`, are in
+[`doc/ADVANCED.md`](doc/ADVANCED.md#logging--debugging).
+
+## Platform support
+
+caret is **macOS-first**; Linux and Windows are best-effort. See
+[`doc/ADVANCED.md`](doc/ADVANCED.md#platform-support) for the details.
+
+## Documentation
+
+- [`doc/ADVANCED.md`](doc/ADVANCED.md) — the deep reference: build-from-source,
+  architecture, the agent adapters, the full configuration surface, and the development
+  workflow.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — develop caret locally: setup, the `mise` workflow,
+  and where tests live.
+- [`doc/`](doc/) — contributor rules-of-the-road, routed from [CLAUDE.md](CLAUDE.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Vendored third-party assets (the Lucide icons) are itemized
+in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) (ISC).

package/bin/caret

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+#
+# caret plugin entrypoint shim (EXC-643). This is the ONE file Claude Code's
+# hooks invoke — `${CLAUDE_PLUGIN_ROOT}/bin/caret <subcommand>` (see
+# hooks/hooks.json and commands/discovery.md). It is committed and shipped in
+# every install; it resolves the actual caret runtime from whatever the install
+# method placed beside it:
+#
+#   1. a compiled binary (bin/caret-native) — the build-from-source paths
+#      (`scripts/install.sh`, `mise run build --install`) compile this; running
+#      it needs no `bun` at hook time.
+#   2. the run-from-source bundle (dist/cli.js) — the GitHub/npm plugin install
+#      ships this plus a sibling ui/dist; it runs on `bun`. REQUIRES `bun` on
+#      PATH (documented in the README).
+#   3. raw source (src/cli.ts) — a dev checkout that built neither artifact.
+#
+# Resolution is by the shim's own on-disk location (resolved through symlinks,
+# since Claude Code's plugin cache may symlink), never the cwd.
+
+set -euo pipefail
+
+# Resolve this script's real directory, following symlinks.
+source="${BASH_SOURCE[0]}"
+while [ -h "$source" ]; do
+  dir="$(cd -P "$(dirname "$source")" >/dev/null 2>&1 && pwd)"
+  source="$(readlink "$source")"
+  case "$source" in
+  /*) ;;
+  *) source="$dir/$source" ;;
+  esac
+done
+root="$(cd -P "$(dirname "$source")/.." >/dev/null 2>&1 && pwd)"
+
+# 1. Compiled binary, if a build-from-source install produced one.
+if [ -x "$root/bin/caret-native" ]; then
+  exec "$root/bin/caret-native" "$@"
+fi
+
+# 2 & 3 both run through `bun`. Fail loudly with install guidance if it's absent,
+# rather than letting `exec bun` surface a bare "command not found".
+if ! command -v bun >/dev/null 2>&1; then
+  echo "caret: 'bun' is required to run caret from source but was not found on PATH." >&2
+  echo "       Install Bun (https://bun.sh) and retry." >&2
+  exit 127
+fi
+
+# 2. The shipped run-from-source bundle (npm/github plugin install).
+if [ -f "$root/dist/cli.js" ]; then
+  exec bun "$root/dist/cli.js" "$@"
+fi
+
+# 3. Raw source (dev checkout with neither artifact built).
+exec bun "$root/src/cli.ts" "$@"

package/commands/debug.md

@@ -0,0 +1,130 @@
+---
+description: Review the current caret session — pending/approved/rejected/expired plans plus recent errors — and help debug failures
+---
+
+caret persists every review and logs to its state dir. This command reviews the current
+session — the plans you've sent for review and their outcomes — and surfaces recent errors
+so a failure can be diagnosed. A failure usually first shows as a deny like "caret: … —
+denying so no unreviewed plan ships. See …/caret.log."
+
+## 1. Locate caret's state
+
+caret writes to its state dir — `$XDG_STATE_HOME/caret` when that variable is set,
+otherwise `~/.local/state/caret`:
+
+- `reviews/<id>.json` — one JSON review record per file, kept on disk as history after it
+  resolves. Each record carries `id`, `sessionId`, `cwd`, `title`, `status`
+  (`pending`/`rejected`/`approved`/`expired`), a `versions` array (plan revisions), and —
+  once resolved — a `decision` (`behavior`/`feedback`/`acceptMode`/`decidedAt`).
+- `caret.log` — NDJSON records from the short-lived `caret review` hook process, one JSON
+  object per line: `level` (pino numeric: 20 debug, 30 info, 40 warn, 50 error), `time`
+  (ISO 8601 UTC), `step`, `source` (the emitting process), `caller` (the emitting
+  `file:line`, when resolvable), `msg`, review-scoped extras
+  (`sessionId`/`cwd`/`reviewId`, plus `feedbackChars`/`acceptMode` on a decision record),
+  and — on errors — `err` with `message`, `stack`, and a nested `cause` chain. Feedback
+  and plan bodies are never logged — only counts like `feedbackChars` (EXC-444). Normal
+  operation (a review decision, a format reject) logs at info; only genuine failures sit
+  at level ≥ 50.
+- `daemon.log` — the detached daemon's stdout/stderr: the same NDJSON shape (tagged with
+  `pid`) for lifecycle and request errors, possibly interleaved with raw non-JSON lines
+  (crash traces, port messages).
+
+Lines that don't start with `{` (including pre-NDJSON sentinel records from older caret
+versions) are skipped by the `grep '^{'` filters below.
+
+Resolve the directory once:
+
+```bash
+dir="${XDG_STATE_HOME:-$HOME/.local/state}/caret"
+```
+
+## 2. Session review
+
+Reconstruct the current session's reviews. Identify the session by filtering reviews whose
+`cwd` matches the working directory and taking the `sessionId` of the most recently
+updated match, then list every review in that session, oldest first:
+
+```bash
+sid=$(jq -rs --arg cwd "$PWD" '[.[] | select(.cwd == $cwd)] | sort_by(.updatedAt) | last | .sessionId // empty' "$dir"/reviews/*.json)
+jq -s --arg sid "$sid" '[.[] | select(.sessionId == $sid)] | sort_by(.createdAt) | .[] | {id, title, status, versions: (.versions | length), decidedAt: .decision.decidedAt, feedback: .decision.feedback}' "$dir"/reviews/*.json
+```
+
+If `$dir/reviews` is missing or empty, the glob won't match and these commands error
+(shell or jq, depending on the shell) — treat that as "no reviews recorded", not as a
+failure.
+
+Present the result grouped by status:
+
+- **pending** — awaiting a decision in the browser.
+- **rejected** — changes requested; awaiting a revised plan. Include a short excerpt of
+  the decision `feedback`.
+- **approved** — plan accepted; terminal success.
+- **expired** — abandoned by its hook (timeout) or superseded by a resubmitted plan;
+  terminal, never reviewed (EXC-454).
+
+For each review show its id, title, and version count (`versions` above — the number of
+plan revisions). Note that the field whitelist above is deliberate: `versions[].plan` and
+`generalCommentDraft` hold full plan and draft bodies — never select or echo them.
+
+If no review matches the working directory (`sid` comes back empty), say so, then fall
+back to the most recently updated session across all reviews — recompute `sid` and re-run
+the listing command above with it:
+
+```bash
+sid=$(jq -rs 'sort_by(.updatedAt) | last | .sessionId // empty' "$dir"/reviews/*.json)
+```
+
+## 3. Recent errors
+
+- **caret.log** — extract the **last 5 error records** (level ≥ 50), then report each
+  one's step, msg, and `err` message/cause/stack:
+
+  ```bash
+  grep '^{' "$dir/caret.log" | jq -s '[.[] | select(.level >= 50)] | .[-5:]'
+  ```
+
+- **daemon.log** — same extraction for the daemon side, plus a raw tail for non-JSON crash
+  output near the time of the hook failure:
+
+  ```bash
+  grep '^{' "$dir/daemon.log" | jq -s '[.[] | select(.level >= 50)] | .[-5:]'
+  tail -n 40 "$dir/daemon.log"
+  ```
+
+  For a human-readable rendering of either log: `grep '^{' <log> | bunx pino-pretty`.
+
+  If `jq` isn't available, fall back to `grep '^{' <log> | tail -n 20` and read the raw
+  NDJSON directly — each line is a self-contained JSON record.
+
+A "socket connection closed" on the hook side often has its real cause on the daemon side,
+so check both. The surrounding info records (review created/resolved, plan rejected with
+its `feedbackChars`) give the timeline leading up to a failure:
+
+```bash
+grep '^{' "$dir/caret.log" | tail -n 10 | jq -c '{time, level, step, msg}'
+```
+
+## 4. Handle the empty case
+
+Two independent axes — report each on its own:
+
+- **No reviews for this project** — if the cwd matches no review and the fallback finds
+  nothing, state that plainly. Don't imply a failure occurred; an absence of reviews just
+  means none have been sent from here yet.
+- **No error records** — if neither log contains a record with `level >= 50`, report
+  **"caret has no errors recorded"**. Info records alone (rejected plans, routine
+  lifecycle) are normal operation, not errors. The session review still renders if reviews
+  exist.
+
+## 5. Debug
+
+If a failure is present (an error record at level ≥ 50) and the `/systematic-debugging`
+skill is available, invoke it to drive root-cause investigation from the logged error
+(it's the right tool for turning a stack trace into a confirmed root cause). Otherwise,
+reason from the failing step, msg, cause, and stack to the likely cause and propose a fix.
+
+If no failure is present, stop after the session review — there is nothing to debug.
+
+Keep your output diagnostic-focused — step, msg, cause, stack. The logs deliberately avoid
+full plan bodies, and review JSON contains them under `versions[].plan`; never fetch or
+echo plan content into this conversation.

package/commands/demo.md

@@ -0,0 +1,21 @@
+---
+description: Demo caret by presenting a short fake plan via ExitPlanMode
+---
+
+Read the shared fake-plan fixture at `${CLAUDE_PLUGIN_ROOT}/scripts/dev/fake-plan.md` and
+present its contents **verbatim** to the user by calling `ExitPlanMode` with that markdown
+as the `plan` argument. This is the same fixture `mise run dev` seeds, so the demo and the
+dev environment draw their plan from one source of truth. Do **not** do any real work,
+research, or file edits — this is only to exercise the review flow. If the fixture can't
+be read, fall back to inventing a short, plausible-but-fake plan (a Context section, an
+Approach section, and a couple of Steps).
+
+This triggers caret's `PermissionRequest`/`ExitPlanMode` hook, which opens the plan in a
+local browser UI for inline review. When the user approves or requests changes there, the
+decision flows back to you:
+
+- **Approved** → proceed (this is just a demo, so simply acknowledge that caret approved
+  the plan and stop).
+- **Changes requested** → the feedback arrives as the denial reason. Revise the plan
+  accordingly and present it again via `ExitPlanMode` (caret captures it as a new
+  version).

package/commands/discovery.md

@@ -0,0 +1,35 @@
+---
+description: Gather a redacted diagnostics snapshot of this caret install and present it ready to paste into a bug report
+---
+
+caret's `discovery` subcommand prints a one-shot, read-only snapshot of the local install
+— running caret processes, daemon identity, lock/port state, effective settings, review
+counts, the agent adapter's install-state probe (plugin version, enabled state, and
+whether a manual hook sits in the agent's user settings), log sizes and error counts,
+install/runtime info, and system basics. The report is **always redacted** (home paths
+become `~`, usernames in foreign home paths are censored) and never contains plan, prompt,
+or feedback bodies, nor any log contents — it exists to be shared.
+
+First ask the user (via `AskUserQuestion`) which format they want:
+
+- **JSON** — for pasting into a bug report or feeding to tooling.
+- **Human-readable** — for scanning in the conversation.
+
+Then run the matching invocation:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/bin/caret" discovery --json   # JSON
+"${CLAUDE_PLUGIN_ROOT}/bin/caret" discovery          # human-readable
+```
+
+End your output with the command's stdout **verbatim** in a fenced code block — ` ```json
+` for the JSON format, plain ` ``` ` for the human-readable one — so the user can copy it
+straight into a bug report. Add nothing inside the block and do not summarize away
+sections; the report is already redacted and complete. A degraded section (e.g.
+`daemon error: …` or `"error": "…"`) is normal when the daemon is down — present it as-is
+rather than treating it as a failure of this command.
+
+If the command exits non-zero, no report could be produced at all: present the exit code
+and stderr instead, and suggest `/caret:debug` for log-side diagnosis. If the binary
+itself is missing (a source checkout that has never been built), say so and point at
+`scripts/install.sh` or `mise run build`.