hindwatch

The problem

A coding agent can't see Metro, logcat, simulator or iPhone logs on its own. It can run one command when it thinks to ask, and it gets raw text back.

Related MCP server: Engineering Operations MCP

What Hindwatch does

One background daemon per project keeps recording, so the agent can ask what happened before the crash and check that a fix worked. It is for React Native and Expo developers who use Claude Code, Cursor or Codex. React Native support comes from a plugin, so Flutter, KMP and other frameworks are possible through a plugin too.

• Records - logs from before the agent asked are already in the buffer.

• Groups - one call returns the first error, the events from every source that led up to it, and the resolved stack with a file:line snippet.

• Collapses - repeated lines fold into one template with a count. Known noise can be muted per project.

• Verifies - mark, wait-for and expect exit 0 or 1, so the agent can prove a fix worked.

• Redacts - always on. Every event is redacted before it reaches the buffer, a plugin, the CLI or MCP.

Quick Start

1. Install. Hindwatch needs Node 22 or newer. The npm package includes the React Native plugin.

npm install -g hindwatch      # or: pnpm add -g hindwatch / yarn global add hindwatch / bun add -g hindwatch
hindwatch --help

To run it once without installing, use npx hindwatch (or pnpm dlx hindwatch, bunx hindwatch).

git clone https://github.com/omer-ayhan/hindwatch.git
cd hindwatch
npm install
alias hindwatch="node $PWD/packages/hindwatch/dist/core/src/cli.js"
hindwatch --help

npm install also builds the CLI into packages/hindwatch/dist/core/src/cli.js. Put the alias in your shell profile to keep it.

2. Start your app, then the daemon. Run these in the folder of your app. Start the app (and its bundler, if it has one) first. With no config file, Hindwatch reads package.json. If it depends on expo or react-native, it records JS logs from Metro on port 8081.

hindwatch doctor          # check adb, Xcode tools and Metro; starts nothing
hindwatch start           # start the daemon

3. Mark the moment, then reproduce the bug.

hindwatch mark before-tap

4. Read the incident.

hindwatch incidents       # list incidents, then open one
hindwatch incident 1

5. Prove the fix.

hindwatch expect --absent TypeError --since before-tap   # after the fix: exit 1 if still there

6. Connect your agent. See Supported clients.

This session ran on the repo's crash fixture (fixtures/forced-crash.jsonl), output pasted as printed:

$ hindwatch mark after-crash --root fixtures/projects/demo
{"mark":{"name":"after-crash","id":304,"ts":1793274819738}}
$ hindwatch incidents --root fixtures/projects/demo
{"schemaVersion":1,"incidents":[{"id":1,"kind":"crash","title":"TypeError: Cannot read property 'name' of undefined","count":2,"source":"react-native","app":"com.hindwatch.fixture","firstTs":1700000115200,"lastTs":1700000115900,"stale":true}],"truncated":false,"omitted":0,"next":null,"lastId":1,"startedAt":1793274818508}
$ hindwatch expect --absent TypeError --since after-crash --root fixtures/projects/demo
{"ok":true,"expect":"absent","matched":0,"window":{"fromId":0,"toId":0},"schemaVersion":1,"order":"asc","events":[],"truncated":false,"omitted":0,"muted":0,"next":null,"lastId":304}

How it works

flowchart LR
  agent[Agent] --> cli[CLI / MCP] --> daemon
  subgraph core[Hindwatch core]
    daemon[Daemon: redact, buffer, patterns, incidents]
    logcat[Android logcat] --> daemon
    sim[iOS simulator] --> daemon
    iphone[iPhone] --> daemon
  end
  subgraph plugins[Plugins]
    rn["react-native<br>Metro/CDP JS logs, symbolication, crash detector"]
    flutter["Flutter<br>possible plugin"]
    kmp["KMP<br>possible plugin"]
  end
  rn --> daemon
  flutter -.-> daemon
  kmp -.-> daemon

The core is framework-agnostic: it records Android logcat, the iOS simulator and iPhones on its own, and raises incidents for Android Java and native crashes, Android ANRs, and iOS crash reports. React Native support comes from a plugin, @hindwatch/plugin-react-native, which adds Metro/CDP JS logs, symbolication and the crash detector. Flutter, KMP and other frameworks are possible through a plugin that adds a source, enricher or detector. Only the React Native plugin is built today. See docs/plugins.md.

Tools

Every CLI command prints JSON on stdout. Run hindwatch --help for the commands and hindwatch <command> -h for one command's options. The MCP tools serve the same daemon.

start (CLI only) starts the daemon and is safe to repeat. mcp serves the tools on stdio.

Supported clients

These use npx, so no global install is needed. From source, replace npx -y hindwatch with node /path/to/hindwatch/packages/hindwatch/dist/core/src/cli.js. Without --root, the server's working directory picks the project.

Put this in .mcp.json in the project folder:

{
  "mcpServers": {
    "hindwatch": {
      "command": "npx",
      "args": ["-y", "hindwatch", "mcp"]
    }
  }
}

Or run this in the project folder:

claude mcp add hindwatch -- npx -y hindwatch mcp

Put this in .cursor/mcp.json. --root pins the project, since Cursor's docs don't say which working directory the server gets. This follows Cursor's docs but has not yet been tried in a live Cursor launch:

{
  "mcpServers": {
    "hindwatch": {
      "command": "npx",
      "args": ["-y", "hindwatch", "mcp", "--root", "${workspaceFolder}"]
    }
  }
}

Run this in the project folder. This follows the Codex docs but has not yet been tried in a live Codex launch:

codex mcp add hindwatch -- npx -y hindwatch mcp

For longer agent playbooks (crash triage, fix verification), copy the opt-in skill in .claude/skills/hindwatch into your project.

Measure it

The wait_for, expect, mute, unmute and noise tools also return a short context: daemon status, open incidents and top patterns, so the agent needs fewer follow-up calls.

Measured on the fixture with scripts/u4-companion-prove.ts.

Docs

Add hindwatch.config.json to the project folder to record native logs too:

{
  "sources": {
    "android": { "package": "com.example.app" },
    "ios-sim": { "bundleId": "com.example.app", "minLevel": "info" },
    "ios": { "bundleId": "com.example.app", "minLevel": "info" }
  },
  "plugins": ["@hindwatch/plugin-react-native"],
  "plumbing": ["my-lib/"],
  "logTimeSpan": 1800000
}

A config file replaces zero-config, so list the react-native plugin to keep Metro's JS logs. Where Metro lets only one debugger hold an app, Hindwatch steps aside when React Native DevTools takes it, and status says so. Metro doesn't tell anyone when DevTools closes, so JS logs resume once the app's page leaves Metro or Metro stops; to resume sooner, close DevTools and stop the daemon. A daemon that starts while DevTools is open takes the app once; reconnect DevTools and Hindwatch steps aside again. ios-sim.minLevel and ios.minLevel default to info; set debug or verbose when a native bug needs it. Android has no ingest floor. logTimeSpan is how many milliseconds of timeline the daemon keeps (default 1800000, 30 minutes); only age evicts events, so a noisy app grows memory instead of shortening the span. plumbing adds stack-frame patterns (regex) for your own deps on top of the built-in RN/devtools list.

ios records an iPhone attached to the Mac by USB, as Console.app does: through usbmuxd to the device's log stream, signed in with the pairing the Mac made when the iPhone was trusted. It needs no root and no relaunch, and it follows the app across restarts and reinstalls. Crash reports come from the device through xcrun devicectl (Xcode 15 or newer). With more than one iPhone attached, set ios.device to the UDID that xcrun devicectl list devices shows. JS logs from an iPhone come through Metro, as from any device.

Redaction is always on and no config or plugin can turn it off. Every event is redacted before it reaches the buffer, a plugin, the CLI or MCP. It covers private keys, bearer and basic auth, JWTs, AWS keys, emails and key=value secrets, and masks sensitive attribute names such as password or token.

The project root is the nearest folder with hindwatch.config.json or package.json. Pass --root <dir> to pick another. start refuses a root with nothing to record, and never starts in your home folder or / alone.

doctor checks Node, the config, the runtime folder, adb, adb devices, xcrun simctl, xcrun devicectl, the iPhone and Metro. It never starts the adb server or a simulator.

The daemon stops itself after 30 minutes with no client attached and no command. Once stopped, it leaves only its log in ~/.hindwatch/run (at most 1 MB plus one older copy) and a .stderr file, emptied at each start. After a kill -9, the next command cleans up the rest.

• Plugins: write a source, enricher or detector.

• Security: known issues.

Contributing

The repo layout and dev commands are in AGENTS.md. CI runs these, so run them before a PR:

npm run typecheck
npm test
npm run smoke:pack

Commit messages follow Conventional Commits. Each merge to main that passes CI is released by semantic-release: fix: publishes a patch, feat: a minor and a ! or BREAKING CHANGE: footer a major, with the version tag and GitHub release notes written from those commits.

License

MIT, see LICENSE.