| name | add-agenttrace |
| description | Add live agent activity traces (tools, tasks, reasoning summaries, silence keepalives) via nanoclaw-agenttrace and nanoclaw-hosthooks. |
/add-agenttrace — Live Agent Activity Trace
Surfaces what the agent is doing during long turns — tools, task progress, optional reasoning summaries, and silence keepalives — without polluting chat history on rich channels.
Addresses nanocoai/nanoclaw#1440. Does not implement deep-session mode (#1686).
See also: QUICKSTART.md in the npm package.
Prerequisites
- Working NanoClaw v2 install with
pnpm
- Node.js ≥ 20 (22 recommended)
nanoclaw-hosthooks API v1 installed in the host and runner- Container rebuilt after installing hosthooks
Architecture
Claude SDK → agenttrace observe (container)
↓
messages_out system action
↓
host delivery action → channel (timeline | edit status | typing)
Recipe order
/add-webchat # optional — richest timeline UI
/add-agenttrace # this skill
Install
Pre-flight (idempotent)
Skip to Enable if all of these are already in place:
src/agenttrace-boot.ts existscontainer/agent-runner/src/agenttrace/observe.ts existssrc/index.ts contains await startAgentTrace()src/hosthooks.ts and container/agent-runner/src/hosthooks.ts expose API v1nanoclaw-agenttrace is listed in package.json
Otherwise continue. Every step is safe to re-run.
0. Sync this skill (first time only)
pnpm exec nanoclaw-agenttrace sync-skill
1. Install npm package
pnpm add nanoclaw-agenttrace@0.1.0
Local peer monorepo:
pnpm add file:../nanoclaw-agenttrace
2. Run the installer
pnpm exec nanoclaw-agenttrace install
This will:
- Copy host adapter sources into
src/agenttrace-*.ts
- Copy runner modules into
container/agent-runner/src/agenttrace/
- Insert the host
startAgentTrace() boot block and runner registration import
- Register Claude observation, partial/summarized-thinking options, inbound
turn boundaries, and container environment forwarding through hosthooks
- Scaffold
.env keys (AGENTTRACE_ENABLED=false by default)
- Sync this skill to
.claude/skills/add-agenttrace/
The installer fails clearly when hosthooks API v1 or its call sites are
missing. Install nanoclaw-hosthooks first and rebuild the container.
3. Enable
In .env:
AGENTTRACE_ENABLED=true
AGENTTRACE_DEFAULT_VISIBILITY=trace
AGENTTRACE_SILENCE_KEEPALIVE=true
4. Build, rebuild container, verify
pnpm run build
./container/build.sh
pnpm exec nanoclaw-agenttrace verify
Run host wiring test when present:
pnpm exec vitest run src/agenttrace-wiring.test.ts src/agenttrace-config.test.ts src/agenttrace-dispatch.test.ts
5. Webchat companion (optional)
If nanoclaw-webchat is installed, upgrade it to ≥ 0.3.1 (implements publishActivity + activity WebSocket events) for the collapsible timeline:
pnpm webchat:local
Typing continues to work as a floor signal even without the timeline.
Uninstall
See REMOVE.md.
Visibility levels
| Value | Shows |
|---|
off | Nothing |
status | Tools / tasks / keepalives (no reasoning or partial text) |
trace (default) | Status + partial text + Anthropic summarized reasoning |
trace_reasoning | Alias of trace (compat; no raw CoT mode — API does not expose raw CoT) |
trace_full | Everything in trace plus secret-scanned tool inputs/results and subagent transcripts |
trace_full payloads are secret-scanned (@sanity-labs/secret-scan, pattern-based) — credential-shaped strings are stripped, but PII, internal URLs, file paths, and proprietary content pass through truncated. Enable only where that content is acceptable on the timeline.
Host default: AGENTTRACE_DEFAULT_VISIBILITY. Per-group override (container env / config blob): activity_visibility or AGENTTRACE_VISIBILITY at spawn — no trunk CRUD change required if you set it in the group's container config JSON.
Retention
Bounded per session: max 200 events/turn (500 under trace_full), ~4 KiB/event summary, prune oldest activity rows beyond 50 turns. Activity never replaces the final chat reply.
