---
title: "Work with sessions Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/concepts/sessions
---

# Work with sessions

Every agent interaction is a session — a sequence of messages exchanged between the user, the LLM, and tool results. Sessions let you inspect, resume, and persist conversations, while the TypeScript SDK can also detect concurrent local agents in the same workspace.

## Working with Sessions

Sessions are created automatically by the `Runner` and contain the full conversation history.

## Session Attributes

A `Session` has these attributes:

-   `id` — auto-generated unique identifier (e.g., `session-20250407-143022-123456`)
-   `messages` — list of `Message` objects in chronological order
-   `working_directory` — the directory relative paths resolve to (default `.`)
-   `created_at` — when the session was created

## Coordinate concurrent TypeScript sessions

The TypeScript SDK can observe other Autohand sessions working in the same local workspace and warn about likely Git, file-claim, or repository-drift conflicts. This is local-machine coordination, not a remote lock service.

``` typescript
import { Agent } from '@autohandai/agent-sdk';

const agent = await Agent.create({
  cwd: '/path/to/project',
  sessions: { awareness: 'coordinate' },
});

try {
  const peers = await agent.getSessionPeers();
  console.log(peers);
} finally {
  await agent.close();
}
```

| Tier | Behavior | Use it when |
|---|---|---|
| passive | Publishes activity and reports peer presence. | Your host wants visibility but applies its own policy. |
| warn (default) | Adds advisory warnings for likely Git conflicts, path overlap, and repository drift. | You want safe guidance without an approval pause. |
| coordinate | Uses the normal permission flow before writing a path claimed by another active agent. | Multiple agents edit the same workspace and a human or host can decide. |

### Inspect peers and events

`getSessionPeers()` is available on `Agent`, `AutohandSDK`, and `RPCClient`. It returns other live records and excludes the caller's own CLI session.

-   `session_peer_joined` — another session appears.
-   `session_peer_updated` — meaningful activity, status, or claim data changes; heartbeat timestamp noise is ignored.
-   `session_peer_left` — a previously visible session disappears.
-   `session_awareness_error` — the registry could not be observed; the event is recoverable.

### Coordination and configuration safety

At the `coordinate` tier, a conflicting write is acknowledged and then allowed or denied through the standard permission protocol. Auto-confirm, `--yes`, YOLO, and unrestricted modes continue with a warning instead of adding an interactive pause.

When the SDK receives an explicit tier, it copies the effective CLI configuration to a private temporary file with `0600` permissions, overlays only `sessions.awareness`, and removes the file at shutdown. It never mutates the user's config file.

### Registry boundaries

Active records live under `$AUTOHAND_HOME/active-agents`, which defaults to `~/.autohand/active-agents`. Treat records as untrusted local input: the SDK strips unsafe terminal and directional controls, limits activity text and path collections, and does not let a reader delete another session's record.

## Saving and Loading Sessions

Persist a session to disk and resume it later.

The saved JSON file contains the message history, session ID, working directory, and creation timestamp. You can inspect it with any JSON viewer — it's not opaque binary.

## Manual Session Manipulation

Sessions can be built up manually before passing to a runner.

## Use Cases

### Resuming a Long Conversation

Save after each significant agent run. If your process crashes, you still have the message history.

### Building a Chat UI

Each message in a web UI maps to a session message.

### Auditing Agent Behavior

The session's message history is your audit trail. You can log it, search it, and replay it to understand what the agent did and why.