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

# ProvenanceTracker

> A real-time session feed that displays actions as they are recorded.

> Polls `pk.sessionProvenance()` and displays a live feed of recorded actions with a timeline UI. Ideal for chat apps and multi-step AI workflows where you want users to see provenance building in real time.

<Tabs>
  <Tab title="Preview">
    <Frame>
      <iframe src="https://ui-preview.provenancekit.com/tracker" style={{ width: "100%", height: "480px", border: "none", borderRadius: "8px" }} title="ProvenanceTracker preview" />
    </Frame>
  </Tab>

  <Tab title="Code">
    ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark"}}
    import { ProvenanceTracker } from "@provenancekit/ui";

    // Auto-polls by sessionId — shows new actions as they arrive
    <ProvenanceTracker
      sessionId="research-session-a1b2c3"
      pollInterval={3000}
      onNewAction={(action) => {
        console.log("New action:", action.type, action.id);
      }}
    />

    // Headless mode — pass session directly (no polling)
    <ProvenanceTracker session={mySession} maxActions={10} />
    ```
  </Tab>
</Tabs>

## What the preview shows

The tracker is loaded with a **6-step AI research workflow** session:

| Step           | Type        | Performer                                 | Description                            |
| -------------- | ----------- | ----------------------------------------- | -------------------------------------- |
| Upload sources | `create`    | Sarah Kim (human)                         | Source documents uploaded              |
| Synthesise     | `transform` | Research Assistant (AI · Claude Opus 4.6) | Extracts key facts from sources        |
| Draft summary  | `create`    | Research Assistant (AI · Claude Opus 4.6) | Writes the initial report draft        |
| Generate chart | `create`    | Research Assistant (AI · GPT-4o)          | Produces a supporting data chart       |
| Revise         | `transform` | Sarah Kim (human)                         | Human edits and refinements            |
| Finalise       | `verify`    | Research Assistant (AI · Claude Opus 4.6) | Combines and verifies the final report |

Each action item shows:

* **Action type chip** (create / transform / verify)
* **Latest badge** on the most recent action
* **AI tool badge** (violet) when `ext:ai@1.0.0` is present
* **Verified badge** (green) when `ext:verification@1.0.0` status is `"verified"`
* Relative timestamp

The session header shows live stats: total actions, resources, and entities recorded.

## Props

| Prop           | Type                       | Default | Description                           |
| -------------- | -------------------------- | ------- | ------------------------------------- |
| `sessionId`    | `string`                   | —       | Session ID to poll                    |
| `pollInterval` | `number`                   | `3000`  | Polling interval in milliseconds      |
| `session`      | `SessionProvenance`        | —       | Headless mode — pass session directly |
| `maxActions`   | `number`                   | `20`    | Maximum number of actions to display  |
| `onNewAction`  | `(action: Action) => void` | —       | Called when a new action is detected  |
| `className`    | `string`                   | —       | Additional CSS class                  |

## Common pattern — chat apps

```tsx theme={"theme":{"light":"github-dark","dark":"github-dark"}}
// Start a session when the conversation begins
const session = await pk.startSession({ label: "user-chat-123" });

// After each AI response, record an action
await pk.record({
  action: {
    type: "create",
    performedBy: "your-ai-entity-id",
    extensions: {
      "ext:ai@1.0.0": {
        provider: "anthropic",
        model: "claude-opus-4-6",
        autonomyLevel: "assistive",
        tokensUsed: response.usage.totalTokens,
      },
    },
  },
  sessionId: session.sessionId,
});

// Show the live feed in the UI
<ProvenanceTracker
  sessionId={session.sessionId}
  pollInterval={2000}
/>
```