{
  "id": "page:docs-adapters-tutorials-sessions",
  "_kind": "Page",
  "_file": "wiki/docs/adapters/tutorials/sessions.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/adapters/tutorials/sessions.md",
    "sourceKind": "repo-docs",
    "title": "Sessions",
    "displayName": "Sessions",
    "slug": "docs/adapters/tutorials/sessions",
    "articlePath": "wiki/docs/adapters/tutorials/sessions.md",
    "article": "\n# Sessions\n\nAdapters reads each agent's native **session** storage through a shared\npersistent-session registry. Most targets use JSONL files written by the\nunderlying CLI, while some targets use JSON or SQLite. The SDK and `adapters`\nCLI normalize those formats so you can list, resume, inspect, and export\nsessions consistently.\n\n## Listing sessions\n\n```ts\nimport { AgentMuxClient } from '@a5c-ai/adapters';\n\nconst client = new AgentMuxClient();\nconst sessions = await client.listSessions({ agent: 'claude' });\nfor (const s of sessions) {\n  console.log(s.sessionId, s.title ?? '(no title)', s.modifiedAt);\n}\n```\n\nFrom the CLI:\n\n```bash\nadapters sessions list --agent claude\nadapters sessions list --agent codex --limit 20\n```\n\n## Resuming a session\n\nPass `sessionId` to `run()`. The adapter rehydrates the conversation on disk\nand the CLI picks up where it left off:\n\n```ts\nawait client.run({\n  agent: 'claude',\n  sessionId: 'abc123',\n  prompt: 'Continue from where we stopped.',\n});\n```\n\n```bash\nadapters run claude --session-id abc123 \"Continue from where we stopped.\"\n```\n\n## Reading session contents\n\nUse the `sessions` surface for normalized content. It preserves the native\nsession ID, adds the deterministic unified ID (`<agent>:<native-id>`), and\nuses the same registry path as gateway and CLI session APIs:\n\n```ts\nconst parsed = await client.sessions.get('claude', 'abc123');\n\nconsole.log(parsed.messages.length, 'messages');\nconsole.log(parsed.cost?.totalUsd ?? 0, 'USD');\nconsole.log(parsed.unifiedId); // claude:abc123\n```\n\nDirect adapter methods (`sessionDir()`, `listSessionFiles()`, and\n`parseSessionFile()`) are still available for compatibility, but new code should\nprefer `client.sessions` so native adapters and plugin-generated targets follow\nthe same contract.\n\n## Where sessions live\n\n| Agent     | Default path                               |\n|-----------|--------------------------------------------|\n| claude    | `~/.claude/projects/`                      |\n| codex     | `~/.codex/sessions/`                       |\n| cursor    | `~/.cursor/sessions/`                      |\n| gemini    | `~/.gemini/sessions/`                      |\n| opencode  | `~/.config/opencode/sessions/`             |\n| pi        | `~/.pi/agent/sessions/`                    |\n\nAtlas `SessionSemantics` and `PluginTarget` metadata describe target aliases,\nsession ID sources, and directory strategies. The runtime registry uses that\nmetadata when available, while target-specific codecs keep responsibility for\nparsing native formats.\n\n## Plugin targets and gateway sessions\n\nPlugin-generated targets use the same session registry as native adapters. A\ntarget may be addressable by its Atlas `PluginTarget.targetId` or by the\nunderlying adapter name; the normalized session still uses the adapter-native\nsession ID and the deterministic unified ID.\n\nGateway session endpoints (`/api/v1/sessions`, `/api/v1/sessions/:id`, and\n`/api/v1/sessions/:id/full`) prefer the SDK `client.sessions` path. That keeps\ngateway responses aligned with CLI and SDK output. A direct adapter-file fallback\nexists only for embedded clients that do not expose `client.sessions`.\n\n## Watching sessions\n\nLive session watching is not currently exposed on `SessionManager`.\n\nEarlier tutorial drafts mentioned `watchSessions()`, but no truthful cross-adapter contract is\navailable yet. Use `list()`, `get()`, `search()`, `export()`, and `diff()` for read-only session\ninspection.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-adapters-tutorials",
      "to": "page:docs-adapters-tutorials-sessions",
      "kind": "contains_page"
    }
  ]
}