Skip to content

sessionFlow v1.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 07 Oct 07:31
· 65 commits to main since this release
v1.0.0
710947d

sessionFlow v1.0.0

Search. Understand. Continue. Switch agents without losing context.

SessionFlow v1.0.0 is a production-ready cross-agent continuity layer. It unifies session history from multiple AI coding agents into a single searchable index, restores context mid-task, and hands off work between agents without losing reasoning or progress.

Nothing is uploaded anywhere — all indexing, searching, and context restoration happens locally on your machine.

Highlights

  • Unified agent timeline: Merge sessions from 8+ agent platforms (Codex, Claude Code, ZCode, DSH, Cursor, Kiro, Grok, Antigravity) into one queryable index.
  • Full-text search: Find commands, code changes, or reasoning across all agent history — CJK substring search supported.
  • Context restoration: Resume any session from where you left off with voyager continue <thread> or restore via MCP/DSH tools.
  • Cross-agent handoff: Seamlessly transition work between different agents using voyager switch and voyager handoff.
  • Local-first privacy: No cloud upload required; all data stays on your machine.
  • DSH plugin available: Six standardized tools for agent-side query access (see DSH Integration).

Supported Agents and Workflows

First-class support (native adapters)

  • Codex: Rollout JSONL format with thread correlation.
  • Claude Code: Project JSONL with file-version chain tracking.
  • ZCode: SQLite-based session storage.
  • DSH: Compressed JSONL sessions via zstd transport.

Good-faith support (best-effort adapters)

  • Cursor: JSON project files.
  • Kiro: Event-based session logs.
  • Grok: Agent conversation records.
  • Antigravity: Custom runtime sessions.

Note: Provider capabilities differ in their native persistence models. sessionFlow normalizes these differences while preserving provenance. Where an agent's native interface supports it, resume commands are executed automatically; otherwise, users receive actionable hints about how to manually restore context.

Search, Timeline, and Continuity

Full-text search

Search across all normalized events:

voyager search "sqlite migration"

Supports:

  • CJK substrings (中文搜索)
  • File path matching
  • Command history lookup
  • Context snippet extraction

Timeline per repository

See what happened to your project over time:

voyager list --repo my-project

Shows:

  • Session ID, provider, timestamp
  • Message/tool counts
  • Titles extracted from session metadata

Context restoration

Resume any session directly:

voyager continue <thread-id>

Or restore context inline:

voyager show <thread-id> --json | ...

Cross-agent handoff

Move work between agents:

voyager handoff claude --from codex

Uses lease-based concurrency control to prevent conflicting writes when multiple agents access the same workspace thread.

Reliability and Safety

Read-only by default

All core queries (search, recent, session, current_work) are read-only. The only write operation (merge) persists explicit user actions like creating or updating WorkThreads.

Transactional repairs

The voyager doctor --fix command runs a read-only diagnostic first, then applies only whitelisted repairs (SAFE_FIXERS). Repairs are:

  • Transactional: All-or-nothing per repair batch
  • Idempotent: Safe to re-run after failures
  • Dry-run enabled: Test before applying changes

Empty-state UX

When no agent sessions are detected, sessionFlow shows clear error messages with:

  • Helpful hints about supported providers
  • Commands to run synthetic demo data (voyager demo)
  • Links to documentation for extending support to new agents

No tracebacks, no confusing stack traces — just actionable guidance.

DSH Integration

The DSH plugin (dsh-sessionflow) exposes six standardized tools to any DSH-connected agent:

  1. sessionflow_search: Full-text search across all sessions
  2. sessionflow_recent: Get most recent sessions from last N hours/days
  3. sessionflow_session: Retrieve full details of a specific session/thread
  4. sessionflow_current_work: Identify active/in-progress threads
  5. sessionflow_continue_context: Restore context from a prior session
  6. sessionflow_merge: Merge work across multiple session sources

Usage

Install the plugin once:

dsh plugin --profile <profile> install HarryHeYu/dsh-sessionflow

Agents can then use natural language to discover and continue past work:

"我之前这个项目做到哪了？" → sessionflow_current_work
"继续这个会话" → sessionflow_continue_context <id>
"帮我合并 codex 和 claude 的上下文" → sessionflow_merge

Bridge Schema v1: Versioned contract between core and plugin. Additive-only changes preserve compatibility; schema never breaks consumer implementations.

Installation

Pipx (recommended)

Isolated CLI installation without virtualenv management:

pipx install "voyager[all] @ git+https://github.com/HarryHeYu/sessionFlow.git"

Components:

  • Core: pipx install "voyager @ git+https://github.com/HarryHeYu/sessionFlow.git"
  • DSH support: pipx install "voyager[dsh] @ git+https://github.com/HarryHeYu/sessionFlow.git"
  • MCP server: pipx install "voyager[mcp] @ git+https://github.com/HarryHeYu/sessionFlow.git"

Direct pip

User-level installation:

pip install "voyager[all] @ git+https://github.com/HarryHeYu/sessionFlow.git"

From source

For development or custom builds:

git clone https://github.com/HarryHeYu/sessionFlow
cd sessionFlow
pip install -e ".[all]"

Verify installation

voyager --help
voyager demo           # Synthetic tour, no agents needed
voyager list           # Discover existing sessions

Known Limitations

Provider capability variance

Different agents expose different levels of persistence detail:

  • Native session IDs may not map perfectly across providers
  • Some agents track file edits better than others
  • Resume command support depends on provider capabilities and observed evidence

Zero-touch continuity

Automatic context recovery works best when:

  • The agent natively supports session restoration commands
  • Sufficient evidence exists in the session logs to identify correct state
  • Provider-specific constraints are documented in adapter implementations

Where zero-touch isn't available, sessionFlow provides clear manual restoration hints.

Platform-specific behavior

Some features behave differently across operating systems:

  • Windows uses PowerShell for certain Codex operations
  • File path normalization differs between Unix and Windows
  • Unicode handling is tested on all platforms but may require environment configuration in rare cases

Distribution strategy

sessionFlow v1.0.0 is distributed primarily through GitHub source installation. Package manager publishing is intentionally deferred:

  • PyPI: Name undecided (existing voyager package taken); target future release
  • npm (dsh-sessionflow): Publication deferred by design; current distribution via GitHub plugin installation

This allows the team to validate the stable API surface before committing to package manager ecosystems.

Data retention

sessionFlow preserves historical sessions even when their source provider becomes unavailable (marked as SOURCE_MISSING). This prevents accidental data loss during provider migrations or tool replacements. However, deleted session files from local agent directories will be reflected in future scans unless explicitly archived.

Changelog: See CHANGELOG.md for full release history including RC1 and RC2 improvements.

Architecture: Learn more about the bridge protocol and adapter architecture in docs/architecture.md.

Post-1.0 plans: Roadmap and upcoming improvements tracked in docs/POST-1.0.md.

Assets 2
Loading