@rantingjs/assist

What AI coding agents (Claude Code, Cursor, Codex, Copilot...) need to work on a ranting app without guessing: an MCP server with tools on the app itself (its database, logs, browser logs, URLs and the documentation of the ranting packages it has installed), and project rules shared through the repository.

bunx ranting install @rantingjs/assist --dev

It runs only in a local app (APP_ENV=local) or one with APP_DEBUG=true, and never under tests.

Setting up the agents

bunx ranting assist:install

asks which features (guidelines, skills, the MCP server) and which agents to set up, offering the agents whose files the project already has; --guidelines --skills --mcp --agents claude_code,cursor answers without asking. For each agent it writes:

• the guidelines into CLAUDE.md (Claude Code, when the file exists) or AGENTS.md, inside a <ranting-assist-guidelines> block; what the file holds outside that block is left as it is;
• the skills into the agent's skills folder (.claude/skills, .cursor/skills, .agents/skills...);
• the MCP server into the agent's MCP config (.mcp.json, .cursor/mcp.json, .codex/config.toml...), next to the servers already there. A config with comments is not rewritten: the command says what to add by hand.

Agents: amp, antigravity, claude_code, codex, copilot, cursor, factory, grok_build, kiro, opencode, pi, zed. What was chosen is kept in assist.json; commit it with the files written.

bunx ranting assist:update writes the guidelines and skills again, for the same agents: after updating packages, or after changing .ai/guidelines or .ai/skills. It leaves the MCP configs alone.

Guidelines and skills

The guidelines tell an agent what this app is (ranting's version, Bun's, the packages installed), how ranting is written (controllers, validation, models, migrations, tests, a client/ frontend when there is one) and how to use the MCP tools. Their code examples are compiled against ranting's API in this package's tests, and every command and tool they name is checked to exist, so they cannot drift from what ranting does.

• An app's own guidelines: markdown files in .ai/guidelines/. One named like a built-in one (ranting.md) replaces it; any other is added.
• A ranting package can carry guidelines in assist/guidelines/ and skills in assist/skills/.
• Skills are folders with a SKILL.md (name, description in its frontmatter): the built-in infer-conventions (it reads the codebase and records its conventions as project rules), the packages' ones, and the app's own in .ai/skills/.

The MCP server

bunx ranting assist:mcp speaks MCP over stdin and stdout. An agent starts it from its MCP settings (assist:install writes them), for example .mcp.json for Claude Code:

{
  "mcpServers": {
    "ranting-assist": { "command": "bun", "args": ["x", "ranting", "assist:mcp"] }
  }
}

Every tool call runs in a process of its own (assist:execute-tool), so a tool sees the code, config and .env as they are after the agent changed them.

| Tool | What it does | |---|---| | application-info | Bun and ranting versions, the database engine, the installed packages with their versions, the models | | database-connections | The connection names and the default one | | database-schema | Tables with their columns (summary), or columns, indexes and foreign keys of the tables a filter matches (include_column_details, include_views) | | database-query | A read-only query: one statement that only reads (SELECT, SHOW, EXPLAIN, DESCRIBE, WITH … SELECT), run with the database itself set to refuse writes (SQLite's query_only, a read-only transaction elsewhere, rolled back) | | get-absolute-url | A path or a named route as a full URL, from APP_URL | | last-error | The last error entry of the app's log | | read-log-entries | The last N entries of the app's log (text entries with their stack, or JSON lines) | | browser-logs | The last N entries of the browser's console output and errors | | search-docs | Searches the documentation of the installed ranting packages (see below) | | record-rule | Records a project rule in .ai/rules, only when the user asks for one | | tinker | Runs code inside the app, like ranting tinker --execute; off unless assist.tinkerTool |

Searching the documentation

search-docs reads the documentation the installed packages carry, at their installed versions: the framework's pages (docs/, from routing to queues) and the README of each ranting package (@rantingjs/inspector, @rantingjs/metrics...). It splits them at their ## and ### headings and returns the sections that match, best first, each with its source (docs/routing.md), as written: nothing is summarised. When nothing matches, it says so.

• Words must all appear, in any form (routes finds route; temporaryUrl is the words temporary and url).
• "quoted phrases" must appear as written.
• Several queries are alternatives: ["rate limiting", "throttle"].
• packages limits the search (["@rantingjs/framework"]); token_limit (3000 by default) sets how much comes back.

Browser logs

In a local app, every HTML page gets a small script that sends the browser's console output, errors and unhandled promise rejections to POST /_assist/browser-logs, written to storage/logs/browser.log for the browser-logs tool. ASSIST_BROWSER_LOG_LEVELS (error,warning,info,debug by default) chooses what is sent. Pages with a Content-Security-Policy nonce get the script with that nonce.

What lands there reaches an AI agent, so only the app's own pages may write it (a same-origin request, or an Origin of the app), each entry stays on one line, and requests are bounded (256 KB, 100 entries, 10,000 characters a message).

Project rules

Rules are what agents should know about this app beyond the framework: decisions, conventions, traps. Each lives in a markdown file of .ai/rules/ with the globs it applies to in its frontmatter, and .ai/rules/index.md maps the globs to the files. Ask your agent to remember something and it records it through record-rule; commit .ai/rules. bunx ranting assist:index-rules writes the index again after hand edits (it stops at files with merge conflicts).

Config

bunx ranting publish @rantingjs/assist --tag config copies src/config/assist.ts: enabled (ASSIST_ENABLED), browserLogsWatcher, browserLogLevels, rules.enabled (ASSIST_RULES_ENABLED), mcp.exclude (tools to leave out, by name), mcp.toolTimeout (seconds, 180) and tinkerTool (ASSIST_TINKER_TOOL).