Context Dumping

The /dumpcontext command captures complete API request/response data for debugging provider interactions. Dumps are saved in OpenAI-compliant JSON format, making them easy to replay with curl or analyze for troubleshooting.

Quick Start

# In an interactive session, immediately dump the current conversation context
/dumpcontext now

# Enable dumping for every request in the session (foreground and subagents)
/dumpcontext on

# Enable dumping only when errors occur (foreground and subagents)
/dumpcontext error

# Check current status
/dumpcontext status

# Disable dumping
/dumpcontext off

Command Options

Mode	Description
`now`	Dump the current conversation context immediately (no model request is sent)
`status`	Show current dump status (default)
`on`	Dump context before every request in the session (foreground and subagent requests)
`error`	Dump context only when errors occur in the session (foreground and subagent requests)
`off`	Disable context dumping for the session (foreground and subagent requests)

Session-Wide Scope

The transport modes (on, error, off) are session-wide. After you run /dumpcontext on, every subsequent provider request in the current session is dumped — including requests made by subagents launched via the task tool. This is essential for debugging subagent orchestration, prompts, provider behavior, and tool calls.

A mode change affects the next provider invocation from both foreground and already-created subagent runtimes.
An invocation that is already in flight retains its own immutable settings snapshot and is unaffected by a mid-request mode change.
/dumpcontext status reports the current effective mode (the value consumed by both foreground and subagent requests), but does not indicate whether the mode originates from a session override or a profile-local fallback.
If a subagent's own profile specifies dumpcontext, the session value takes precedence — including session off overriding a profile-local on.
A brand-new session starts with no inherited dump mode.

/dumpcontext now is a separate immediate operation: it dumps the current foreground conversation history to disk right away and does not change the session-wide transport mode.

Dump Location

Dumps are saved to <cache>/dumps/ (see Application Directories) with filenames in the format:

YYYYMMDD-HHMMSS-<provider>-<random>.json

Example: 20251208-183505-openai-asq1d9.json

Dump File Structure

Each dump file contains the complete HTTP request and response:

{
  "provider": "openai",
  "timestamp": "2025-12-08T18:35:05.039Z",
  "request": {
    "url": "https://api.openai.com/v1/chat/completions",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "llxprt-code"
    },
    "body": {
      "model": "gpt-5.5",
      "messages": [...],
      "tools": [...],
      "stream": false,
      "tool_choice": "auto",
      "temperature": 1
    }
  },
  "response": {
    "status": 200,
    "headers": {...},
    "body": {...}
  }
}

Note: The Authorization header is intentionally omitted from dumps for security.

Using Dumps with curl

Dumps are OpenAI API compliant and can be replayed with curl. Since the dump includes metadata alongside the request body, extract the body first:

Extract and Send Request

# Linux example: LLXPRT_CACHE_HOME -> LLXPRT_CONFIG_HOME -> Linux default.
# See Application Directories for the macOS and Windows defaults.
DUMPS="${LLXPRT_CACHE_HOME:-${LLXPRT_CONFIG_HOME:-$HOME/.cache/llxprt-code}}/dumps"
jq '.request.body' "$DUMPS/YOUR_DUMP.json" > /tmp/body.json

curl -X POST "$(jq -r '.request.url' "$DUMPS/YOUR_DUMP.json")" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d @/tmp/body.json

One-liner Alternative

# Pipe the body directly to curl
jq '.request.body' "$DUMPS/YOUR_DUMP.json" | \
  curl -X POST "https://api.openai.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d @-

Using with Different Providers

For OpenAI-compatible providers (like local models or alternative endpoints):

# Extract URL from dump and use with custom auth
DUMP="$DUMPS/YOUR_DUMP.json"
jq '.request.body' "$DUMP" | \
  curl -X POST "$(jq -r '.request.url' "$DUMP")" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $YOUR_API_KEY" \
    -d @-

Analyzing Dumps

View Request Summary

# Show provider, model, and message count
jq '{
  provider: .provider,
  model: .request.body.model,
  message_count: (.request.body.messages | length),
  tool_count: (.request.body.tools | length),
  response_status: .response.status
}' "$DUMPS/YOUR_DUMP.json"

Extract Conversation History

# Show messages with roles
jq '.request.body.messages[] | {role, content: .content[:100]}' "$DUMPS/YOUR_DUMP.json"

List Available Tools

# Show tool names and descriptions
jq '.request.body.tools[] | {name: .function.name, description: .function.description[:50]}' "$DUMPS/YOUR_DUMP.json"

Check Response Details

# Show response finish reason and token usage
jq '{
  finish_reason: .response.body.choices[0].finish_reason,
  usage: .response.body.usage
}' "$DUMPS/YOUR_DUMP.json"

Use Cases

Debugging API Issues

When encountering unexpected behavior:

Enable dumping: /dumpcontext on
Reproduce the issue
Disable dumping: /dumpcontext off
Analyze the dump to see exactly what was sent/received

Comparing Provider Responses

Capture the same prompt across different providers to compare:

Run with provider A, dump enabled
Switch providers: /provider openai
Run same prompt with provider B
Compare the dump files

Reporting Bugs

Include relevant dump files (with sensitive data redacted) when reporting provider-related bugs. The dumps show exactly what LLxprt sent and what the API returned.

Testing API Compatibility

Use dumps to verify that OpenAI-compatible providers handle requests correctly:

# Replay a known-good request against a new endpoint
jq '.request.body' dump.json | \
  curl -X POST "http://localhost:1234/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -d @-

Combining with Debug Logging

For comprehensive debugging, combine context dumping with debug logging:

# Enable both debug logging and context dumping
llxprt --debug llxprt:*

# In session
/dumpcontext on

This gives you:

Debug logs: Internal application flow and timing
Context dumps: Exact API payloads and responses

See Debug Logging for more information.

Security Considerations

Authorization headers are never included in dumps
Dumps may contain sensitive conversation content
When on or error mode is active, dumps may also include subagent prompts, conversation history, and tool-call data (including tool arguments and results), which can be especially sensitive
Store dumps securely and clean up when no longer needed
Consider redacting sensitive data before sharing dumps

# Clean up old dumps. This Linux example honors LLXPRT_CACHE_HOME, then
# LLXPRT_CONFIG_HOME, then the Linux default; see Application Directories for
# the macOS and Windows defaults.
CACHE_DIR="${LLXPRT_CACHE_HOME:-${LLXPRT_CONFIG_HOME:-$HOME/.cache/llxprt-code}}"
rm -f "${CACHE_DIR}/dumps/"*.json

# Or keep only recent dumps
find "${CACHE_DIR}/dumps" -name "*.json" -mtime +7 -delete