webkubor/vite-plugin-agent-eyes

Vite Agent Debugger

Give agents working in Vite projects runtime visibility to run a closed-loop self-healing cycle: "read logs → locate → modify → restart dev → re-read and verify." Comes with an npm package vite-plugin-agent-eyes (source code in this directory src/, can be npm published or installed via git). If you only need the agent operation flow, read AGENT_GUIDE.md first; to make Codex, Claude, Gemini, Hermes proactively discover and use it, read AGENT_BOOTSTRAP.md; README is for human installation and evaluation.

When to Use

• The user reports "page broken / cannot log in / request failed / cookie issue", but you should not rely on guessing code – read telemetry first.
• You made changes and need to verify: restart dev, trigger actions, read logs to confirm behavior is correct.
• When needing to restore a logged-in UI or browser context, first look at log/<port>/auth-state.json to confirm the current account profile, then look at log/<port>/interaction.log to restore recent interaction paths.
• When a user's commit is blocked by guard or requires preemptively avoiding obvious errors / legacy code signals, first read log/guard-report.json.
• To install this self-healing capability into a Vite project that hasn't been set up yet.

Integration (one-time, 1 step by default)

// vite.config.ts
import { agentEyes, agentProxy } from 'vite-plugin-agent-eyes'
export default defineConfig({
  plugins: [...agentEyes()],  // Default: logging + automatic client instrumentation + project health check + size watch + commit guard
  server: { proxy: { '/api': agentProxy('https://your-api.example.com') } },
})

agentEyes() only takes effect during vite dev and automatically injects autoInstrument() into the dev HTML; normal projects don't need to modify the app entry.

If automatic injection is disabled (agentEyes({ client: false })), you need to manually add it in the app entry:

import { autoInstrument } from 'vite-plugin-agent-eyes/client'
autoInstrument()

Or manual instrumentation (for fine-grained control):

import { installAgentErrorReporter, logApiCall, logConsoleEntry, snapshotDom } from 'vite-plugin-agent-eyes/client'
installAgentErrorReporter()   // Captures global errors + full console + DOM snapshots
// In fetch/ky/axios interceptors, call at end of each request
logApiCall({ method, path, url, ok, duration_ms, code, status, request_id, error, request, response })
logConsoleEntry('warn', ['deprecated API called'])

Record desensitized account profile after successful login:

import { recordLoginSuccess } from 'vite-plugin-agent-eyes/client'
recordLoginSuccess({ userId, email, name, roles, tenantId })

Only saves desensitized profile, not token/cookie. Can be read in browser as window.__AGENT_EYES_AUTH__, file at log/<port>/auth-state.json.

Interaction traces are installed by default via autoInstrument() and written to log/<port>/interaction.log. input / change only record <redacted>, not actual form values.

If the package is not installed but you want to use it temporarily: prefer installing via git or workspace methods; do not just copy src/index.ts / src/client.ts as they depend on the cdp, git, guard-* modules in the same directory.

Commit Governance: agentEyes / agentGit / agentGuard / agentSizeWatch (Configuration Quick Reference)

Responsibilities (hooks are installed/rewritten by the apply:'serve' plugin when dev starts – after changing configuration or upgrading version, you must run pnpm dev once for it to take effect; for Astro projects, add to the vite.plugins array in astro.config):

Plugin	Timing	Effect
agentEyes	dev start	Default combined entry: logging + automatic client instrumentation + project health check + size watch + guard-only git hook
agentGit	Before/after commit	Replace husky: run precommit commands + can embed guard; Feishu notification post-commit. Built-in deduplication for rebase/cherry-pick replays
agentGuard	At commit time	Hard block of staged content: secrets/oversized files/excessive line count/TODO/any/console.log. If using agentGit, configure guard inside agentGit({ guard }), do not mount separately (contention for pre-commit hook)
agentSizeWatch	During dev coding	Warns oversized files in console as [agent-eyes:size], warning only, no blocking. Specifically for AI-generated overly long CSS

Typical configuration (as used by this project's three repositories):

agentGit({
  projectLabel: 'Domestic Website',
  precommit: ['sh scripts/precommit.sh'],     // Any non-zero exit blocks
  webhook: [{ url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxxx', format: 'feishu' }],
  guard: { level: 'block', fileLength: { warn: 400, block: 800 } },  // Hard block legacy code
  claimHooksPath: true,   // When global core.hooksPath (e.g., lefthook) overshadows local hooks, set local override
  force: true,            // Take over existing non-plugin pre-commit hooks
})
// Dev-time real-time warning (optional, mount independently): agentSizeWatch({ warn: 400, cssWarn: 300 })

level: warn – report only / block (recommended) – red line block / strict – currently same as block. guard.checks: ['secrets','largeFiles','fileLength','todo','noAny','noConsoleLog'], can be toggled as needed.

Two behaviors in 0.12.0 that must be known before configuring guard (otherwise they might appear as bugs):

• lockfile/compressed artifacts are not counted for fileLength: pnpm-lock.yaml/package-lock.json/yarn.lock/*.lock/go.sum/.min.js|css are automatically skipped – these are generated artifacts, not hand-written code. To extend the list, modify GENERATED_FILE_PATTERN (two copies: guard-core and guard-hook must be synced).

• webhook does not self-trigger: agentGit automatically injects its own configured webhook URL into guard allowSecrets, so secret checking no longer flags it as a leak. To manually allow other literals, use guard.allowSecrets: [...].

• guard only checks staged files; the latest JSON report is at log/guard-report.json.

• See README ### agentGit / agentGuard / agentSizeWatch API section for complete options.

Self-Healing Loop (Core, Follow This)

1. First read log/README.md – project self-description, confirm current port log location and what each stream shows.
2. Read log/project-guide.json – check project type, API/business/routing/config hierarchy and @ alias suggestions.
3. Read log/<port>/errors.log – locate "what broke" (latest at top, head suffices).
4. Drill down based on clues:
   • Unclear reproduction path → log/<port>/interaction.log for click/input/change/submit/route sequence.
   • API/field issues → log/<port>/api-calls.log to see actual request/response bodies (never guess fields based on types).
   • Console warnings/debug info → log/<port>/console.log for all-level output (React dev warnings, library deprecation, etc.).
   • Login/cookie/CORS/302 network layer → log/<port>/proxy-<host>.log for Cookie(req) and Set-Cookie.
   • Logged-in UI restoration → log/<port>/auth-state.json for current account profile.
   • Visual issues → log/<port>/snapshots/ for error screenshots (PNG) + DOM snapshots (HTML).
   • Pre-commit guard issues → log/guard-report.json for block/warning details.
5. Noise prediction: Unauthenticated /auth/session 401s, browser extension runtime.lastError are expected noise, not bugs – do not chase.
6. Modify code → restart dev (Vite config/plugin changes require a server restart, HMR is not sufficient) → re-trigger → re-read logs to verify. Logs are cleared on each start, so what you see is from this session.

Signature Diagnosis: Successful Login But Persistent 401

log/<port>/api-calls.log:  POST .../auth/login  code=0        ← Login success
log/<port>/api-calls.log:  GET  .../auth/session code=40101    ← Immediately after, not logged in
log/<port>/proxy-<host>.log: GET .../auth/session → 200 | Cookie(req): none   ← Browser did not send cookie

Root cause: Upstream Set-Cookie has Domain=<parent domain> + Secure + SameSite=None, local http://localhost domain mismatch + Secure dropped → rejected. agentProxy already fixes this in dev by default (removes Domain / strips Secure / changes SameSite=None→Lax). To disable: agentProxy(target, { rewriteCookiesForLocalhost: false }).

Log Quick Reference

File	What to Look At
log/<port>/errors.log	API failures + frontend runtime errors (aggregated dedup + frequency)
log/<port>/console.log	All-level console output (log/warn/error/info/debug)
log/<port>/interaction.log	Desensitized interaction trace of click/input/change/submit/route
log/<port>/api-calls.log	All API + route calls with request/response bodies
log/<port>/proxy-<host>.log	Proxy-level Cookie / Set-Cookie attributes / status (per host if multiple proxies)
log/<port>/auth-state.json	Most recent successful login desensitized account profile
log/<port>/snapshots/err-*.png	Error screenshots (requires CDP, auto-detects port)
log/<port>/snapshots/dom-*.html	DOM snapshots (always available, no CDP needed)
log/project-guide.json	Project type, API/business/routing/config hierarchy, alias and planning suggestions
log/guard-report.json	Most recent pre-commit guard JSON report