Coding agents
A coding agent can reach everything Tracepad has without help: the CLI answers
in JSON when piped, the MCP server is in the binary, and GET /api/v1
describes every route. What it lacks is the order of work — which door to use,
what to read before writing, what a healthy answer looks like, and which acts
need a human. The agent skill teaches that order, and it ships inside the
binary so that its version is always the server's.
This page is the whole setup: install the skill, connect MCP if the agent speaks it, and give the CLI its two variables.
Installing the skill
That is the user-wide skills directory of Claude Code, which every session of that user reads. Two other places:
tracepad skills install --project # ./.claude/skills/tracepad, for one repository
tracepad skills install --dir ~/.agents/skills # DIR/tracepad, for any other agent's skills directory
--project writes into the working directory's .claude/skills, which a
repository can commit so that everyone who clones it has the skill. --dir
is for any agent that reads the same layout — a SKILL.md with a
references/ directory beside it — from another place.
The install script runs this command for you, in each skills directory an agent on the machine has made.
The skill is plain files. SKILL.md is what the agent loads when a task
matches its description. Six references are read only when the task needs
one: debugging, instrumenting a service, evals, administration, setting
Tracepad up for a project from nothing, which
agent-setup.md hands an agent, and upgrading it, which
agent-upgrade.md does.
tracepad skills show prints SKILL.md and tracepad skills show
debugging.md a reference, for reading it without installing it.
Neither command talks to a server or needs a key.
Updating
tracepad upgrade does it for you, wherever a copy carries
the skill's .version marker. By hand, run the same command again after
upgrading the binary:
The directory is replaced whole, so a reference the new version dropped does
not linger. The installed SKILL.md carries the binary's version in its
frontmatter (metadata.version), and the skill tells the agent to compare it
with tracepad version and to reinstall when they differ — a development
build stamps dev, which matches anything.
A tracepad directory the command did not install — one without both the
SKILL.md naming tracepad and the .version file it writes — is refused
rather than overwritten, with the directory named; --force replaces it.
A tracepad in your own skills directory that is a symlink — a copy kept in a
dotfiles repository — is updated where it points, but only if what it points
at is a skill this command installed: a link to any other directory is refused
even with --force, because replacing it would delete a directory you never
named. Remove the link and install again. The one exception is a link to an
empty directory — how a dotfiles copy is set up the first time — which
--force installs into. The directories above it are yours, so a ~/.claude
kept in a dotfiles repository works as it is. With --project no link is
followed at all — not .claude, not .claude/skills, not tracepad — because
the links in a checkout belong to whoever wrote it; install with --dir into
the directory such a link points at instead.
From the Docker image
The image runs as nonroot. Mount the host's skills directory, run as your
own user so the files are yours, and create the directory first — a mount
point Docker creates for you is owned by root:
mkdir -p ~/.claude/skills
docker run --rm --user "$(id -u):$(id -g)" \
-v "$HOME/.claude/skills:/skills" \
ghcr.io/tracepad/tracepad skills install --dir /skills
Not docker exec into the running server: the files would be written to that
container's own layer and vanish with it. The image sets TRACEPAD_IN_CONTAINER,
and with it set skills install refuses a target that is not on a mounted
volume, naming the command above, rather than printing installed for a copy
nobody can reach.
docker run --rm ghcr.io/tracepad/tracepad skills show prints the skill
without writing anything.
By copying
agent/skills/tracepad/ in the repository is the skill, file for file. A copy
of it works as it is, with metadata.version: dev.
Connecting MCP
The server serves MCP at /mcp, and the binary serves the same tools over
stdio. Both configuration blocks, and what each tool does, are in
mcp.md. The tools only read, and take a key with the
read scope: an agent writes and deletes through the CLI or
the API, where the dry-run ceremony applies.
The skill works without MCP — the CLI is the door it uses first when the agent has a shell — and uses the tools when the client has them.
The CLI's environment
Piped, every command prints the API's JSON; exit 1 is a request that failed
and 2 a command typed wrong. The rest is cli.md. The packages
read the same two variables (TRACEPAD_HOST, their first name for the
address, still works and says it is deprecated).
What the skill holds the agent to
Most of the skill is method: start from the trace rather than the
application's logs, read the observation's input before guessing at the
prompt, list the values a filter takes before guessing one. One part is
policy. Every destructive command in Tracepad is a dry run until it is
confirmed (admin.md), and that ceremony
protects against a typo, not against an agent that has decided to delete.
The skill closes the gap: the agent runs the dry run, shows the human what it
would remove, and stops; it adds --yes only on the human's word about that
preview, never on its own initiative. It also never prints or commits a secret
key, and asks for one rather than hunting for it — the narrowest that does the
task: read for looking, all three scopes for running evals. It never mints or
revokes a key; that is a person's act.