dev3000

A debugging assistant that captures everything happening in your web app during development - server logs, browser events, network requests, and automatic screenshots - organized in a timeline that AI can understand.

Quick Start

pnpm install -g dev3000
dev3000

Then tell Claude: "fix my app"

Requirements

• Node.js >= v22.12.0 (required for Chrome DevTools Protocol support)

What It Does

dev3000 runs your development server and monitors it in a headless browser, capturing:

• Server logs and console output
• Browser console messages and errors
• Network requests and responses
• Automatic screenshots (navigation, errors, interactions)
• User interactions (clicks, form submissions)

Everything is saved to timestamped logs that AI assistants can read to understand what went wrong and suggest fixes.

View the timeline at http://localhost:3684/logs

How It Works

dev3000 provides an MCP server with debugging tools that Claude Code can use:

• fix_my_app - Analyzes logs, finds errors, suggests fixes
• execute_browser_action - Takes screenshots, clicks, navigates
• restart_dev_server - Restarts your server safely
• crawl_app - Discovers all routes in your app
• find_component_source - Maps DOM elements to source code

When you run dev3000 in a project with Next.js or if you have chrome-devtools MCP installed, it automatically integrates with those too.

Installation & Setup

Global Install (Recommended)

pnpm install -g dev3000
cd your-project
dev3000

Local Install

pnpm add -D dev3000
pnpm dev3000

Claude Code Setup

1. Start dev3000 in your project
2. Open Claude Code
3. Say "fix my app" or ask debugging questions

That's it. Claude automatically discovers the dev3000 MCP server and can read your logs.

Options

dev3000 --help

Key options:

• --port <number> - Development server port (default: 3000)
• --mcp-port <number> - MCP server port (default: 3684)
• --disable-mcp-configs <targets> - Skip auto-writing specific MCP config files (.mcp.json, .cursor/mcp.json, opencode.json). Use all to skip everything or set the DEV3000_DISABLE_MCP_CONFIGS env var for a default.
• --browser <path> - Use a different browser (see Browser Options below)
• --servers-only - Skip browser monitoring entirely
• --headless - Run browser in headless mode (for CI/CD)

AI Integration

dev3000 automatically integrates with:

• Claude Code - Works out of the box, no configuration needed
• chrome-devtools MCP - Advanced browser inspection when installed
• nextjs-dev MCP - Next.js-specific debugging when installed

The MCP server discovers available tools automatically and suggests them when relevant.

MCP Config Control

dev3000 writes MCP client config files (.mcp.json, .cursor/mcp.json, opencode.json) so Claude Code, Cursor, and OpenCode can connect instantly. If you don't want certain files touched, pass --disable-mcp-configs "claude cursor" (aliases: .mcp.json, .cursor/mcp.json, opencode.json, or all). You can also set a default via DEV3000_DISABLE_MCP_CONFIGS.

Prefer a persistent setting? Create ${XDG_CONFIG_HOME:-~/.config}/dev3000/config.json:

{
  "disableMcpConfigs": "all"
}

Any value in this file is treated like a default CLI flag (overridden by env vars or explicit flags).

Development Commands

# Run dev server locally
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

Browser Options

Chrome (Default)

By default, dev3000 launches Chrome for browser monitoring. Each project gets a dedicated Chrome profile that preserves login state, cookies, and local storage.

Arc Browser

If you use Arc instead of Chrome:

d3k --browser '/Applications/Arc.app/Contents/MacOS/Arc'

Other Chromium Browsers

Any Chromium-based browser works. Pass the full path to the executable:

# Brave
d3k --browser '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'

# Edge
d3k --browser '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'

# Chromium
d3k --browser '/Applications/Chromium.app/Contents/MacOS/Chromium'

Servers Only Mode

Skip browser monitoring entirely and just run the dev server + MCP server:

d3k --servers-only

Headless Mode

For CI/CD environments where no display is available:

d3k --headless

Logs

Logs are stored in:

• /var/log/dev3000/ (if writable)
• OS temp directory (fallback)

Each project gets its own log files, automatically rotated (keeps 10 most recent).

Frequently Asked Questions

Can I use this with Cursor, Windsurf, etc.?

Yes, but you'll need to manually configure the MCP server connection. See the MCP documentation for your AI assistant.

Does this work with non-Next.js projects?

Yes. dev3000 works with any web framework (React, Vue, Svelte, vanilla JS, Rails, Django, etc.). It just monitors your dev server and browser.

Can I use Arc or other browsers?

Yes! Use --browser '/path/to/browser' to specify any Chromium-based browser. See Browser Options for examples.

How do I stop dev3000?

Ctrl+C or Cmd+C stops both dev3000 and your development server.

Where are screenshots saved?

Screenshots are embedded in the log files and viewable in the web UI at http://localhost:3684/logs

Contributing

We welcome contributions! Please see our contributing guidelines.

License

MIT