Logbooks

Trackio logbooks are shareable experiment notebooks for recording the reasoning, commands, results, figures, artifacts (checkpoints, datasets, etc.), and agent traces behind an experiment. A logbook is stored locally in the .trackio/logbook directory of a workspace and can be previewed locally or published as a static Hugging Face Space.

Recommended for coding agents: The easiest way to use Logbooks with coding agents (e.g. Codex, Claude Code, Pi, OpenCode) is to just give your coding agent these instructions:

trackio skills add
trackio logbook open
trackio logbook attach trace <path to current trace>

Work in this workspace's Trackio logbook. Before running any experiment or
script, create or select the relevant page with `trackio logbook page "..."`. Run every experiment command with `trackio logbook run -- <command>` ratherthan invoking it directly, which will log the code and its outputs into the logbook. 

For more specifics and fine-grained control, keep reading!

Start an agent session with a logbook

The easiest way to use a logbook is to create it before the agent starts making changes or running experiments:

trackio logbook open --title "Learning-rate sweep"

This creates the local logbook and opens its preview. Use --no-serve when you only want to create or attach to the local logbook. Use --no-browser to start the preview without opening a browser, or pass --port to select a different port.

Give the agent the Trackio skill

Install the Trackio skill for the coding agent you are using. For Codex:

trackio skills add --codex

The command installs the skill in the project and links it for Codex. Start a new Codex session after installation when necessary so it can load the skill. For another supported agent, replace --codex with its flag, such as --claude, --cursor, --opencode, or --pi.

The skill tells the agent to run code with trackio logbook run -- ... rather than invoking an experiment command directly. That wrapper records the exact command, detected scripts and configuration files, output, exit code, duration, and supported output artifacts. For example:

trackio logbook page "Baseline"
trackio logbook run -- python train.py --learning-rate 0.001

The training script should still use trackio.init(), trackio.log(), and trackio.finish() normally. With a logbook in the workspace, trackio.init() can also add a live dashboard cell for the active Trackio project.

Attach the active session trace

Attach the current coding-agent transcript near the beginning of the session:

trackio logbook attach trace /absolute/path/to/current-session.jsonl --title "Agent session"

The agent runtime determines where its transcript is stored. Find the JSON or JSONL file for the active conversation using that runtime’s session directory, then attach the file whose timestamps and metadata match the session. An active JSONL file can be attached before the session ends; Trackio refreshes it while the local preview is open. Attaching also establishes the Workspace baseline, so later supported model and data files can be associated with the session.

Trackio scrubs common secrets from an attached trace by default. Review traces before publishing because they can still contain prompts, tool inputs, command output, paths, or personal data. Use --no-scrub only for an already-sanitized source.

Create pages as the work develops

Opening a workspace that already contains a logbook attaches to it. The logbook is made up of pages; create or select a page with:

trackio logbook page "Baseline"

Add experiment content

Add Markdown, code, figures, artifacts, or an embedded Trackio dashboard:

trackio logbook cell markdown "Baseline accuracy: 82.4%" --page "Baseline"
trackio logbook cell code --page "Baseline" --code-text "print(metrics)" --language python
trackio logbook cell figure --page "Baseline" --image plots/baseline.png
trackio logbook cell artifact "my-project/model:v1" --page "Baseline" --type model
trackio logbook cell dashboard my-project --page "Baseline"

To run an experiment command and capture its command, output, scripts, and output files in one step:

trackio logbook run --page "Sweep" -- python train.py --learning-rate 0.001

Output model and data files are recorded as artifact cells by default. Pass --no-artifacts to disable that capture.

Read a logbook programmatically

trackio logbook read produces a compact, agent-friendly view. It can read a local workspace, a published Space ID, or a logbook URL:

trackio logbook read
trackio logbook read pages
trackio logbook read page "Baseline"
trackio logbook read --json

Use trackio logbook read cell <cell-id> --full when a cell needs to be inspected in full. The JSON form is useful for automation and coding agents.

Publish a logbook

Publish the current logbook to a Hugging Face Space:

trackio logbook publish username/learning-rate-logbook

Published logbooks are static and read-only. The Space stores references to trace datasets and artifact buckets by default; use --public only when those referenced resources should also be public. Use --private to make the Space private.