Agent slash commands

This project ships several Claude Code  slash commands that drive the graph commands as their tools:

• /codespine-interview — read-only; interviews you to scope a measurable optimization target and grounds each candidate in the graph.
• /codespine-optimize — finds and applies one verified-safe optimization.
• /codespine-name-communities — names the cluster communities by what each one does, reading members from the graph and writing the labels back — no API key.

Because the agent runtime is Claude Code itself, there is nothing to configure beyond installing the commands and pointing them at a graph — the model, the API key, and the provider all come from Claude Code, as the next section explains.

Configuration with Claude

The agent has no configuration of its own — no model selection, API key, provider, or .env file. That falls out of where it runs: the runtime is Claude Code . Claude Code supplies the model and the tool-calling loop; these slash commands and the codespine-query skill only tell it what to do and which graph queries to reach for. There is no separate agent process to host and no provider to point at.

So “configuring” the agent comes down to two things — making those instructions visible to Claude Code, and giving them a graph to query:

• The command and skill files must live in the project’s .claude/. They are authored under dotclaude_folder/ and mirrored into .claude/ — the commands under .claude/commands/, the codespine-query skill under .claude/skills/. The next section covers installing them.
• A loaded graph must exist at the default database ./.codespine/graph.kuzu. If it does not, both commands build it first with npx codespine extract . --semantic followed by npx codespine load. The --semantic flag is required: the agent relies on the caller and heritage edges that only a semantic extraction emits.

Installing the commands

The commands are already committed in this repository’s .claude/. For another project, install them with one command from that project’s root:

npx codespine install

This copies the slash commands and the codespine-query skill into the project’s .claude/ — see install (pass --force to refresh existing copies). Inside this repository’s own checkout you can instead run npm run symlink:dotclaude, or copy the files under dotclaude_folder/ by hand. If Claude Code reports “/codespine-optimize is not a known command,” the files have not been installed.

/codespine-interview

A read-only optimization analyst. Its job is not to change code — it interviews you, narrows a vague wish (“optimize this”) into one or more concrete, measurable, well-scoped tasks, and grounds each candidate in the graph so it points at real symbols. It finishes by presenting tasks; it never applies them.

/codespine-interview
/codespine-interview the JSON serialisation path

An optional argument is treated as a starting hint (a dimension, subsystem, or named symbol) to steer the interview.

What “optimize” means

“Optimize” is multi-dimensional, so the command establishes the dimension rather than guessing. It walks you through five steps, one focused round of questions at a time:

1. Dimension — execution time / latency, memory, infrastructure cost (including LLM tokens), network, scalability, maintainability, bundle size, energy.
2. Business concern — the pain point, not the metric (“cloud bill too high”, “search feels slow”).
3. Measurable target — a baseline and a target (800ms → 300ms, 10M → 2M tokens/day). If it cannot be measured, it cannot be optimized.
4. Scope — which part of the system, down to a specific module or symbol.
5. Constraints — what must be preserved (functionality, security, API contract, UX, accuracy).

What the graph can and cannot ground

The graph is a static model: it knows symbols, callers, references, and dead code, but holds no runtime telemetry (latency, CPU, memory, cost, frequency). So the command is decisive for maintainability / dead-code work (dead-exports is a direct source of candidates) and for structural risk / coupling (rank centrality with references, who-calls, blast-radius, neighbors). For runtime dimensions it can only show where a hot path lives structurally — you must supply the measurement and baseline. It says so plainly rather than inventing numbers.

Each drafted task is self-contained and shaped to hand to /codespine-optimize, with a title, dimension and scope, target (real node ids and paths), measurable goal, constraints, graph evidence, and an estimated risk argued from blast radius and coupling. The command ends by telling you to run /codespine-optimize "<task>" yourself with whichever task you choose.

Full definition: dotclaude_folder/commands/codespine-interview.md.

/codespine-optimize

An autonomous TypeScript optimization agent that uses the graph as its eyes — resolved symbols and types, so its answers about callers, references, and dead code are precise where text search is not.

/codespine-optimize
/codespine-optimize Inline the single-use helper formatRow in src/report.ts

With no argument it runs the default mission: find one genuinely dead exported symbol, prove it has zero inbound references, and remove it safely. With an argument, it treats that text as the task.

The method

The command drives a find → confirm → edit → verify → keep/revert loop:

1. Find a candidate — dead-exports (dead code is the safest win) or find to locate a named target.
2. Confirm the blast radius — before any change it confirms safety with references (and who-calls / blast-radius when useful). A symbol is safe to remove only when it has zero inbound references.
3. Read the exact text so the edit matches the file precisely.
4. Make exactly one edit.
5. Verify, then keep or revert — runs verify, one gate that runs the type-check and the test suite. ok: true → the edit stands; ok: false → it reverts immediately with git restore <file> and tries a different edit or abandons the change. It never leaves a failing verify behind.
6. Measure the impact (optional) — when the task targets a runtime metric and a workload exists, it can report a benchmark delta. This is advisory — a noisy median, never a guarantee, and never allowed to override the hard verify result.
7. Stop and summarize — the file changed, the symbol removed, and why it was safe. It states plainly how the edit was verified: type-checked and tested only when behaviorVerified was true; type-check-only (degraded) is reported as not behaviourally verified.

Rules it follows

• Node ids come from find and dead-exports output; it never invents them.
• It acts autonomously — it does not ask you questions mid-run.
• It prefers removing genuinely dead exports or behavior-preserving simplifications, and never changes observable behavior.
• Run it on a clean git tree so a revert restores a known-good state and git diff shows exactly what it kept.
• At most one verified edit per run.

Full definition: dotclaude_folder/commands/codespine-optimize.md.

/codespine-name-communities

Names the code communities that cluster has already detected. Detection is the algorithm’s job; naming is a language task, and this command hands it to the agent — no API call and no key, because the runtime is Claude Code itself: it reads each community’s members and writes a label back.

/codespine-name-communities
/codespine-name-communities ./.codespine/project_01

An optional argument is the output folder holding the graph (default ./.codespine); it is passed through as -o to every command.

The method

A dump → name → apply loop over two cluster subcommands:

1. Dump the detected communities and their members with cluster communities --json — { index, currentLabel, size, members }, largest first. (If none exist yet, it runs cluster first.)
2. Name each community from its members — a concise noun phrase for its responsibility (“Citation rendering”), not its location (utils · citation). It leaves a community alone when the structural label is already a good name.
3. Apply the names with cluster rename --labels <file>, which writes metadata.communityLabel and the clustering manifest. The webview legend and reports then show them unchanged.

Because the labels are keyed by community index, it names after detection and without re-detecting in between; a later cluster run resets the labels to the structural baseline.

Full definition: dotclaude_folder/commands/codespine-name-communities.md.

The codespine-query skill

Alongside these commands, install ships a skill, codespine-query. Where the commands are missions (optimize, interview), the skill is a reflex: it tells the agent to reach for the graph — not grep / glob — whenever a question is about code structure or impact, and which command answers it.

It also encodes the two ground rules every query here follows: resolve a name to a node id with find --json first (never hand-write ids), and consume the --json output rather than the human-readable table. So an agent in any session — not only a /codespine-* run — uses the graph as its eyes for impact and dependency questions.

Full definition: dotclaude_folder/skills/codespine-query/SKILL.md.

See also

• The pipeline — running the agent on its first verified edit.
• verify — the keep/revert gate the optimizer relies on.
• dead-exports — the safest starting point for both commands.