Claude Plugin
The Spantail plugin for Claude Code captures your Claude Code sessions as agent activity automatically, and adds skills and agents for logging work and building reports from inside Claude Code.
Requires Claude Code v2.1.143 or later.
Install
Section titled “Install”Enabling the plugin prompts for your instance URL and an agent access token (register an agent first), plus an optional personal API token for the skills’ MCP server (see Skills and agents). Claude Code stores this config per plugin and shares it across all your repositories, whatever install scope you pick — which is why the workspace and project are not part of it. Pick user scope when the installer asks: one install covers every repository, and attribution is per repository (below).
Each setting can be overridden with an environment variable
(SPANTAIL_API_URL, SPANTAIL_AGENT_TOKEN, SPANTAIL_SEND_SESSION_SUMMARY)
— the environment wins. These overrides apply to the hooks only; the
bundled MCP server reads the plugin’s apiUrl and apiToken config, so keep
them in sync if you override the instance via SPANTAIL_API_URL.
The hooks need bash, jq, and curl on PATH. They never fail a turn or
block a session from ending: on any problem they log to stderr and skip.
Link a repository
Section titled “Link a repository”Which workspace and project a repository’s sessions land in is configured in the repository itself. In each repository you want attributed, run:
It asks for the workspace and project ids (copy them with the copy buttons
in the sidebar: workspace switcher and project list) and writes them to
.spantail/config.local.json — personal; keep it out of git
(the skill reminds you if it is not ignored yet). For a
team-shared link, /spantail:link --shared writes .spantail/config.json
instead; commit it once and every collaborator who installs the plugin
inherits it.
These files may only carry workspaceId and projectId; the hooks refuse
apiUrl or tokens from a repository, since a cloned repo is untrusted
input. A linked repository owns attribution outright, and a personal local
file replaces a committed shared one entirely — a workspace-only link
never inherits a project configured elsewhere. Environment variables
(SPANTAIL_WORKSPACE_ID, SPANTAIL_PROJECT_ID) override both files.
A repository you never link has no attribution target: its sessions are
rejected at ingest rather than silently landing somewhere. (To route every
unlinked repository to one workspace anyway, set SPANTAIL_WORKSPACE_ID
user-globally.) Run /spantail:doctor any time to see where each setting
resolves from, whether the current repository is linked, and what to fix.
What gets sent
Section titled “What gets sent”The plugin’s hooks send compact telemetry only — conversation bodies, thinking, and tool input/output never leave your machine:
- On every Stop (end of a turn): per-turn token usage, timestamps, and model names, plus the git branch, repository URL, working directory, Claude Code version, and provider request ids as event attributes. The post runs detached in the background, so a slow network never delays your next prompt.
- On SessionEnd: a final idempotent re-post of the events, then a
finalize with the wall-clock end
and the pull requests the session touched (as
context.refs).
One thing is opt-in: with the sendSessionSummary setting (or
/spantail:summary on for a single session), the SessionEnd hook also sends
a title as the entry’s description: the title of the session’s plan file,
or — when the session used no plan — the transcript’s own session title
(the one Claude Code generates; it exists only on compacted or resumed
sessions). Both are extracted mechanically from structured transcript
records — no extra inference — and a session with neither simply leaves the
description empty. Like any description it is stored verbatim and can appear
in reports and share links — it stays off unless you turn it on.
Skills and agents
Section titled “Skills and agents”| What | Purpose |
|---|---|
/spantail:log-work |
Log a work entry — from your words or from the current session’s work. When it records the current session, that session’s agent entry (once captured) is linked to the work entry automatically. |
/spantail:log-work #N <duration> [date] |
Log against a GitHub issue: the server resolves the project from its repo mapping (see GitHub integration), fills in the issue title and labels, and links matching agent sessions — including the session you run it from, once its telemetry exists (its first completed turn creates it). Titles of linked sessions are appended to the entry’s note when they have one. |
/spantail:create-report |
Compose a report; always previews before saving. |
/spantail:summary on|off |
Per-session toggle for sending the session’s title (plan title, else the generated session title) as the description. |
/spantail:link [--shared] |
Link the current repository to a workspace and project (see Link a repository). |
/spantail:doctor |
Show where every plugin setting resolves from and what to fix. |
spantail-work-analyst (agent) |
Retrospectives over your work entries. |
spantail-agent-activity-analyst (agent) |
Analysis of your agents’ session telemetry. |
The skills and analysis agents act as you, so they use the
Spantail MCP connection with a personal API token — a
separate credential from the hooks’ write-only agent token. The plugin bundles
this MCP server: set the optional apiToken and it connects to your instance’s
/mcp over HTTP as you. Hook-only users can leave apiToken blank; no CLI is
needed. Two exceptions: /spantail:doctor and /spantail:link work
without the MCP.
To use the MCP from another client, or without the plugin, register it manually — see MCP.
Without the plugin
Section titled “Without the plugin”The hook scripts also run standalone with manually wired settings.json
hooks and SPANTAIL_* environment variables — see the
plugin README
for the copy-and-adapt instructions, or send telemetry programmatically via
the ingest API.