Diários de bordo

Os cadernos de experimentos do Trackio são cadernos compartilháveis para registrar o raciocínio, comandos, resultados, figuras, artefatos (checkpoints, conjuntos de dados, etc.) e rastros de agentes por trás de um experimento. Um caderno é armazenado localmente no diretório .trackio/logbook de um workspace e pode ser visualizado localmente ou publicado como um Space estático do Hugging Face.

Recomendado para agentes de codificação: A maneira mais fácil de usar Logbooks com agentes de codificação (por exemplo, Codex, Claude Code, Pi, OpenCode) é simplesmente fornecer a seu agente de codificação estas instruções:

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. 

Para mais detalhes e controle mais granular, continue lendo!

Inicie uma sessão de agente com um diário de bordo

A maneira mais fácil de usar um logbook é criá-lo antes que o agente comece a fazer alterações ou executar experimentos:

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

Isso cria o logbook local e abre sua pré-visualização. Use --no-serve quando você quiser apenas criar ou se conectar ao logbook local. Use --no-browser para iniciar a pré-visualização sem abrir um navegador, ou passe --port para selecionar uma porta diferente.

Dê ao agente a habilidade Trackio

Instale a skill do Trackio para o agente de codificação que você está usando. Para o Codex:

trackio skills add --codex

O comando instala a skill no projeto e a vincula para o Codex. Inicie uma nova sessão do Codex após a instalação, quando necessário, para que ele possa carregar a skill. Para outro agente suportado, substitua --codex pela sua flag, como --claude, --cursor, --opencode ou --pi.

A skill instrui o agente a executar o código com trackio logbook run -- ... em vez de invocar um comando de experimento diretamente. Esse wrapper registra o comando exato, os scripts e arquivos de configuração detectados, a saída, o código de saída, a duração e os artefatos de saída suportados. Por exemplo:

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

O script de treinamento deve continuar usando trackio.init(), trackio.log() e trackio.finish() normalmente. Com um logbook no workspace, trackio.init() também pode adicionar uma célula de dashboard ao vivo para o projeto Trackio ativo.

Anexe o rastro da sessão ativa

Anexe a transcrição do agente de codificação atual perto do início da sessão:

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

O runtime do agente determina onde seu transcript é armazenado. Encontre o arquivo JSON ou JSONL da conversa ativa usando o diretório de sessão desse runtime e, em seguida, anexe o arquivo cujos timestamps e metadados correspondam à sessão. Um arquivo JSONL ativo pode ser anexado antes do término da sessão; o Trackio o atualiza enquanto a pré-visualização local estiver aberta. O anexo também estabelece a linha de base do Workspace, permitindo que arquivos de modelo e dados suportados sejam associados à sessão posteriormente.

O Trackio remove segredos comuns de um trace anexado por padrão. Revise os traces antes de publicá-los, pois eles ainda podem conter prompts, entradas de ferramentas, saída de comandos, caminhos ou dados pessoais. Use --no-scrub apenas para uma fonte já sanitizada.

Crie páginas à medida que o trabalho avança

Abrir um workspace que já contém um logbook faz com que você se conecte a ele. O logbook é composto por páginas; crie ou selecione uma página com:

trackio logbook page "Baseline"

Adicionar conteúdo do experimento

Adicione Markdown, código, figuras, artefatos ou um painel Trackio incorporado:

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"

Para executar um comando de experimento e capturar seu comando, saída, scripts e arquivos de saída em uma única etapa:

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

Os arquivos de modelo e dados de saída são registrados como células de artefato por padrão. Passe --no-artifacts para desabilitar essa captura.

Ler um diário de bordo programaticamente

trackio logbook read produz uma visão compacta e amigável para agentes. Ele pode ler um workspace local, um ID de Space publicado ou uma URL de logbook:

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

Use trackio logbook read cell <cell-id> --full quando uma célula precisar ser inspecionada por completo. O formato JSON é útil para automação e agentes de código.

Publicar um diário de bordo

Publique o logbook atual em um Hugging Face Space:

trackio logbook publish username/learning-rate-logbook

Os diários publicados são estáticos e somente leitura. O Space armazena, por padrão, referências aos conjuntos de dados de rastreamento e aos buckets de artefatos; use --public apenas quando esses recursos referenciados também devem ser públicos. Use --private para tornar o Space privado.