The package installs three binaries:
| Binary | Purpose |
|---|---|
sessions |
Ingest, search, manage, transfer, and sync session records. |
sessions-mcp |
Expose session operations over MCP. Streamable HTTP is the default transport. |
sessions-serve |
Run the authenticated /v1 HTTP API or apply Postgres migrations. |
Run sessions <command> --help, sessions-mcp --help, or
sessions-serve --help for the exact help shipped by the installed version.
| Command | Options and behavior |
|---|---|
sessions ingest |
Index all providers. --source, --force, --verbose, and --json are supported. |
sessions reindex |
Alias command with the same behavior and options as ingest. |
sessions ingest-watch |
Continuously ingest changes. Alias: watch-ingest. Supports repeatable --source, --no-initial, --debounce (default 2000 ms), --poll (default 10000 ms; 0 disables), --status, and --json. |
sessions search-indexed <query> |
Full-text search. Aliases: search, indexed-search. Filters: --source, --project, --machine; default --limit 20. Add --tools, --semantic, --hybrid, or --json. |
sessions transcript-search <query> |
Search transcript content through the active store. Alias: registry-search. Supports --project, --limit (default 20), and --json. |
sessions recall <query> |
Local-only combined recall. Supports --source, --project, --machine, --limit (default 10), --no-semantic, and --json. |
sessions embed |
Generate local message embeddings. Supports --limit (default 200) and --json; requires OPENAI_API_KEY. |
sessions graph |
List graph entities, use --related <type:name>, or inspect --session <id>. Also supports --type, --source, --limit (default 50), and --json. |
recall, embeddings, and the richer local graph/tool analysis require the local
index. Active-store commands fail clearly when a requested operation has no
self-hosted /v1 equivalent.
| Command | Options and behavior |
|---|---|
sessions list |
List the active store. Supports --project, --limit (default 50), and --json. |
sessions history |
List with --project, --today, --agent, --limit (default 200 before filtering), and --json. |
sessions recent |
List recent records with --machine, --limit (default 20), and --json. |
sessions list-indexed |
List with --source, --project, --machine, --limit (default 50), and --json. Alias: indexed-list. |
sessions show <id> |
Resolve an internal id, unique prefix, or --source-qualified native id. --messages defaults to 12; --json returns full structured output. |
sessions machines |
List contributing machines and counts; supports --json. |
sessions paths |
List project paths and counts; supports --json. Missing-path markers are local-mode only. |
sessions stats |
Show ingestion and project statistics; supports --json. |
sessions create |
Create a record with required --source and --source-id; optional --title, --project-path, --project-name, --model, --machine, and --json. |
sessions rename <id-or-prefix> <title> |
Set the title. Use --source for a provider-native id; supports --json. |
sessions delete <id> |
Delete a record from the active store; supports --json. |
sessions resume [id-or-prefix] |
Select by id, --project, --last, or --pick; use --source for a native id. --print-command does not launch. Only Claude currently has an executable resume command. |
sessions watch |
Refresh the active-store table. Supports --project, --interval (default 5 seconds), --json, and --once. |
The active store is local SQLite by default. It becomes the self-hosted HTTP store only when self-hosted mode, API URL, and API key are all configured; a partial self-hosted configuration fails closed rather than silently using local data.
| Command | Options and behavior |
|---|---|
sessions live |
Inspect tmux-backed Codewith/session panes. Filters: --open-only, --project, --machine, --status; --interval defaults to 5. Use --watch, --once, or --json. |
sessions bulk <action> |
Plan status, capture, doctor, ensure, start, stop, or restart. Supports live filters, --dry-run, --yes, --no-queue, --concurrency (default 2), --jitter (default 0), --max-active-agents (default 12), optional --max-load1, and --max-load-per-core (default 1.5). Mutating execution is intentionally disabled; use --dry-run to inspect plans. |
The JSON schemas and guard semantics are defined in the live status contract.
| Command | Options and behavior |
|---|---|
sessions relocate <old-path> <new-path> |
Rewrite transcript paths and, unless --no-db, active-store paths. Supports --dry-run, --verbose, and --json. |
sessions migrate <source-project> <target-project> |
Move Claude project session files. Supports --dry-run and --verbose. |
sessions transfer export |
Export raw files. Supports --project, --output, --name, --dry-run, --verbose, and --json. |
sessions transfer import <path> |
Import an export. Supports --remap-home, --remap <from:to>, --reingest, --overwrite, --dry-run, --verbose, and --json. |
sessions import-db <path> |
Merge another local sessions database, preserving machine tags; supports --json. This operation is local-only. |
sessions handoff [target] |
Create an ExternalHandoffBundleV1. Source/context flags: --source-agent, --source-session, --source-transcript, --cwd, --idempotency-key, and --context-summary. Repeatable fields: --auth-ref, --verification, and --blocker. Codewith settings: --codewith-auth-profile and --codewith-mode (default interactive). Size limits: --max-turns (default 8) and --max-turn-chars (default 1200). Output/action flags: --dry-run, --print-command, --launch, --emit-skill, and --json. |
| Command | Options and behavior |
|---|---|
sessions sync |
Ingest, then push content in self-hosted mode. Supports --no-ingest, --dry-run, --watch, source/project/machine filters, --limit (default 500), --interval, --max-iterations (default 60), --backup-command, and --json. |
sessions daemon |
Run bounded sync polling. Same filters and safety options as sync; --interval defaults to 60 seconds and --max-iterations defaults to 60. --status exits after printing the provider ingest-watch roots and persisted lag, last-attempt, last-success, skipped-file, and error metrics; add --json for machine-readable output. |
sessions backfill |
Inventory by default or apply a bounded historical backfill. Selection flags are --source, --pilot, --range-start, --range-end, repeatable --known-id, and --all-sources. Apply requires --apply, --confirm-apply BACKFILL_APPLY, --max-total-bytes, and --backup-command; production-like targets additionally require --allow-production after separate approval. --batch-size defaults to 128, --concurrency to 1, and --max-session-bytes to 67108864. --checkpoint overrides the default ~/.hasna/sessions/backfill/checkpoint.json; --json emits machine-readable output. |
Live self-hosted sync and backfill apply require a successful backup command. Dry runs do not execute the backup command or push content.
sessions-mcp binds Streamable HTTP to 127.0.0.1:8877 by default. The MCP
endpoint is /mcp and GET /health returns
{"status":"ok","name":"sessions"}.
| Selector | Effect |
|---|---|
--stdio or MCP_STDIO=1 |
Use stdio transport. |
--http or MCP_HTTP=1 |
Explicitly select the default HTTP transport. |
--port <n> or MCP_HTTP_PORT=<n> |
Override the HTTP port. The CLI flag wins. |
sessions-serve starts the HTTP service on 127.0.0.1:3456 by default.
sessions-serve migrate applies Postgres migrations, while
sessions-serve migrate --dry-run only reports pending migrations. See the
configuration reference for server mode, auth, database,
body-limit, and bind settings.