Skip to content

trace docs: add hermes and droid #2574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cfahlgren1 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

trace docs: add hermes and droid #2574

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 18 additions & 10 deletions docs/hub/agent-traces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,35 @@
<img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/datasets/agent-traces-preview-dark.webp" alt="Agent trace preview on a dataset page in dark mode."/>
</div>

Agent traces from Claude Code, Codex, and Pi Agent are natively supported on the Hugging Face Hub. Upload the raw JSONL sessions to a [Dataset](https://huggingface.co/datasets?format=format%3Aagent-traces) or a [Storage Bucket](./storage-buckets) to open them in a dedicated trace viewer. Datasets show traces in Data Studio; buckets let you open individual `.jsonl` files directly.
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](https://huggingface.co/datasets?format=format%3Aagent-traces) or a [Storage Bucket](./storage-buckets) to open them in a dedicated trace viewer. Datasets show traces in Data Studio; buckets let you open individual `.jsonl` files directly.

## Find your traces

Each supported agent writes JSONL sessions to the following directories:
Most supported agents write JSONL sessions to local directories:

| Agent | Local session directory |
| ----------- | ----------------------- |
| Claude Code | `~/.claude/projects` |
| Codex | `~/.codex/sessions` |
| Pi | `~/.pi/agent/sessions` |
| Agent | Local 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:

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

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`](https://github.com/badlogic/pi-share-hf) can help collect project sessions, redact known secrets, run TruffleHog and LLM review, and upload only sessions that pass checks.

<Tip>

The easiest way to upload is to ask your agent itself: point it at the directory above and tell it to upload the `.jsonl` files to a Hub dataset or bucket.
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.

Expand All @@ -44,11 +52,11 @@ 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. 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`.
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, and results.
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.

<div class="flex justify-center">
<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/datasets/agent-traces-session.webp" alt="Agent trace session viewer showing user and assistant turns with expanded tool calls."/>
Expand Down
Loading