Hub documentation

Agent Traces

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Agent Traces

Agent trace preview on a dataset page in light mode.

Agent traces from Claude Code, Codex, Pi, Hermes Agent, and Factory Droid are natively supported on the Hugging Face Hub. Upload the raw JSONL sessions to a Dataset or a Storage Bucket to open them in a dedicated trace viewer. Datasets show traces in Data Studio; buckets let you open individual .jsonl files directly.

Requests routed through OpenRouter can also be exported straight to a bucket and opened in the same viewer, see OpenRouter Broadcast traces.

Find your traces

Most supported agents write JSONL sessions to local directories:

AgentLocal session directory
Claude Code~/.claude/projects
Codex~/.codex/sessions
Codex archive~/.codex/archived_sessions
Factory/Droid~/.factory/sessions
Pi~/.pi/agent/sessions

These trace files are supported out of the box, so you can upload them without modifying or converting them first.

Hermes Agent stores current sessions in its session database. Export the sessions you want to share as JSONL before uploading:

hermes sessions export session.jsonl --session-id <session_id>

Are you building your own harness? If your agent isn’t listed above, you can make its sessions render in the trace viewer by emitting the Session Traces Format.

Trace files can include prompts, tool inputs, command output, local paths, screenshots, secrets, private code, and personal data. Review and redact traces before publishing them publicly, or keep the dataset or bucket private if you are not sure what is inside.

For Pi Agent sessions, pi-share-hf can help collect project sessions, redact known secrets, run TruffleHog and LLM review, and upload only sessions that pass checks.

The easiest way to upload is to ask your agent itself: point it at the directory or exported JSONL file above and tell it to upload the .jsonl files to a Hub dataset or bucket.

Buckets are especially useful if you want to keep syncing traces as new sessions land.

Upload your traces

After creating a dataset or bucket, install the hf CLI with the recommended standalone installer and log in. The installer also sets up the Hugging Face CLI Skill, so your coding agent can run hf commands for you.

curl -LsSf https://hf.co/cli/install.sh | bash
hf auth login

hf upload <username>/<dataset-name> ~/.codex/sessions . --repo-type dataset
hf buckets sync ~/.codex/sessions hf://buckets/<username>/<bucket-name>/codex

Replace ~/.codex/sessions with the matching session directory for your agent, or with a directory containing JSONL files exported from Hermes Agent. Use hf upload for datasets and hf buckets sync for buckets you want to update as new traces are written. The shorter hf sync command is an alias for hf buckets sync.

View your traces

Once you have traces in a dataset, open Data Studio and click a row. For traces in a Storage Bucket, navigate to the .jsonl file you want to inspect and open it. The trace viewer shows the session timeline, prompts, assistant messages, tool calls, shell output, reasoning blocks, and results.

Agent trace session viewer showing user and assistant turns with expanded tool calls.

For a public example, open TeichAI/DeepSeek-v4-Pro-Agent. You can also browse more datasets tagged as traces.

OpenRouter Broadcast traces

OpenRouter Broadcast can send traces of the requests you route through OpenRouter to a Storage Bucket, and the Hub opens those files in the trace viewer. Nothing changes in your app or agent, so it works for anything that goes through OpenRouter: Claude Code or Codex pointed at OpenRouter, OpenCode, or a plain chat-completions app.

To set it up, create a bucket, generate S3 credentials from a token with write access to it, and add Hugging Face Storage Buckets as a destination under Settings > Observability in OpenRouter. OpenRouter’s Hugging Face Storage Buckets guide has the full steps.

Create the bucket as private:

hf buckets create <username>/openrouter-traces --private

The files hold full prompts, system prompts, and tool output such as file paths and shell output, along with your OpenRouter account and user IDs and the name of the API key. OpenRouter’s guide doesn’t cover bucket visibility, and anyone can read a public bucket.

Each trace is saved as a separate JSON file named {traceId}-{timestamp}.json. With the default path template, openrouter-traces/{date}, they land in a folder per day:

openrouter-traces/<date>/gen-<unix>-<id>-<timestamp>.json

A trace is one model request, not a whole session. A single agent turn usually makes several model requests, so a three-turn session can produce around ten files. Each file contains the conversation up to that request, which means the last file of a session holds the whole session. Files from the same session share the same trace.sessionId.

Open any of these .json files in the bucket to see it as an OpenRouter trace, with a toggle between the trace view and the raw JSON. The viewer shows the messages, tool calls and results, the model, token counts (including cached tokens), and cost. The cost in the footer is for that one request, not for the session.

Two things to know when reading these traces:

  • Images are not stored. OpenRouter strips multimodal content from the messages before exporting, and the viewer shows [image] in its place.
  • Some requests may be missing or have no content. OpenRouter’s sampling rate and API key filters limit which requests are sent to a destination, and Privacy Mode removes the prompt and completion content.
Update on GitHub