feat(import): import sessions from other agents — Claude Code, Codex, Cursor, Aider

Summary

Hermes WebUI already imports sessions from the Hermes CLI agent (reads ~/.hermes/state.db via get_cli_sessions() in api/models.py). The same pattern could be extended to import read-only session history from other AI agents — Claude Code, OpenAI Codex, Cursor, Windsurf, and others — giving users a unified place to browse all their past AI conversations.

This was requested by a community member who has years of sessions across multiple tools and no good way to review them.

Agents and their storage formats

Agent	Format	Default location
Claude Code	JSONL per project (messages array with role/content)	~/.claude/projects/<hash>/
OpenAI Codex	JSON sessions	~/.codex/
Cursor	SQLite (workspaceStorage)	~/Library/Application Support/Cursor/User/workspaceStorage/
Windsurf	SQLite (similar to Cursor/VSCode)	~/Library/Application Support/Windsurf/
Aider	Markdown chat logs	Per-repo .aider.chat.history.md

Claude Code is the highest-priority target — it's the most common overlap with Hermes users and the format is straightforward JSONL.

Proposed approach

Phase 1 — Claude Code import (well-scoped, high value)

Add a get_claude_code_sessions() function in api/models.py mirroring get_cli_sessions():

1. Scan ~/.claude/projects/*/ for JSONL session files
2. Parse role/content message arrays (same shape as Hermes messages)
3. Surface them in the sidebar under a cli_session: true flag and a source: "claude_code" tag, read-only
4. Show source badge in the session header (similar to how CLI sessions are currently distinguished)

No write operations — import is purely read-only. Sessions are never modified or deleted.

Phase 2 — Generic import endpoint

A POST /api/import/session endpoint accepting a standard JSON payload:

{
  "title": "My session",
  "source": "claude_code",
  "messages": [{"role": "user", "content": "..."}, ...]
}

This lets power users write their own conversion scripts for any format and import via curl. Also provides the foundation for a future UI import wizard.

Phase 3 — UI import wizard (stretch)

A file picker in Settings → Import that accepts:

• Hermes session JSON (round-trip export/import)
• Claude Code JSONL
• Generic JSON in the Phase 2 format

What's already in place

• get_cli_sessions() (api/models.py:249) — full working pattern for external session import
• _cli_sessions_enabled flag and sidebar toggle — UI infrastructure for non-native sessions
• Session model supports profile, model, source metadata fields
• Sidebar already filters and groups by source type

Scope note

Read-only import of past conversations is firmly in scope — it's the same thing we already do for Hermes CLI sessions. Write-back (continuing a Claude Code session from within Hermes) is out of scope and would require agent-specific API integration.

Related

• Requested by community member in Discord (April 18 2026)
• Hermes CLI import: api/models.py:249 (get_cli_sessions)