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
-
findingsis the command an agent reads first: a ranked list of findings, 20 unless--limitsays 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.
compareputs the window before a mark beside the window after it, endpoint by endpoint and query by query. - A verdict with an exit code
-
checkturns 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 |
Anything that can run |
The CLI, |
Claude Code and every agent with a shell. It also works when no Spider Sense is running, straight from the H2 file. |
The skills, |
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 |
Read-only SQL, |
A question no command has a column for. Storage lists the tables and the columns to query. |
MCP, |
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 |
A host without a shell (Claude Desktop, an IDE chat panel) |
MCP |
The only case the CLI cannot serve. |
CI, a build gate |
The CLI’s |
A build step passes or fails on its exit code, and |
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
initprepared, the Spider Sense block ofCLAUDE.mdorAGENTS.mdnames it (The block). -
Under the Gradle plugin,
./gradlew bootRun(orrun) is step 1, and./gradlew -q spiderSense --args="<command>"takes the place of everyjava -jar "$SENSE" <command>(Tasks). -
Only inside the Spider Sense repository itself does
./gradlew :spider-sense-agent:senseJarbuild it, underspider-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
-
Start the application under the agent, with
-javaagent, or withJAVA_TOOL_OPTIONSwhen the start command is not the agent’s to change, and confirm withstatus, which names the mode, the port, the database and how much it holds. -
Mark the moment with
mark before, then exercise the endpoints in question, run the tests, or run the load generator. Call each endpoint once beforemark before: a cold JVM’s first call includes class loading, JIT compilation and opening the connection pool, and a before window that holds it makescomparesaybetterabout a change that was never made. -
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 itstracesand the code. -
Fix the code, and rebuild and restart when the fix needs it.
-
Verify with
mark after, the same exercise, thencompare --before=before --after=afterandcheck. After a restart the JVM is cold again, so call each endpoint once beforemark after. -
Resolve the finding once
checkpasses, withresolve <finding id> --note=<the fix>, so the finding is aregression, 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 |
|
A start script from |
|
A start command that is not yours to edit |
|
Spring Boot or |
The |
Maven Spring Boot |
|
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
--jsononly when a value has to be parsed. -
Keep the window small. The default
--since=15mincludes requests from before the change.--since=beforeor--since=startcovers 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
checkpass, becausecheckdoes not look at acknowledgements. -
Run
checkbefore 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, sofindingsreports it as aregressionandcheckfails if a later change brings it back. Treat aregressionat the top offindingsas the first thing to fix: a change undid an earlier fix. -
sqlis the last resort, not the first.findingsand the tables come with the thresholds, the ranking and the evidence already applied. Reach forsqlonly 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
-javaagentto the start command is part of the loop. Editing the project’s ports, thresholds orspidersense.*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
statusshows the mode, the port, the database and how much it holds.