---
sidebar_position: 5
title: Sessions & artifacts
---

# Sessions & artifacts

Every agent run — local or cloud — produces a **session folder** under `.zibby/output/sessions/<sessionId>/`. The folder is the canonical record of what happened.

## What's inside

```
.zibby/output/sessions/1777678254943_ymcw/
├── result.json              # final structured output (Zod-validated)
├── raw_stream_output.txt    # every byte the agent emitted, raw
├── events.json              # JSONL execution log: per-node start/end, validation, retries
├── .session-info.json       # session metadata (start time, agent, model, workflow type)
└── nodes/
    ├── plan/
    │   ├── prompt.txt         # exact prompt sent to the agent
    │   ├── raw_output.txt     # what the agent returned, pre-validation
    │   └── result.json        # the validated output
    ├── implement/...
    └── verify/...
```

## Session IDs

Format: `<unix_ms>_<random>`. Generated when the graph starts running.

You can override via:

```bash
zibby agent run my-agent --session 1777678254943_ymcw
```

Useful for replay — re-run from a saved input/state without re-paying earlier nodes.

## Replay a session

```bash
zibby agent run my-agent \
  --session 1777678254943_ymcw \
  --node verify   # only re-run the 'verify' node
```

The graph reads `state.plan` and `state.implement` from the saved session and only invokes `verify` again. Cheap iteration on the last node when debugging.

## Cloud sessions

Cloud runs land in the same `.zibby/output/sessions/` layout, just inside the ECS container's `/workspace/`. The session folder is uploaded to S3 at the end of each run; `zibby agent logs <uuid> -t` streams CloudWatch logs in real time.

To download a finished cloud session locally:

```bash
zibby agent download <uuid>
```

This pulls the agent source (so you can edit and redeploy) plus the most recent execution's session folder.

## Studio integration

[Zibby Studio](https://zibby.app) is a desktop UI that watches `.zibby/output/sessions/`. Anything that writes a session folder shows up in Studio automatically — pin a session, watch state evolve live, or stop an agent from the Stop button.

The protocol is documented and stable:

- `__WORKFLOW_GRAPH_LOG__` markers in stdout signal node begin/end events
- `.zibby-studio-stop` file is the kill switch — Studio writes it, the runtime checks for it between nodes
- `ZIBBY_RUN_SOURCE=studio` env var tells the runtime "you were spawned by Studio"
- `stoppedByStudio: true` returned from `graph.run()` when the kill switch fired