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 |
Maven, or no build tool |
Download |
A version not on Maven Central yet |
Build it from a checkout, and |
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 |
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 |
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 |
|---|---|
|
The same query running 5 or more times under one request. |
|
The same outbound HTTP call running 5 or more times under one request. |
|
A query whose p95 is over the slow-query threshold. |
|
An endpoint, a background job, or an outbound HTTP call whose p95 is over the slow-request threshold. |
|
An exception group, or an |
|
A JDBC pool with requests waiting, or every connection in use. |
|
A long or frequent collection, heap at 90% of its limit, or a thread count that keeps climbing. |
|
A finding of any other kind that was resolved with |
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 runsfindings --since=beforeandtrace. - 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 runscompare --before=before --after=after. - Gate a change
-
"Make sure
/ordersstays under 300 ms p95 with no N+1." The agent runscheck --max-p95-ms=300 --max-n-plus-one=0and 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=startstill 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).