{"id":30205357,"url":"https://github.com/instructa/browser-echo","last_synced_at":"2025-08-23T09:07:50.755Z","repository":{"id":309385876,"uuid":"1036087892","full_name":"instructa/browser-echo","owner":"instructa","description":"⚡ Stream browser logs to terminal, zero setup, perfect for Ai Agents","archived":false,"fork":false,"pushed_at":"2025-08-18T18:41:03.000Z","size":1210,"stargazers_count":202,"open_issues_count":2,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-18T20:39:04.227Z","etag":null,"topics":["ai","browser","claude-code","codex-cli","cursor","gemini-cli","llm","log","logging"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/instructa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-11T14:38:24.000Z","updated_at":"2025-08-18T15:49:43.000Z","dependencies_parsed_at":"2025-08-11T19:15:10.295Z","dependency_job_id":null,"html_url":"https://github.com/instructa/browser-echo","commit_stats":null,"previous_names":["regenrek/vite-browser-logs","instructa/browser-echo"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/instructa/browser-echo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructa%2Fbrowser-echo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructa%2Fbrowser-echo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructa%2Fbrowser-echo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructa%2Fbrowser-echo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/instructa","download_url":"https://codeload.github.com/instructa/browser-echo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructa%2Fbrowser-echo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271746302,"owners_count":24813556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","browser","claude-code","codex-cli","cursor","gemini-cli","llm","log","logging"],"created_at":"2025-08-13T13:09:27.706Z","updated_at":"2025-08-23T09:07:50.723Z","avatar_url":"https://github.com/instructa.png","language":"TypeScript","readme":"# Browser Echo\n\n![Browser Echo](public/banner.png)\n\nStream browser `console.*` logs to your dev terminal and optional file logging.\n\n`browser-echo` makes it easy for you (and your AI coding assistant) to read client-side logs directly in the server terminal during development.\n\n## Features\n\n🤖 **AI Coding Assistant Support** - Perfect for Cursor AI, Claude Code, GitHub Copilot CLI, Gemini CLI, and other code editors that read terminal output\n\n🚀 **Framework Support** - React, Vue, Nuxt 3/4, Next.js, TanStack Start, Vite-based frameworks, and custom setups\n\nNo production impact. Providers enable this across frameworks by injecting a tiny client patch and exposing a dev-only HTTP endpoint.\n\n## Quick start\n\n#### 1. Install Framework Package\n\nFirst, set up Browser Echo for your framework:\n\n| Framework | Quick Setup |\n| --- | --- |\n| TanStack / Vite | [Installation Guide](packages/vite/README.md#tanstack-start) |\n| Nuxt 3/4 | [Installation Guide](packages/nuxt/README.md) |\n| Next.js (App Router) | [Installation Guide](packages/next/README.md) |\n| Vue + Vite | [Installation Guide](packages/vite/README.md#vue--vite) |\n| React + Vite | [Installation Guide](packages/vite/README.md#react--vite) |\n| Vue (non-Vite) | [Installation Guide](packages/vue/README.md) |\n| React (non-Vite) | [Installation Guide](packages/react/README.md) |\n| Core | [Installation Guide](packages/core/README.md) |\n\n\u003e Framework users only install their provider + `@browser-echo/core`. No cross‑framework bloat.\n\n#### 2. Use Browser Echo MCP (Optional)\n\n**⚠️ IMPORTANT:** You **must complete step 1** (framework setup) first before MCP will work. The MCP server needs your framework to forward browser logs to it.\n\n**📖 [Set up Browser Echo MCP Server](packages/mcp/README.md)** for AI assistant integration\n\n## What you get\n\n- Drop‑in client patch that wraps `console.log/info/warn/error/debug`\n- Batched posts (uses `sendBeacon` when possible)\n- Source hints `(file:line:col)` + stack traces\n- Colorized terminal output\n- Optional file logging (Vite provider only)\n- Works great with AI assistants reading your terminal\n- **NEW:** MCP (Model Context Protocol) support for enhanced AI assistant integration\n\n## Browser Echo MCP Server\n\nBrowser Echo includes built-in MCP (Model Context Protocol) server support, enabling AI assistants like Claude (via Cursor) to interact with your frontend logs using natural language commands:\n\n- **\"Check frontend logs\"** - Retrieves recent console logs\n- **\"Show only errors from the last 2 minutes\"** - Filters by level and time\n- **\"Find hydration mismatch warnings\"** - Searches for specific content\n- **\"Clear logs and start fresh\"** - Clears the buffer for new captures\n- **\"Focus on my current tab's logs\"** - Filters by session\n\nThe MCP server exposes two main tools:\n- `get_logs` - Fetch logs with extensive filtering (level, session, time, content)\n- `clear_logs` - Clear logs with soft/hard modes and session-specific clearing\n\nThis integration makes debugging with AI assistants much more powerful - they can directly query and analyze your frontend logs without you having to copy/paste from the terminal.\n\n**📖 [Full MCP Setup Guide \u0026 Documentation](packages/mcp/README.md)**\n\n### MCP discovery and forwarding (Vite / Next / Nuxt)\n\n- By default, when an MCP server is detected, frameworks forward logs to MCP and **suppress local terminal output**. If MCP is not found, they log locally.\n- **Vite now auto‑discovers MCP** (no need to set `mcp.url`). It resolves in this order:\n  1. Explicit option/env: Vite plugin `mcp.url` or `BROWSER_ECHO_MCP_URL`\n  2. Discovery file written by the MCP server: `.browser-echo-mcp.json` (project root or OS tmp) containing `url` and `routeLogs`\n  3. Port scan of common local ports (127.0.0.1 / localhost)\n  4. Fallback to local terminal logging\n- **Terminal output control:**\n  - `BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Force suppress terminal output (even when no MCP)\n  - `BROWSER_ECHO_SUPPRESS_TERMINAL=0` — Force show terminal output (even when MCP forwarding)\n  - Framework-specific options available (see individual framework package READMEs)\n\n## Options\n\nMost providers accept these options (names may appear as plugin options or component props):\n\n```ts\ntype BrowserLogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\ninterface BrowserEchoOptions {\n  enabled?: boolean;                 // default: true (dev only)\n  route?: `/${string}`;              // default: '/api/client-logs' (Next), '/__client-logs' (others)\n  include?: BrowserLogLevel[];       // default: ['log','info','warn','error','debug']\n  preserveConsole?: boolean;         // default: true (also keep logging in the browser)\n  tag?: string;                      // default: '[browser]'\n  // stacks\n  stackMode?: 'none' | 'condensed' | 'full'; // default: 'full' (provider-specific; Vite supports all)\n  showSource?: boolean;              // default: true (when available)\n  // batching\n  batch?: { size?: number; interval?: number }; // default: 20 / 300ms\n  // server-side\n  truncate?: number;                 // default: 10_000 chars (Vite)\n  fileLog?: { enabled?: boolean; dir?: string }; // Vite-only\n}\n```\n\n\u003e Note: File logging and `truncate` are currently implemented in the Vite plugin’s dev server middleware. Nuxt/Next providers print to stdout by default (you can extend them if you need file output there).\n\n## Production\n\n* Providers apply only in development and inject nothing into your production client bundles.\n* If you also want to strip `console.*` in prod builds, use your bundler’s strip tools (e.g. Rollup plugin) separately.\n\n## Troubleshooting\n\n* No logs appear\n\n  * Vite: ensure plugin is added and either `index.html` exists or you import the virtual module manually.\n  * Nuxt: confirm the module is in `modules[]` and you’re in dev mode.\n* Next: make sure `app/api/client-logs/route.ts` is exported and `\u003cBrowserEchoScript /\u003e` is rendered in `\u003chead\u003e`.\n\n* Endpoint 404\n\n  * Using a custom `base` or proxy? Keep the route same‑origin and not behind auth.\n  * Nuxt sometimes proxies dev servers; our module registers a Nitro route directly.\n\n* Too noisy\n\n  * Limit to `['warn','error']` and use `stackMode: 'condensed'`.\n\n* Duplicate logs in browser\n\n  * Set `preserveConsole: false`.\n\n## License\n\nMIT\n\n\n## Links\n\n- X/Twitter: [@kregenrek](https://x.com/kregenrek)\n- Bluesky: [@kevinkern.dev](https://bsky.app/profile/kevinkern.dev)\n\n## Courses\n- Learn Cursor AI: [Ultimate Cursor Course](https://www.instructa.ai/en/cursor-ai)\n- Learn to build software with AI: [AI Builder Hub](https://www.instructa.ai)\n\n## See my other projects:\n\n* [codefetch](https://github.com/regenrek/codefetch) - Turn code into Markdown for LLMs with one simple terminal command\n* [instructa](https://github.com/orgs/instructa/repositories) - Instructa Projects\n","funding_links":[],"categories":["Integrations"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstructa%2Fbrowser-echo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finstructa%2Fbrowser-echo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstructa%2Fbrowser-echo/lists"}