Skip to content
Nexus Docs
↑↓Navigate↵SelectescClose

Claude Code session checklist

Manually verify Claude Code sessions, tool use, error handling, and observability

Last updated on:

Use this checklist after the scripted pytest battery passes. Capture raw SSE transcripts when triaging protocol failures.

Prerequisites

Section titled “Prerequisites”
  • Nexus dev stack running with a valid NEXUS_API_KEY
  • Claude Code installed locally
  • ANTHROPIC_BASE_URL=http://127.0.0.1:14450/anthropic
  • Registry contains the model you will select in Claude Code

Launch modes

Section titled “Launch modes”

Run the full session twice, once with each credential mode:

  1. ANTHROPIC_AUTH_TOKEN=nxs_... (unset ANTHROPIC_API_KEY)
  2. ANTHROPIC_API_KEY=nxs_... (unset ANTHROPIC_AUTH_TOKEN)

Session script

Section titled “Session script”

For each launch mode:

  1. Start a new Claude Code session against nexus.
  2. Ask it to read a small file in the workspace, propose an edit, and explain the change.
  3. Accept a tool call that runs a harmless shell command (pwd or ls).
  4. Ask a follow-up question that requires context from the prior turn.
  5. Enable extended thinking (if your model supports it) and ask a reasoning question; continue one more turn reusing the signed thinking block.
  6. Start a second session turn with a long cached system preamble (repeat a paragraph ~200 times with prompt caching enabled in Claude Code settings, when available).
  7. Invoke token counting if exposed in the client UI or via a short prompt that triggers count_tokens.

Pass criteria

Section titled “Pass criteria”

Record a result for each criterion in your run report. These are expected outcomes, not a certification result for the current version.

Area Expected outcome
Protocol No protocol errors, silent retries, or session aborts
Streaming Visible assistant text completes successfully
Tools Tool identifiers correlate across tool_use and tool_result turns
Conversation Session resume recalls prior-turn context
Caching Cached calls show cache_read_input_tokens in Nexus request analytics
Analytics Each request includes usage, cost, cache tokens, and an attempt trail
Invalid credentials An invalid Nexus key produces an Anthropic-shaped authentication error without crashing the client
Unknown model An unknown model identifier produces an Anthropic-shaped client error without crashing Claude Code

Conditional checks

Section titled “Conditional checks”
  • Extended thinking: Verify replay on a follow-up turn with a thinking-enabled upstream. Record a skipped result and the reason if the selected model does not support it.
  • API-key launch mode: Complete Claude Code’s interactive approval for ANTHROPIC_API_KEY, then run the session using x-api-key authentication. Integration-suite coverage of the header does not replace this interactive check.

Error-path spot checks

Section titled “Error-path spot checks”
Scenario Expected client behavior
Invalid nxs_... key Authentication error message; no crash
Unknown model id Invalid-request style error; no crash
Upstream overload (529) Overloaded error with retry guidance
Upstream rate limit (429) Rate-limit error with retry guidance
Unknown /anthropic/* path (e.g. telemetry probe) 404 with Anthropic error envelope

Artifact storage

Section titled “Artifact storage”

Archive Claude Code transcripts alongside certification runs under test-suite/compat/reports/claude-code/ with a timestamp and launch mode in the filename.

Record the Nexus commit, Claude Code version, model, credential mode, and pass/fail/skipped results. This directory is ignored by Git, so retain the evidence with your certification artifacts.