# Dejank

[![M8ven Score](https://m8ven.ai/badge/mcp/ranjithkumarseekolu-dejank-1bigrs)](https://m8ven.ai/mcp/ranjithkumarseekolu-dejank-1bigrs)

**Give your AI coding agent hands on a live React Native app.**

Dejank is an MCP server. Your agent can tap the UI, read the screen, pull native logs, capture React/JS profiles, and save evidence — so it can find bugs, verify fixes, and investigate performance without you switching to DevTools by hand.

You describe what's wrong in plain English. The agent uses Dejank to look at the running app and figure it out.

## What you need first

- A React Native or Expo app running in **debug** mode
- Metro already started (usually port `8081`)
- A simulator or device with the app open
- An AI tool that supports MCP (Cursor, Claude, VS Code, ChatGPT desktop, Windsurf, Antigravity, Gemini CLI, …)

Dejank doesn't start Metro or your app for you — it attaches to what's already running.

## Install

### 1. Add Dejank to your AI tool

From this repo:

```bash
pnpm mcp:install-global -- --npx
```

That writes a `dejank` MCP server into every client it finds on your machine:

| App | Config |
|---|---|
| Cursor | `~/.cursor/mcp.json` |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Code | `~/.claude.json` (if `claude` CLI is installed) |
| VS Code / VSCodium | `…/Code/User/mcp.json` (`servers` key) |
| ChatGPT desktop | `~/.codex/config.toml` + `…/ChatGPT/chatgpt_mcp_config.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Antigravity | `~/.gemini/antigravity/mcp_config.json` |
| Gemini CLI | `~/.gemini/settings.json` |
| GitHub Copilot (Agent Host) | `~/.copilot/mcp-config.json` |
| Warp | `~/.warp/.mcp.json` |
| Amazon Q / Kiro / LM Studio / Cline / Roo | when their config dirs already exist |

Equivalent Cursor / Claude config:

```json
{
  "mcpServers": {
    "dejank": {
      "command": "npx",
      "args": ["-y", "dejank"],
      "env": {
        "DEJANK_METRO_HOST": "localhost",
        "DEJANK_METRO_PORT": "8081"
      }
    }
  }
}
```

VS Code uses the same command, but the top-level key is `servers` (not `mcpServers`). ChatGPT desktop on macOS stores MCP in `~/.codex/config.toml` under `[mcp_servers.dejank]`.

Developing Dejank itself? Use the local build instead of npm:

```bash
pnpm mcp:install-global
```

Fully quit and reopen your AI tools so they reload MCP. In VS Code, use **Agent** mode in Copilot Chat.

### 2. Start your app

```bash
npx expo start
# open the app on a simulator or device
```

Metro should be running (usually on port `8081`) before you ask the agent anything.

## Try it

Just ask your agent, in plain English:

> Reproduce the bug when I tap **Submit** and tell me what failed.

> I fixed the null check — tap **Submit** again and confirm the error is gone.

> Why is the screen slow when I press **Load feed**?

> Show me the UI tree and a screenshot of the current screen.

> Pull the last minute of device logs after I tap **Retry**.

The agent picks the right Dejank tools for the job — no need to know their names.

## What it's good for

| Goal | Dejank gives the agent |
|---|---|
| **Fix a bug** | UI tree, tap, screenshot, native logs, component tree |
| **Verify a fix** | The same tap/screenshot/logs, repeatable before vs after |
| **Diagnose slowness** | One-shot JS + React profiling around a tap, via `investigate_slow_screen` |
| **Check UI state** | UI tree + screenshot |
| **Trace React renders** | Component tree and profiler data via Fusebox DevTools |
| **Catch runtime noise** | Android logcat / iOS Simulator logs |

Dejank collects evidence from the live app. Your agent — and you — decide the fix.

> Not built yet: dedicated JS console streaming, network inspection, memory/heap profiling. Native device logs often catch JS/runtime errors anyway, since most get printed there too.

## How it works

```
you ask to debug / verify / profile
            │
            ▼
   agent calls Dejank (MCP)
            │
            ▼
 Dejank attaches to Metro / the app
            │
            ▼
tap · screenshot · logs · JS/React profiles
            │
            ▼
   evidence returns to the agent
            │
            ▼
 agent explains it, and can patch your code
```

## Tools

| Tool | Use it for |
|---|---|
| `investigate_slow_screen` | Performance — one-shot JS + React profiling + diagnosis around an optional tap |
| `get_ui_tree` / `tap` | See on-screen controls; reproduce taps by label or coordinates |
| `take_screenshot` | Visual proof for bugs and UI checks |
| `get_device_logs` | Native logs (logcat / iOS Simulator) |
| `get_component_tree` | React component names via Fusebox DevTools |
| `capture_*` / `start_*` / `stop_*` profiles | Finer-grained JS or React profiling when you need more control |
| `list_targets` / `get_target_info` | Metro debug targets, useful if attaching fails |
| `list_artifacts` | Find recent evidence files |

For "is it slow?" questions, `investigate_slow_screen` alone is usually enough. For bugs and validation, the agent composes `tap` + `get_ui_tree` + `take_screenshot` + `get_device_logs`.

## Settings

| Env var | Meaning | Default |
|---|---|---|
| `DEJANK_METRO_HOST` | Where Metro runs | `localhost` |
| `DEJANK_METRO_PORT` | Metro port | `8081` |
| `DEJANK_ARTIFACT_DIR` | Where profiles and screenshots are saved | `.dejank/artifacts` |

## Developing Dejank itself

```bash
pnpm install
pnpm build
pnpm mcp:install-global   # local dist/ → Cursor / Claude (use -- --npx for npm)
pnpm mcp                  # run the server in the foreground
```

Contributor checks:

```bash
pnpm validate:m0   # basic attach / capability check
pnpm validate:m3   # injected slow-screen scenarios (sample app + simulator)
```

Historical product notes: [docs/SCOPE.md](docs/SCOPE.md).

## License

MIT