The Loop

The loop is the sequence of steps an AI coding agent runs against Spider Sense: start the application under the agent, mark a moment, exercise it, read the findings, fix, mark again, compare, check.

What an agent needs

A person finds a group of slow requests by looking at the scatter chart. An agent reads only text, every line it reads takes room in its context, and it needs a pass or a fail to decide its next step. Four requirements follow from that, and the interfaces in the next section meet them.

Findings, not charts

findings is the command an agent reads first: a ranked list of findings, 20 unless --limit says otherwise and 100 at most. Each finding carries the numbers that justify it, the trace ids that prove it, and the code location when one is known. The time series and the response-time buckets are left to the UI’s charts.

Text first

Every agent-facing answer has a Markdown rendering beside the JSON one. A trace is an indented tree, a list is a table, and repeated siblings are collapsed. The text is deterministic, so the same data renders to the same bytes and two answers can be diffed.

Before and after

After a change the agent needs to know whether it helped. A mark gives a point in time a name. compare puts the window before a mark beside the window after it, endpoint by endpoint and query by query.

A verdict with an exit code

check turns thresholds into pass or fail, so the agent can use Spider Sense the way it uses a test.

Every answer is served by the same Queries the UI uses, so the numbers an agent quotes are the numbers a person sees on screen.

Interfaces

Interface When it is the right one

HTTP API with format=text

Anything that can run curl.

The CLI, java -jar spider-sense.jar <command>

Claude Code and every agent with a shell. It also works when no Spider Sense is running, straight from the H2 file.

The skills, skills/spider-sense/ and skills/spider-sense-sql-tuning/

The first teaches an agent the loop itself: how to start the application under the agent, mark, exercise, read findings, fix, compare and check. The second teaches query tuning: indexes, rewrites, fetch joins and batching, verified with compare and check.

Read-only SQL, POST /api/sql and the sql command

A question no command has a column for. Storage lists the tables and the columns to query.

MCP, POST /mcp and the mcp command

Hosts without a shell. Eight tools over the same handlers, answering the same text.

The CLI documents every command, MCP the two transports and the eight tools, The Agent Skill the skill and its installation, and The HTTP API the wire shapes.

Choosing an interface

The CLI and MCP call the same handlers and print the same bytes, so both return the same text for the same question. The choice depends only on what the host can reach.

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 task

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

The application has crashed

The CLI, or MCP over stdio

Both open the H2 file in process. MCP over HTTP needs the server up.

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.

The skill teaches the loop for the CLI. The MCP server’s instructions field carries the same loop in one paragraph, so a host on MCP gets the same steps as a host on the CLI.

The loop

$SENSE below is the Spider Sense jar’s absolute path, and where it comes from depends on the project.

  • In a project init prepared, the Spider Sense block of CLAUDE.md or AGENTS.md names it (The block).

  • Under the Gradle plugin, ./gradlew bootRun (or run) is step 1, and ./gradlew -q spiderSense --args="<command>" takes the place of every java -jar "$SENSE" <command> (Tasks).

  • Only inside the Spider Sense repository itself does ./gradlew :spider-sense-agent:senseJar build it, under spider-sense-agent/build/libs/:

# in the Spider Sense repository only
SENSE="$(ls spider-sense-agent/build/libs/spider-sense-[0-9]*.jar 2>/dev/null | head -1)"
[ -n "$SENSE" ] || { ./gradlew :spider-sense-agent:senseJar; SENSE="$(ls spider-sense-agent/build/libs/spider-sense-[0-9]*.jar | head -1)"; }

Then, in order:

java -javaagent:"$SENSE" -jar build/libs/app.jar &   # 1. start the application under the agent
java -jar "$SENSE" status                            # confirm it is collecting
curl -s http://localhost:8080/orders/42 >/dev/null   #    warm each endpoint once: a cold JVM's first call is not the code's speed
java -jar "$SENSE" mark before                       # 2. name the moment
curl -s http://localhost:8080/orders/42 >/dev/null   #    exercise: the endpoints in question, the tests, or the load generator
java -jar "$SENSE" findings --since=before           # 3. read the top finding
java -jar "$SENSE" trace 4bf92f3577b34da6a3ce929d0e0e4736   #    open its evidence, locate the code
#                                                    # 4. fix, rebuild, restart, and warm each endpoint once again
java -jar "$SENSE" mark after                        # 5. exercise the same way
java -jar "$SENSE" compare --before=before --after=after
java -jar "$SENSE" check --since=after --max-p95-ms=300 --max-n-plus-one=0
java -jar "$SENSE" resolve n-plus-one:4c5f46be8bc5 --note="fetch join"   # 6. once check passes
  1. Start the application under the agent, with -javaagent, or with JAVA_TOOL_OPTIONS when the start command is not the agent’s to change, and confirm with status, which names the mode, the port, the database and how much it holds.

  2. Mark the moment with mark before, then exercise the endpoints in question, run the tests, or run the load generator. Call each endpoint once before mark before: a cold JVM’s first call includes class loading, JIT compilation and opening the connection pool, and a before window that holds it makes compare say better about a change that was never made.

  3. Read the findings with findings --since=before, and take the top one. Read its suspect-change lines first, which say whether the frame’s line is in the change just made (The suspect change), then open a trace from its traces and the code.

  4. Fix the code, and rebuild and restart when the fix needs it.

  5. Verify with mark after, the same exercise, then compare --before=before --after=after and check. After a restart the JVM is cold again, so call each endpoint once before mark after.

  6. Resolve the finding once check passes, with resolve <finding id> --note=<the fix>, so the finding is a regression, ranked first, if a later change brings it back.

After a restart there is a fresh start mark, so --since=start covers the new run without marking anything. --url=<base url>, or the SPIDERSENSE_URL environment variable, points the CLI at a Spider Sense on another port. --db=<path> reads a database directly. init writes the Spider Sense block into the project’s CLAUDE.md or AGENTS.md and installs the skills into .claude/skills/, so the next session finds both without being told.

Starting the application under the agent

You restart the application with the agent on its command line. Spider Sense does not attach to a JVM that is already running.

Situation How

A jar, or a main class you launch

java -javaagent:"$SENSE" -jar app.jar

A start script from installDist, or anything honouring JAVA_OPTS

JAVA_OPTS="-javaagent:$SENSE" build/install/app/bin/app

A start command that is not yours to edit

JAVA_TOOL_OPTIONS="-javaagent:$SENSE" <command>

Spring Boot or application under Gradle

The net.benelog.spidersense plugin, then ./gradlew bootRun or ./gradlew run

Maven Spring Boot

mvn spring-boot:run -Dspring-boot.run.agents=$SENSE

The Three Modes covers the agent mode, forwarding to a shared Spider Sense, and the standalone server. The Gradle Plugin and Maven cover each build tool in full, including test tasks. Configuration lists every property, including spidersense.port when 4000 is taken, otel.service.name so the service has a name, and spidersense.collector to forward to a Spider Sense running elsewhere.

Reading findings

findings ranks by severity, then by kind, then by impact, then by id, so the list is stable between two calls over the same data. The table lists the findings in rank order, and the numbered blocks under it hold each row’s evidence, one per row and in the same order. Each finding carries why (the numbers in a sentence), numbers (kind-specific), statement (when the finding is about one), code (application frames, innermost first) and traces (at most three). Findings documents every kind, its numbers and the fix it usually wants.

trace <id> opens the evidence as an indented tree: one span per line with its offset and duration, the service named where it changes, repeated siblings collapsed after the third into × n, the statement under a slow or collapsed database span, the exception and its application frames under an error span, and the trace’s log lines at the end. --full expands the collapsed spans and keeps statements whole.

When a finding is known and accepted, ack <finding id> --note=<why> moves it to the bottom of every later list, so the top of the list shows what is new. Acknowledgements covers ack, unack and --hide-acked.

The state column says what the last restart changed: new for a finding the run before it did not have, ongoing for one it had. findings --since=start therefore names the findings the last change introduced without a second mark (State).

Verifying a change

# after a restart, call each endpoint once first: a cold JVM's first call is not the code's speed
java -jar "$SENSE" mark after
# exercise exactly as before: the same endpoints, the same number of times
java -jar "$SENSE" compare --before=before --after=after
java -jar "$SENSE" check --since=after --max-p95-ms=300 --max-queries-per-request=5 --max-errors=0

compare gives each endpoint, query and error a verdict. The verdict is the first column, and the rows sort worse, new, same, better, gone, so anything that got worse is at the top of each table. Every other cell holds both windows as before → after, with — where a side has nothing. Compare documents the windows, the rows and the exact verdict thresholds.

check prints the verdict in its heading and then one row per rule, with its limit, its actual value, its own verdict and a detail naming what decided it. Exit code 3 means the exercise step did not reach the application, not that the fix worked. Check documents every rule and every exit code.

Once check passes, record the fix:

java -jar "$SENSE" resolve n-plus-one:4c5f46be8bc5 --note="fetch join"

If a later change brings the finding back, findings reports it as a regression, first in the list, and check fails on it by default (Resolutions).

Rules

  • Prefer the CLI’s text output. It carries the same data as the JSON and is smaller. Reach for --json only when a value has to be parsed.

  • Keep the window small. The default --since=15m includes requests from before the change. --since=before or --since=start covers only the requests since that mark.

  • Never quote a number the tool did not print. Percentages, p95s and call counts come from the output, not from an estimate.

  • Quote the trace id as evidence. The user cannot check a claim about an endpoint that names no trace.

  • Acknowledge a finding the user has accepted, with the reason as its note, so it sorts below the findings that are new. Never acknowledge one to make check pass, because check does not look at acknowledgements.

  • Run check before calling a fix done, and say which rules it passed with which limits.

  • Resolve a finding once its fix passes check, with the fix as its note, so findings reports it as a regression and check fails if a later change brings it back. Treat a regression at the top of findings as the first thing to fix: a change undid an earlier fix.

  • sql is the last resort, not the first. findings and the tables come with the thresholds, the ranking and the evidence already applied. Reach for sql only when none of them has a column for the question, and say so when its answer was capped.

  • Do not change the monitored application’s Spider Sense configuration unless asked. Adding -javaagent to the start command is part of the loop. Editing the project’s ports, thresholds or spidersense.* properties is a change to the project.

  • Nothing in Spider Sense may keep the application from starting. If the agent fails during startup, it logs the failure and the application starts without it. When the application runs but no data arrives, the cause is in the configuration, and status shows the mode, the port, the database and how much it holds.