vite-plugin-agent-eyes skill
A Vite plugin with a skill that writes errors, requests and page snapshots to logs an agent reads to find the cause of a bug
- 105 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Writes request logs with Cookie headers and an anonymized account profile to disk and takes screenshots of the page
- Installs Git hooks that block a commit and can run your commands before it
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/vite-plugin-agent-eyesDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Writes request logs with Cookie headers and an anonymized account profile to disk and takes screenshots of the page
- Installs Git hooks that block a commit and can run your commands before it
This is third-party code. Review the repository files before installing.
What it does
The plugin works only in `vite dev` mode. It injects client code into the page that writes structured logs to the `log/<port>/` folder: errors, the console, API calls with response bodies, the user's path through the interface and an anonymized account profile that the application passes with `recordLoginSuccess`. Values from input fields do not reach the log, a `<redacted>` mark goes there. An agent reads these files and sees how the application really behaves without guessing from the code. If the browser is open for CDP debugging, the plugin takes screenshots tagged with project, route and time. Besides the logs, the plugin shows an Agent Eyes panel on the page and prints a summary at startup: environment, proxy targets, aliases and stack. The `agentProxy()` wrapper records the Cookie and Set-Cookie headers and fixes the Domain, Secure and SameSite attributes in a local HTTP environment. The second block is about commits: `agentGit` replaces husky, `agentGuard` blocks secrets, overlong files and diverging env files, and `agentSizeWatch` warns about bloated files during development.
Who it is for. For Vite frontend developers who fix and extend an interface together with an agent and are tired of retelling what happened in the browser.
Good fit when
- Login passes but the next request returns 401, and you need to see the real chain of Cookie headers.
- An agent fixed a component and checks the result itself: it restarts the dev server, repeats the action and reads `errors.log`.
- A bug is reproduced with clicks, and the sequence of actions comes from `interaction.log`.
- Secrets, file size and divergence of `.env.production` from `.env.test` are checked before a commit.
- You need to check whether `robots.txt`, `sitemap.xml` and `llms.txt` are in place in the project.
Not a fit when
- You need monitoring of a live site: logs, the panel and screenshots work only in `vite dev`.
- The project is not built on Vite: versions 4 to 9 are supported, other bundlers are not.
- The team forbids writing Cookie headers and profile data to disk, even to the local `log/` folder.
Example request
Add vite-plugin-agent-eyes to the project, reproduce the login failure and use the logs in `log/` to find why a 401 comes after loginLimitations
It works only during `vite dev` and supports Vite 4 to 9 (version 9 is not yet in the CI matrix). Screenshots are taken only if the browser is open for CDP debugging and exactly one page matches the project and route. The presence of `robots.txt` or `sitemap.xml` in the panel does not mean the site is already indexed. Logs with Cookie headers and the account profile live in the project's `log/` folder, which is worth adding to `.gitignore`. Git hooks are refreshed on `pnpm dev` after a config or version change. The documentation and some messages are in Chinese, and an English README exists. Licensed under MIT.
How to disable. Remove `...agentEyes()` from `plugins` in the Vite config and delete the package with `pnpm remove vite-plugin-agent-eyes`. Individual features are turned off with options: for example, `agentEyes({ client: false })` disables the automatic client code injection.
FAQ
How do I add vite-plugin-agent-eyes?
With `pnpm add -D vite-plugin-agent-eyes` and the line `plugins: [...agentEyes()]` in `vite.config.ts`. After `vite dev` starts, the terminal shows a project summary and the page shows the Agent Eyes panel.
What goes into the logs?
Errors, console output, API calls with real responses, the user's path through the interface and an anonymized account profile. Tokens and input values are not stored, and a `<redacted>` mark goes to the log.
Does the plugin work in a production build?
No. Logs, the panel and screenshots work only in `vite dev`, and the plugin adds nothing to a server build.
Do I need Chrome with debugging?
Only for screenshots: the browser must be open for CDP debugging. The other features work without it.
How does it replace husky?
The `agentGit` plugin installs pre-commit and post-commit hooks, runs your commands before a commit and can embed the `agentGuard` checks. Any command with a non-zero exit code blocks the commit.
Discussion
No questions or reviews yet.
Related
SkillsA skill for the Vite SVG sprite plugin: setup, configuration, Vue and React components, SSR and migration from the old plugin.
A CLI that sets up a canvas where an AI agent builds dashboards and reports as React artifacts, revised block by block
A Vite plugin with an MCP server that shows the agent the components, routes and Pinia stores of a running Vue app
SpotPatch links a click on a page element to the exact JSX location and hands the editor or agent structured context.
A skill that points the agent to ready VueUse composables for Vue 3 and Nuxt, with a usage and type reference for each function
56 JavaScript snippets for web performance: the agent runs them through skills, MCP or CLI and reasons over the result
README in short
The project presents itself as eyes for an agent on a running site: errors, interface, routes and screenshots become readable hints, and the same data is shown to a human in a browser panel. A comparison table lists what an agent had to do by hand before and what it sees now, and separate sections cover the 401 case and checking design token colors in commits.
README badge
Original SKILL.md
---
name: agent-eyes
description: "vite-plugin-agent-eyes 的 agent 使用手册。两块能力：① 自愈遥测——读结构化运行时日志（API/错误/控制台/交互/代理 header）+ 脱敏登录态 + 截图 + DOM 快照，不靠猜代码就诊断修复；② 提交治理——agentGit（去 husky，统一 pre-commit/post-commit + 飞书通知）、agentGuard（提交期硬拦 secret/超长文件/屎山）、agentSizeWatch（dev 期实时警告超长文件）。在 Vite/Astro 项目里配置 agentGit/agentGuard/agentSizeWatch 或排查 guard 拦截/误报时必读。"
version: 0.18.0
---
# Vite Agent Debugger
让在 Vite 项目里干活的 agent 拥有**运行时视野**，跑「读日志 → 定位 → 改 → 重启 dev → 再读验证」的自愈闭环。
配套 npm 包 `vite-plugin-agent-eyes`（源码在本目录 `src/`，可 `npm publish` 或 git 安装）。
如果只需要 agent 操作流程，优先读 `AGENT_GUIDE.md`；如果要让 Codex、Claude、Gemini、Hermes 主动发现并使用，读 `AGENT_BOOTSTRAP.md`；README 面向人类安装和评估。
**在线指南**（按问题查，含 401 案例、截图快照、交互轨迹、登录态画像等）：
https://webkubor.github.io/vite-plugin-agent-eyes/
## 何时用
- 用户报"页面坏了 / 登录不上 / 请求失败 / cookie 问题"，但你**不该靠猜代码**——先读遥测。
- 你自己改完要**验证**：重启 dev、触发操作、读日志确认行为对了。
- 需要还原已登录 UI 或浏览器控制时，先看 `log/<port>/auth-state.json` 确认当前账号画像，再看 `log/<port>/interaction.log` 还原最近交互路径。
- 用户提交被 guard 阻断或要求提前规避明显错误 / 屎山信号时，先读 `log/guard-report.json`。
- 给一个还没接入的 Vite 项目装上这套自愈能力。
## 接入（一次性，默认 1 步）
```ts
// vite.config.ts
import { agentEyes, agentProxy } from 'vite-plugin-agent-eyes'
export default defineConfig({
plugins: [...agentEyes()], // 默认：日志 + 自动客户端埋点 + 项目体检 + size watch + 提交 guard
server: { proxy: { '/api': agentProxy('https://your-api.example.com') } },
})
```
`agentEyes()` 只在 `vite dev` 生效，并会自动向 dev HTML 注入 `autoInstrument()`；普通项目不用再改应用入口。
**如果关闭了自动注入**（`agentEyes({ client: false })`），才需要在应用入口手动加：
```ts
import { autoInstrument } from 'vite-plugin-agent-eyes/client'
autoInstrument()