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.

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();
}
TierBehaviorUse 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.