# RuntimeClue

Give your AI the clues to debug what’s running.

RuntimeClue lets MCP-compatible assistants inspect projects, processes, ports,
logs, HTTP endpoints, Git state, and development databases to diagnose what is
actually happening on your machine.

Ask directly in your terminal using your signed-in Codex or Claude Code CLI:

```sh
rclue "find me the process running on port 3000"
```

RuntimeClue connects the chosen AI CLI to its diagnostic tools and prints the
answer. You can also use the tools from Codex, Claude Desktop, and Cursor chats.

> “Why isn't localhost:8080 responding?”
>
> “Check why this endpoint returns 500.”
>
> “Which process is using port 3000?”

## Install

Requires **Node.js 22.16 or newer** (Node 24 recommended). No Docker, database CLI,
Git executable, or native build toolchain is required to run the packaged server.
Cloning the source requires Git; the setup command requires Node.js and npm.
For terminal questions, install and sign in to **Codex CLI** or **Claude Code CLI**
first. Claude Desktop is a separate app and cannot act as the terminal provider.
Setup checks the installed CLI's required flags, but does not make a paid model
request or verify your account quota. See the official
[Codex noninteractive guide](https://learn.chatgpt.com/docs/non-interactive-mode)
and [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference).

The source release is available on GitHub. Until the first npm publication, install
from a checkout:

```sh
git clone https://github.com/sargis-hakobyan/runtimeclue.git
cd runtimeclue
npm run setup
```

Setup asks for AI app integrations (Codex by default), the terminal provider, and
your application folder. For integrations, enter `codex,claude`, another
combination, `all` for all three supported clients, or `none` for terminal-only
use. Here `claude` means **Claude Desktop**; for the separate terminal provider
selection, `claude` means **Claude Code CLI**.

Setup installs dependencies, builds RuntimeClue, saves your terminal defaults,
adds `rclue` and `runtimeclue` launchers when possible, and registers/checks each
selected app integration. You do not need to find client folders. Start your app
and database normally; RuntimeClue does not start them for you. Restart selected
AI apps to use their MCP integration; terminal questions need no app restart.

Run `npm run setup` again to change the application or client. Setup uses safe
default permissions; use the install CLI below for custom policies. For a
noninteractive setup, pass the choices explicitly:

```sh
npm run setup -- --clients codex,claude --provider codex --root /absolute/path/to/your/project
```

For terminal-only use, pass `--clients none`. To keep the original MCP-only setup
without a terminal provider, pass `--no-terminal`. To save terminal defaults but
skip launcher installation, pass `--no-launchers`.

Replace `/absolute/path/to/your/project` with your application's source-code
folder, not the RuntimeClue checkout. Quote paths containing spaces. The application
folder is currently required for project configuration, Git, file logs, and
database connection discovery. Process and port inspection is not restricted to
that folder. Opening a different project in your AI client does not change the
registered folder; rerun setup to change it.

Repeat setup to add another AI tool; unselected tools are left unchanged. If one
client fails, setup continues with the others and reports which ones succeeded.

No `sudo`, administrator access, OS permission changes, or system configuration
changes are required. RuntimeClue uses your normal account, updates selected
AI tools' user-level configuration, and stores its own terminal settings. Launcher
installation uses an existing user-owned writable bin directory already on PATH
(such as an nvm Node bin directory, or a user-owned Homebrew bin directory that
exposes the active Node executable). It never edits shell startup files or changes
PATH, and refuses to overwrite unrelated commands. If no supported directory is
available, use `node dist/cli.js` from the checkout instead. Runtime information hidden by the OS
is omitted or reported as unavailable; RuntimeClue does not bypass restrictions.
Docker container discovery is not yet implemented.

Keep the RuntimeClue checkout in place: setup registers its compiled CLI using
the absolute path to your current Node executable. Your AI clients start the
server automatically; you do not need to run `serve` manually.

## Ask in the terminal

After setup, run from any directory while the installed launchers are on PATH:

```sh
rclue "find me the process running on port 3000"
rclue "list listening ports"
rclue "search my project log files for recent errors"
rclue --provider claude "discover my databases and list their tables"
rclue --allow-http "check http://localhost:3000/health"
```

Quote questions so your shell does not interpret punctuation, wildcards, or
variable expansions. Unquoted simple words also work. If your question starts
with a reserved command name such as `doctor`, use `rclue ask "..."`.

Change or inspect the saved provider:

```sh
rclue provider claude
rclue provider
```

`--provider codex|claude` overrides it for one question without changing the saved
default. `--root /path/to/app` overrides the application folder for one question;
otherwise the saved folder is used, **not** the current working directory.
`--model <name>` selects a model supported by the chosen CLI. There is no automatic
fallback to another provider. `rclue ask --help` lists all question options.

Each question starts a fresh AI CLI session using its existing sign-in. Questions
and diagnostic results are sent to that AI provider and use its normal account
allowance/billing; RuntimeClue does not request or store API keys. Terminal defaults
are saved in `~/.config/runtimeclue/terminal.json` (or under `XDG_CONFIG_HOME`);
`RUNTIMECLUE_CONFIG_DIR` explicitly overrides the settings directory.

Terminal sessions disable native shell/edit capabilities and unrelated user MCP
integrations, and run outside your project directory. Codex uses its read-only
sandbox. Claude Code has its built-in tools disabled and only RuntimeClue tools
allowlisted. Provider/admin policies still apply; RuntimeClue never bypasses them.
HTTP is disabled unless you pass `--allow-http`, which permits only localhost
`GET`, `HEAD`, and `OPTIONS` for that question. Database queries stay read-only.
Terminal sessions do not inherit custom MCP network or HTTP policies from app
registrations. Each question permits at most 24 diagnostic calls and defaults to
a 120-second deadline (`--deadline-ms`, up to 600000). Press Ctrl+C to cancel.

If launchers were not installed, the equivalent checkout command is:

```sh
node dist/cli.js "find me the process running on port 3000"
```

### Check or remove a checkout installation

Run these commands **from the RuntimeClue checkout**, after setup:

```sh
node dist/cli.js doctor
node dist/cli.js --help
```

To check just one client, use `node dist/cli.js doctor codex` (or `claude` or
`cursor`). A client reported as **not registered** is expected if you did not
select it during setup.

To disconnect one client, run:

```sh
node dist/cli.js uninstall codex
```

Installation backs up existing configuration, preserves other settings, validates
the change, and is safe to repeat. `uninstall` removes only the RuntimeClue
registration from the selected client and leaves a backup. Restart that client
after removal.

### Troubleshooting

- **`command not found: runtimeclue` or `rclue`:** check setup's launcher message.
  Earlier versions did not install commands, and `--no-terminal` or
  `--no-launchers` skips them. Run the updated setup with your original Node version
  active, or use `node dist/cli.js` from the checkout. An nvm-version-specific bin
  directory is only on PATH while that Node version is active. No `sudo` or shell
  configuration changes are needed for the checkout fallback.
- **Provider missing, too old, or not signed in:** terminal questions require the
  Codex or Claude Code CLI, not just a desktop app. Check `codex login status` or
  `claude auth status`; sign in with `codex login` or `claude auth login` if needed.
  Update an older CLI if setup reports missing isolation flags. Model access and
  quota errors come from the provider and are not fixed by changing OS permissions.
- **Doctor says “Registered command differs from the RuntimeClue installer
  output”:** its current check requires the exact Node executable and checkout
  path used during setup. Run Doctor from the original checkout with the same
  Node version active. With nvm, use `nvm use <version-used-for-setup>` first.
  If you intentionally moved the checkout or changed Node, rerun `npm run setup`
  to register the new paths, then restart your selected AI clients.
- **`dist/cli.js` is missing:** run `npm run setup` to install dependencies and
  build the checkout. After pulling source updates, rerun setup to rebuild and
  verify the integrations. This reapplies safe default policies; if you use
  custom policies, build with `npm ci` followed by `npm run build` and use the
  explicit install commands below to retain your chosen options.

### npm distribution (not yet published)

The planned npm package is `runtimeclue`, with `runtimeclue` and `rclue` executable
names. Registry-based installation is not available yet. Use the checkout setup
above; no global npm installation is needed. All commands below use the checkout.

## Seven tools

| Tool | What it tells the assistant |
| --- | --- |
| `inspect_project` | Languages, package scripts, expected ports, and masked database IDs |
| `list_processes` | Process IDs, executable names, memory, and CPU where available |
| `list_ports` | Listening TCP / bound UDP ports and visible owners |
| `read_logs` | Recent file logs, literal text search, and surrounding lines |
| `http_request` | HTTP status, duration, headers, and bounded response body |
| `git_status` | Branch, modified, added, deleted, untracked, and staged paths |
| `db_query` | Read-only PostgreSQL, MySQL, and SQLite queries |

The MCP server does not contain an LLM or call an AI API. It runs locally over MCP
stdio, where stdout is reserved for the protocol. Terminal question mode invokes
your chosen AI CLI, which reasons over the tools and contacts its AI provider.
In question mode, stdout contains the answer and stderr contains status/errors.

## Change the defaults

The following settings configure the **MCP app integrations**, not terminal
questions. Terminal mode deliberately uses the narrower policy described above.

Network access defaults to loopback. HTTP methods default to `GET`, `HEAD`, and
`OPTIONS`. Additional hosts, private networks, and methods are explicit options:

```sh
node dist/cli.js install codex --local --root /work/my-app --allow-host dev-db.internal
node dist/cli.js install codex --local --root /work/my-app --allow-private-network
node dist/cli.js install codex --local --root /work/my-app --http-methods GET,HEAD,OPTIONS,POST,PUT,PATCH,DELETE
```

You can combine these options. Re-running installation replaces the server's
policy with the specified settings; omitted options return to safe defaults.
Keep `--local` when reinstalling from a checkout. These examples update Codex
only; repeat with `claude` or `cursor` for other clients, then restart them.

Alternatively, start from [examples/policy.json](examples/policy.json):

```sh
node dist/cli.js install codex --local --config /absolute/path/to/policy.json
```

Policy files are loaded only when explicitly specified. CLI options override JSON
values. Relative root paths resolve against the shell's current directory. The
installer stores the resolved settings in the client registration; editing the
policy file later requires reinstalling. Tool calls cannot change permissions.

| Setting | Default | Options |
| --- | --- | --- |
| `--root` | Current directory | File access stays within this resolved directory |
| `--allow-host` | None | One or more exact hostnames or IPs; no wildcards |
| `--allow-private-network` | Disabled | RFC1918 IPv4 and IPv6 unique-local addresses |
| `--http-methods` | `GET,HEAD,OPTIONS` | Explicit subset of the seven supported methods |
| `--timeout-ms` | `5000` | HTTP / DB timeout, 100–30000 ms |
| `--max-rows` | `100` | DB row limit, 1–200 |
| `--debug` | Disabled | Sanitized diagnostics on stderr |

HTTP and database connections share the network policy. DNS results are validated
and pinned to the connection. HTTP redirects are returned without following them.
Link-local addresses (including cloud metadata), unspecified addresses, multicast,
and broadcast are always blocked. No proxy environment variables are used.

## Database discovery

Call `inspect_project` to obtain a connection ID, then `db_query` with that ID.
Passwords stay in memory inside the server and its diagnostic child processes.

Supported discovery includes:

- `DATABASE_URL`, `DB_URL`, Spring datasource URLs, including JDBC PostgreSQL/MySQL.
- Standard `PGHOST` / `PGPORT` / `PGDATABASE` / `PGUSER` / `PGPASSWORD` variables.
- `MYSQL_HOST` / `MYSQL_PORT` / `MYSQL_DATABASE` / `MYSQL_USER` / `MYSQL_PASSWORD`.
- `DB_HOST` plus an explicit `DB_TYPE` or `DB_CONNECTION` of `postgres` or `mysql`.
- `.env`, `.env.development`, `.env.local`, `.env.development.local`, Spring
  `application*.properties` / YAML, and explicit Compose environment URLs.
- Existing `.db`, `.sqlite`, `.sqlite3` files and explicit `SQLITE_PATH` / `file:` URLs.

Configuration is read from files, never executed. Compose container hostnames are
not automatically translated to host ports. Database IDs are session-scoped;
run discovery again after changing configuration. SQLite uses Node's bundled
SQLite implementation and opens the existing database read-only.

SQL is parsed and restricted to a conservative subset of `SELECT`, read-only
`WITH`, and `EXPLAIN SELECT`, with a built-in function allowlist. Server databases
also use read-only transactions. Row counts, result sizes, and query execution
time are bounded. Use a dedicated database account with read-only grants.

See [example metadata and application queries](examples/database-queries.md).

## Boundaries and limitations

- No arbitrary shell tool, file editing, process control, Git mutations, telemetry,
  or silent external requests. Explicit HTTP calls can have side effects, including
  poorly designed GET endpoints. MCP marks HTTP calls as potentially destructive.
- Returned logs, response bodies, and database rows are data, never instructions.
  Pattern-based masking cannot identify every possible secret or personal value.
  The connected AI client receives diagnostic results; choose appropriate projects
  and queries. See [SECURITY.md](SECURITY.md).
- Logs must exist as accessible regular files. Unrelated terminal stdout is not
  available. Log search examines at most the last 1 MiB of each of 10 files.
- Project discovery visits at most 2,000 entries, four directories deep, excluding
  dependency/build directories and symlinks. File reads are capped at 1 MiB.
- Process and port results are capped at 200. Ownership depends on OS permissions.
  Linux uses `/proc`; Windows process snapshots use the built-in task list;
  macOS and Windows port inspection use `systeminformation` with standard system
  facilities. Restricted containers or stripped-down OS images can limit results.
- Git status uses a Node implementation and supports ordinary repositories.
  Linked worktrees, external object stores, symlinked Git metadata, and repositories
  exceeding the bounded scan are rejected. Full diffs are not exposed.
- Structured tool output is capped at 128 KiB. At most four diagnostics run at once.
  Diagnostic child processes are stopped when they exceed their deadline.
- TLS certificate verification remains enabled. Private CA / custom TLS options,
  Docker logs, SSH, and production infrastructure management are not implemented.

## Development and release

```sh
npm ci
npm run check
npm pack --dry-run
```

Tests cover masking, path and SQL boundaries, network permissions, HTTP limits and
timeouts, actual stdio MCP calls, SQLite, Git, and installer/doctor round trips with
temporary client homes. CI runs Node 22/24 on macOS, Linux, and Windows and uses
disposable PostgreSQL/MySQL service containers for database integration tests.
Docker is used only by CI, never required by the product.

The npm publication workflow is manual. Configure the `npm` environment and an npm
trusted publisher (or `NPM_TOKEN`) before running it. A GitHub push alone does not
publish to npm. See [CONTRIBUTING.md](CONTRIBUTING.md).

Client integration references: [Codex MCP](https://developers.openai.com/codex/mcp/),
[Claude Desktop local servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers),
[Cursor MCP](https://docs.cursor.com/context/model-context-protocol).

MIT licensed.