{
  "id": "page:docs-agent-mux-tutorials-sessions",
  "_kind": "Page",
  "_file": "wiki/docs/agent-mux/tutorials/sessions.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-mux/tutorials/sessions.md",
    "sourceKind": "repo-docs",
    "title": "Sessions",
    "displayName": "Sessions",
    "slug": "docs/agent-mux/tutorials/sessions",
    "articlePath": "wiki/docs/agent-mux/tutorials/sessions.md",
    "article": "\n# Sessions\n\nAgent-mux persists every run as a **session**: a JSONL file written by the\nunderlying CLI (Claude, Codex, Gemini, …) that you can list, resume, inspect,\nand export through the SDK or `amux` CLI.\n\n## Listing sessions\n\n```ts\nimport { AgentMuxClient } from '@a5c-ai/agent-mux';\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\namux sessions list --agent claude\namux 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\namux run claude --session-id abc123 \"Continue from where we stopped.\"\n```\n\n## Reading session contents\n\nEach adapter exposes `parseSessionFile()` which returns a normalized `Session`\nobject (messages, tool calls, cost totals). This is useful for building\ndashboards or replaying a run:\n\n```ts\nconst adapter = client.registry.get('claude');\nconst paths = await adapter.listSessionFiles();\nconst parsed = await adapter.parseSessionFile(paths[0]);\n\nconsole.log(parsed.messages.length, 'messages');\nconsole.log(parsed.totalCost?.totalUsd ?? 0, 'USD');\n```\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\nOverride by setting the adapter's `sessionDir(cwd?)` — or pass `cwd` on the\nrun and adapters that key on cwd will scope their sessions accordingly.\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-agent-mux-tutorials",
      "to": "page:docs-agent-mux-tutorials-sessions",
      "kind": "contains_page"
    }
  ]
}