# useTree

`useTree` exposes stable structural query callbacks backed by a session's [`Tree`](https://ably.com/docs/ai-transport/api/javascript/core/client-session.md). The returned methods are thin `useCallback` wrappers around `session.tree` and never trigger re-renders on their own.

Use this hook when you need to inspect tree structure outside the visible branch (for example, to count edit or regenerate siblings on a node before showing navigation arrows). Branch navigation for the currently visible chain lives on [`useView`](https://ably.com/docs/ai-transport/api/react/core/use-view.md).

<Code>

#### Javascript

```
import { useTree } from '@ably/ai-transport/react';

function SiblingSwitcher({ nodeKey }) {
  const { getSiblingNodes } = useTree();
  const siblings = getSiblingNodes(nodeKey);

  if (siblings.length <= 1) return null;
  return <Siblings nodes={siblings} />;
}
```
</Code>

This hook must be used within a [`ClientSessionProvider`](https://ably.com/docs/ai-transport/api/react/core/providers.md#client-session-provider) unless `session` is supplied explicitly.

## Parameters 

<Table id='UseTreeParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| session | optional | A client session to read tree structure from. Defaults to the nearest provider. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |

</Table>

## Returns 

<Table id='TreeHandle'>

| Property | Description | Type |
| --- | --- | --- |
| getRunNode | Get a Run by `runId`, or `undefined` if not found. | <Table id='RunNode'/> |
| getNodeByCodecMessageId | Get the input or run node that owns a given `codecMessageId`, or `undefined` if not observed. Narrow on `kind` (`'input'` or `'run'`) before reading kind-specific fields. | `(codecMessageId) => ConversationNode \| undefined` |
| getSiblingNodes | Get the sibling group for a node key (edit versions for an input node, regenerate siblings for a reply run). Ordered oldest-first by serial; single-element array when the node has no siblings; empty when the key is unknown. | `(key) => ConversationNode[]` |

</Table>

<Table id='RunNode' >

| Property | Description | Type |
| --- | --- | --- |
| kind | Discriminator. Always `'run'`. | `'run'` |
| runId | The Run's unique identifier. Minted by the agent. | String |
| parentCodecMessageId | The codec-message-id of the input node this Run is rooted at (the user prompt the agent replied to). `undefined` for the root Run. | String or Undefined |
| forkOf | The node key of the node this Run replaces, or `undefined` if this Run is not a fork. | String or Undefined |
| regeneratesCodecMessageId | The codec-message-id this Run regenerates, or `undefined` for non-regenerate Runs. | String or Undefined |
| clientId | Identity of the Ably client that started this Run. | String |
| status | Run lifecycle status. `'active'` while streaming, `'suspended'` while paused awaiting input, otherwise the `RunEndReason`. | `'active' \| 'suspended' \| RunEndReason` |
| projection | Per-Run codec projection. Folded by the Tree from every event published under this run-id. | `TProjection` |
| invocationId | The agent-minted `invocationId` observed for this Run, adopted from the `ai-run-start` event. Empty string until run-start arrives, or if the wire didn't carry an invocation-id. | String |
| startSerial | Ably serial of the first observed message tagged with this run-id. | String or Undefined |
| endSerial | Ably serial of the run-end lifecycle event. | String or Undefined |

</Table>

## Look up a Run by id 

`getRunNode(runId: string): RunNode<TProjection> | undefined`

Return the full [`RunNode`](#returns) record for a given `runId`, or `undefined` if the Run has not been observed. Use this when you need fields the View's [`RunInfo`](https://ably.com/docs/ai-transport/api/react/core/use-view.md#returns) does not expose (parent / fork relationships, the raw projection, serials).

## Look up a node by codec-message-id 

`getNodeByCodecMessageId(codecMessageId: string): ConversationNode<TProjection> | undefined`

Resolve the node that owns the given `codecMessageId` through the tree's index. The result is a `ConversationNode` union: an `InputNode` (user prompt) or a `RunNode` (agent reply). Narrow on `kind` (`'input'` or `'run'`) before reading kind-specific fields. Returns `undefined` when the message has not been observed.

## Get sibling nodes 

`getSiblingNodes(key: string): ConversationNode<TProjection>[]`

Return the sibling group the node keyed by `key` belongs to. The key is either a `RunNode.runId` or an `InputNode.codecMessageId`. The two sibling-group shapes are: input edits, where input nodes share a parent and chain via `forkOf` (the original user prompt plus every edit of it); and regenerate siblings, where reply runs share an input-node parent (the original reply plus every regenerate of it).

Ordered oldest-first by serial. Returns a single-element array when the node has no siblings, an empty array when the key is unknown. Narrow each node on `kind` before reading kind-specific fields.

## Example 

A run-history sidebar that lists every observed Run and lights up sibling navigation where alternatives exist.

<Code>

### Javascript

```
import { useTree, useView } from '@ably/ai-transport/react';

function RunHistory() {
  const { messages, runOf } = useView();
  const { getSiblingNodes } = useTree();

  const runs = messages
    .map(({ codecMessageId }) => runOf(codecMessageId))
    .filter((r): r is RunInfo => Boolean(r));

  return (
    <ul>
      {runs.map((run) => {
        const siblings = getSiblingNodes(run.runId);
        return (
          <li key={run.runId}>
            <RunSummary run={run} />
            {siblings.length > 1 && <SiblingPicker siblings={siblings} />}
          </li>
        );
      })}
    </ul>
  );
}
```
</Code>

## Related Topics

- [Providers](https://ably.com/docs/ai-transport/api/react/core/providers.md): API reference for the AI Transport React providers: ClientSessionProvider and the createSessionHooks factory.
- [useClientSession](https://ably.com/docs/ai-transport/api/react/core/use-client-session.md): Read a ClientSession from the nearest ClientSessionProvider in the AI Transport React integration.
- [useView](https://ably.com/docs/ai-transport/api/react/core/use-view.md): Subscribe to a paginated, branch-aware view of the AI Transport conversation tree from React.
- [useCreateView](https://ably.com/docs/ai-transport/api/react/core/use-create-view.md): Create an independent View over the AI Transport conversation tree from React, with its own branch selections and pagination.
- [useAblyMessages](https://ably.com/docs/ai-transport/api/react/core/use-ably-messages.md): Subscribe to raw Ably InboundMessages on the AI Transport channel from React.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.