Skip to navigation
Getting StartedQuick StartsAgent Harnesses

Claude Code Quick Start

View as Markdown

Goal

Run one local Claude Code session through NeMo Relay and write its turn, model, and tool lifecycle to a local Agent Trajectory Observability Format (ATOF) file.

Trial configuration

This guide uses disposable local files and wrapped execution to try Relay for one run. It is a trial configuration, not an ongoing deployment setup.

For regular use

For personal use, configure user or system settings and follow the agent’s persistent integration setup.

For administrator-managed deployments, use daemon mode for a shared service and centrally managed configuration.

Use the event relationships to follow model and tool work through a run and check where the expected activity occurred.

Prerequisites

Before you start, make sure you have:

On Unix, the verification step also uses jq 1.6 or newer; check your version with jq --version. PowerShell uses its built-in JSON parser.

Use Claude Code’s configured model; Relay does not select or require one. For example, authenticate with claude auth login, or set ANTHROPIC_API_KEY for API-key access. A custom gateway must provide the Anthropic Messages API; configure its credentials, base URL, and model in Claude Code before wrapping the run. Also add an [upstream] section with anthropic_base_url = "https://YOUR_GATEWAY" to the Relay config.toml below; Relay replaces ANTHROPIC_BASE_URL with its local gateway address. Use your provider’s API root, without the /v1/messages route. Refer to Claude Code authentication.

1

Install

Install the NeMo Relay CLI version for these docs:

curl -fsSL https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.sh | NEMO_RELAY_VERSION=0.11.0 sh
export PATH="$HOME/.local/bin:$PATH"
2

Configure

Create a disposable working directory and make sure the agent can write files there:

mkdir relay-claude-code-quickstart
cd relay-claude-code-quickstart

Save the following files and run the remaining commands from this directory.

Save this file as config.toml in the directory where you will run the agent:

config.toml
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
[agents.claude]
command = "claude"

The agent entry in config.toml tells Relay which executable to launch. Save this sibling file as plugins.toml to enable ATOF export to logs/events.jsonl:

plugins.toml
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
version = 1
[policy]
unknown_component = "error"
unknown_field = "error"
unsupported_value = "error"
[[components]]
kind = "observability"
enabled = true
[components.config]
version = 4
enable_full_payloads = false
[components.config.atof]
enabled = true
[[components.config.atof.sinks]]
type = "file"
output_directory = "logs"
filename = "events.jsonl"
mode = "overwrite"

ATOF output can contain sensitive prompts, responses, tool arguments, and tool results. Protect logs/events.jsonl even when full payload export is disabled.

3

Run

The prompt asks the agent to create a known file so you can distinguish a successful tool action from an ordinary text reply. Relay records the turn, model calls, and tool activity while the agent completes the task.

From the directory containing both files, clear the previous example outputs and run the validation prompt:

rm -f -- relay-check.txt logs/events.jsonl &&
nemo-relay --config "$PWD/config.toml" claude -- -p "Use the Write tool to create relay-check.txt in the current working directory containing exactly RELAY_QUICKSTART_TOOL_OK. Then reply with RELAY_QUICKSTART_RESPONSE_OK." --allowedTools Write

The allowed-tools option approves the Write tool for this invocation, so it can create the marker without a permission prompt. Run this only in your disposable trusted directory.

To choose a model for this invocation, add Claude Code’s --model option after --, for example --model sonnet. Use a model or alias your provider supports.

Relay starts a temporary local gateway and injects Claude Code hooks for this run. It does not modify your persistent Claude Code plugin configuration.

4

Verify

The tool marker proves that the agent created the requested file. The event marker proves that Relay recorded matching start/end records for the required turn or agent, tool, and model work. The response marker is the agent’s reply; it is checked separately from the captured lifecycle.

The verification command prints RELAY_QUICKSTART_TOOL_OK and RELAY_QUICKSTART_EVENTS_OK.

Run the verification checks

After the session exits, confirm that Relay wrote the local event stream:

jq -eRs 'gsub("^\\s+|\\s+$"; "") == "RELAY_QUICKSTART_TOOL_OK"' relay-check.txt > /dev/null &&
jq -se '
  . as $events |
  def closed($category):
    any($events[]; . as $end_event |
      .kind == "scope" and .scope_category == "end" and
      .category == $category and
      ($category != "custom" or .name == "claude-code-turn") and
      any($events[]; .kind == "scope" and .scope_category == "start" and
        .uuid == $end_event.uuid and .name == $end_event.name and
        .category == $end_event.category and .parent_uuid == $end_event.parent_uuid));
  length > 0 and
  all(.[]; .atof_version == "0.1" and (.kind == "scope" or .kind == "mark")) and
  closed("custom") and closed("tool") and closed("llm")
' logs/events.jsonl > /dev/null &&
printf 'RELAY_QUICKSTART_TOOL_OK\nRELAY_QUICKSTART_EVENTS_OK\n'

The verification command prints the following output when its checks pass:

RELAY_QUICKSTART_TOOL_OK
RELAY_QUICKSTART_EVENTS_OK

The agent’s final reply should include RELAY_QUICKSTART_RESPONSE_OK; its surrounding wording can vary.

The verification markers confirm the tool-created file and matching start/end records for custom turn, tool, and LLM work.

Inspect the Recorded Activity

Read the completed model calls from the same event file:

jq 'select(.kind == "scope" and .scope_category == "end" and .category == "llm") |
  {name, category, category_profile, uuid, parent_uuid, timestamp, metadata}' logs/events.jsonl

category and name identify the recorded work. The same uuid pairs its start and end records; parent_uuid connects it to its enclosing scope. timestamp records when this event occurred. For model calls, category_profile and metadata can include the model identity and completion status, depending on the integration. These fields let you follow a call through the run without requiring full prompt or response capture.

For More Details

For more details, refer to: