> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Show Live Diffs

> Render an agent branch as a live diff and refresh the view when a new state arrives.

Render an agent's work from its ephemeral branch while the agent runs. Your product can show current
and prior states without a second file store or diff service.

This guide uses the branch layout from [Capture Agent State](https://code.storage/docs/guides/capture-agent-state.md).

## Read the current diff

Compare the session branch with its normal base branch.

Set `PIERRE_ORG` and `PIERRE_PRIVATE_KEY` as shown in the
[Quick Start](https://code.storage/docs/getting-started/quick-start.md).

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
import { Pierre } from '@pierre/sdk';

const sessionId = process.env.SESSION_ID;

const pierre = new Pierre(); // reads PIERRE_ORG and PIERRE_PRIVATE_KEY

const repoName = 'acme/storefront';
const repo = await pierre.repos.get({ repo_name: repoName });

const sessionBranch = `sessions/${sessionId}`;

const view = await pierre.repos.diff.get({
  repo_name: repoName,
  base_ref: repo.default_branch,
  ref: sessionBranch,
  ref_is_ephemeral: true,
});

console.log(view.stats);
console.log(view.files);
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
import os

from pierre import Pierre

session_id = os.environ["SESSION_ID"]

pierre = Pierre()  # reads PIERRE_ORG and PIERRE_PRIVATE_KEY

repo_name = "acme/storefront"
repo = pierre.repos.get(repo_name=repo_name)

session_branch = f"sessions/{session_id}"

view = pierre.repos.diff.get(
    repo_name=repo_name,
    base_ref=repo["default_branch"],
    ref=session_branch,
    ref_is_ephemeral=True,
)

print(view["stats"])
print(view["files"])
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
import (
	"context"
	"fmt"
	"os"

	pierre "github.com/pierrecomputer/sdk/go"
)

sessionID := os.Getenv("SESSION_ID")

ctx := context.Background()
client, err := pierre.NewClient() // reads PIERRE_ORG and PIERRE_PRIVATE_KEY
if err != nil {
	return err
}

repoName := "acme/storefront"
repo, err := client.Repos.Get(ctx, pierre.ReposGetParams{RepoName: repoName})
if err != nil {
	return err
}

sessionBranch := fmt.Sprintf("sessions/%s", sessionID)
view, err := client.Repos.Diff.Get(ctx, pierre.ReposDiffGetParams{
	RepoName:       repoName,
	BaseRef:        pierre.String(repo.DefaultBranch),
	Ref:            pierre.String(sessionBranch),
	RefIsEphemeral: pierre.Bool(true),
})
if err != nil {
	return err
}

fmt.Println(view.Stats)
fmt.Println(view.Files)
```

`view.files` contains the file changes and diff text. `view.stats` contains the file, line, and
change totals.

Pass `path` to [`repos.diff.get`](https://code.storage/docs/api/repos/diff-get) to filter the response to selected paths.

## Read one file

Use the session branch for the latest content, or use a commit SHA for a fixed view.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const response = await pierre.repos.files.get({
  repo_name: repoName,
  ephemeral: true,
  path: 'src/auth.ts',
  ref: sessionBranch,
});

const source = await response.text();
console.log(source);
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
response = pierre.repos.files.get(
    repo_name=repo_name,
    ephemeral=True,
    path="src/auth.ts",
    ref=session_branch,
)

source = response.read().decode()
response.close()
print(source)
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
import "io"

response, err := client.Repos.Files.Get(ctx, pierre.ReposFilesGetParams{
	RepoName:  repoName,
	Ephemeral: pierre.Bool(true),
	Path:      "src/auth.ts",
	Ref:       pierre.String(sessionBranch),
})
if err != nil {
	return err
}
defer response.Close()

source, err := io.ReadAll(response)
if err != nil {
	return err
}
fmt.Println(string(source))
```

For a fixed review link, store the state SHA and pass it as `ref`. The same SHA can also select a
commit diff.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const stateSha = '4f53cda18c2baa0c0354bb5f9a3ecbe5f6b3f858';
const baseSha = '081b0449cdb51a6fd5c495e7fa329119b3a5dc26';

const fixedDiff = await pierre.repos.diff.get({
  repo_name: repoName,
  base_ref: baseSha,
  ref: stateSha,
});

console.log(fixedDiff.stats);
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
state_sha = "4f53cda18c2baa0c0354bb5f9a3ecbe5f6b3f858"
base_sha = "081b0449cdb51a6fd5c495e7fa329119b3a5dc26"

fixed_diff = pierre.repos.diff.get(
    repo_name=repo_name,
    base_ref=base_sha,
    ref=state_sha,
)

print(fixed_diff["stats"])
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
stateSHA := "4f53cda18c2baa0c0354bb5f9a3ecbe5f6b3f858"
baseSHA := "081b0449cdb51a6fd5c495e7fa329119b3a5dc26"

fixedDiff, err := client.Repos.Diff.Get(ctx, pierre.ReposDiffGetParams{
	RepoName: repoName,
	BaseRef:  pierre.String(baseSHA),
	Ref:      pierre.String(stateSHA),
})
if err != nil {
	return err
}

fmt.Println(fixedDiff.Stats)
```

## Refresh after each state

Use either of these refresh signals:

1. Poll the session branch tip, then reload the diff when the SHA changes.
2. Subscribe to `push` webhooks, validate each delivery, and reload the diff for the same repository
   and branch.

Treat the webhook as a signal. Read the branch again after each event. Do not use the event as your
state store.

See [Webhooks](https://code.storage/docs/repos/webhooks.md) for subscriptions, signatures, and retries.

## Keep credentials on the server

Call Code Storage from your backend. Do not send your organization private key or a write token to
the browser.

Cache a diff by its head SHA when many viewers request the same state. A new state gets a new SHA
and a new cache key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.