Quick Start for Agents

This chapter gets an AI coding agent from nothing to its first finding: get the jar, install the skill, choose the CLI or MCP, start the application under the agent, and ask. The chapters after it document every command, finding, and transport in full.

Get the jar

Everything below runs from one jar, so the first step is to have it. Which way depends on the project’s build.

0.1.0 is not on Maven Central yet, so the first two rows below do not work as written until it is published. Until then, build the jar from a checkout, the last row, whatever the project’s build (Coordinates).
Build How

Gradle

Apply id 'net.benelog.spidersense' version '0.1.0' in plugins {}. The plugin resolves the jar from Maven Central, and ./gradlew spiderSenseInit takes the place of init below (The Gradle Plugin).

Maven, or no build tool

Download net.benelog.spidersense:spider-sense:0.1.0 from Maven Central into the project, for example curl -fLo spider-sense.jar https://repo1.maven.org/maven2/net/benelog/spidersense/spider-sense/0.1.0/spider-sense-0.1.0.jar (Maven).

A version not on Maven Central yet

Build it from a checkout, and ./gradlew publishToMavenLocal for a Gradle build that resolves it from mavenLocal() (From a checkout).

An agent can do this step itself. The prompt below hands it the whole chapter:

Follow https://spider-sense.benelog.net/agent-quickstart.html to set up Spider Sense in this project: get the jar, install the skills with init, and start the application under it.

Install the skill

The skill is the agent’s manual, in the form an agent loads into its context: the loop, the commands, and the rules for reporting a result, which are to quote only numbers the tool printed, to name the trace id, and to run check before calling a fix done (The Agent Skill). The Spider Sense jar carries the skill, so there is no repository to clone.

Claude Code

Run init in the project:

java -jar spider-sense.jar init

init writes a Spider Sense block into the project’s CLAUDE.md (or its AGENTS.md, as below), with the jar’s absolute path and the commands, and copies the skills into .claude/skills/spider-sense/ and .claude/skills/spider-sense-sql-tuning/. The next Claude Code session finds both without being told. In a project that applies the Gradle plugin, you run ./gradlew spiderSenseInit instead. It does the same with the jar the build resolved (init).

init is idempotent, so running it again after a version bump refreshes the jar path and the skill.

Codex

Codex reads skills from ~/.codex/skills for every project, and from a project’s own .codex/skills. Run init as above, then copy the skills into either one:

java -jar spider-sense.jar init
mkdir -p .codex/skills
cp -r .claude/skills/spider-sense .claude/skills/spider-sense-sql-tuning .codex/skills/

Codex reads AGENTS.md rather than CLAUDE.md. init writes the block into AGENTS.md when the project has one and no CLAUDE.md, and into both when it has both (which file). A project with neither gets CLAUDE.md, so for Codex create AGENTS.md first, even empty, and run init then.

Cursor and GitHub Copilot read the project’s .claude/skills/, so the init step alone serves them (Installing the skills by hand).

CLI or MCP

The CLI and MCP answer with the same bytes, because both call the same handlers. The choice depends on whether the host can run a shell command.

Host Use Why

An agent with a shell (Claude Code, Codex CLI, Gemini CLI, Aider, a script)

The CLI and the skill

No setup beyond init. It works with the application down, check is an exit code, output can be piped, and no tool schema is loaded into the context.

A host without a shell (Claude Desktop, an IDE chat panel)

MCP

The only case the CLI cannot serve. init --mcp writes the host’s server entry.

CI, a build gate

The CLI’s check, or the Gradle plugin’s spiderSenseCheck task

A build step passes or fails on its exit code, and check exits 0 on a pass and 1 on a fail.

For MCP, init --mcp adds the stdio server to the project’s .mcp.json. It then installs no skill and writes a block that names the server’s tools instead of the CLI’s commands, so the host is handed one of the two and not both. The server’s status tool confirms the application is collecting, as the CLI’s status does. A host that reaches a running Spider Sense over HTTP is configured with http://127.0.0.1:4000/mcp (MCP).

Do not enable both the CLI and MCP in one host. Two tools that give the same answer make the model choose between them, and the MCP tool schemas take up context for answers the CLI already gives.

Start the application under the agent

Spider Sense does not attach to a running JVM, so you restart the application with the agent on its command line.

java -javaagent:/path/to/spider-sense.jar -jar build/libs/app.jar

Under Gradle, the net.benelog.spidersense plugin puts the agent on bootRun and run. JAVA_TOOL_OPTIONS="-javaagent:…" covers a start command that is not yours to edit. The Loop lists every way to start the application under the agent. java -jar spider-sense.jar status confirms that the application is collecting.

What it diagnoses

findings is the command an agent reads first: a ranked list of findings, 20 unless --limit says otherwise and 100 at most, each with the numbers that justify it, the trace ids that prove it, and the code location when one is known. These are its kinds (Findings).

Kind What it catches

n-plus-one

The same query running 5 or more times under one request.

n-plus-one-http

The same outbound HTTP call running 5 or more times under one request.

slow-query

A query whose p95 is over the slow-query threshold.

slow-endpoint, slow-job, slow-external

An endpoint, a background job, or an outbound HTTP call whose p95 is over the slow-request threshold.

error, log-error

An exception group, or an ERROR log line no error span already covers.

pool-exhausted

A JDBC pool with requests waiting, or every connection in use.

gc-pause, heap-pressure, thread-growth

A long or frequent collection, heap at 90% of its limit, or a thread count that keeps climbing.

regression

A finding of any other kind that was resolved with resolve and has come back since.

Three more commands cover the rest of the loop. trace <id> opens one request as a tree, with the statement under a slow query and the stack under an error. compare puts the window before a mark beside the window after it, with a verdict per endpoint and query. check turns thresholds into pass or fail in its exit code.

What to ask

The skill teaches the agent the loop, so your prompt names the goal and the agent runs the commands. Each prompt below is an example, followed by the commands the agent runs for it.

Find what is slow

"Start the app under Spider Sense, hit the order endpoints, and tell me the top finding with its trace." The agent starts the application, runs mark before, exercises the order endpoints, then runs findings --since=before and trace.

Explain one symptom

"GET /orders/{id} feels slow. Is it the queries?" The agent reads the endpoint’s finding and opens a trace to show the query count and the statement.

Fix and prove it

"Fix the N+1 on the orders page and show me before and after." The agent fixes the code, restarts the application, runs mark after, exercises the same way, then runs compare --before=before --after=after.

Gate a change

"Make sure /orders stays under 300 ms p95 with no N+1." The agent runs check --max-p95-ms=300 --max-n-plus-one=0 and reports which rules passed with which limits.

After a crash

"The app died under load. What was it doing?" The CLI reads the H2 file when no Spider Sense is listening, so findings --since=start still answers.

An agent that follows the skill quotes only numbers the tool printed, names a trace id as evidence, keeps the window to the run in question, and runs check before calling a fix done (The Loop).