Documentation

Sessions

Persistent conversation history — save, search, export, replay, and resume sessions.

Edit on GitHub

Every Nyzhi conversation is automatically saved as a session. You can search, resume, export, and replay any session from the CLI.

How Sessions Work

When you start Nyzhi, it creates a new session. Every message, tool call, and result is recorded. When you exit, the session is saved to disk.

Session metadata includes:

  • ID — unique identifier
  • Title — derived from your first message (truncated to ~80 characters)
  • Timestamps — created and last updated
  • Message count — total messages in the thread
  • Provider and model — which LLM was used

Storage Location

Sessions are stored as JSON files:

~/.local/share/nyzhi/sessions/<id>.json

The path is platform-dependent (uses dirs::data_dir()).

Browsing Sessions

List all sessions or search by title:

# List recent sessions
nyz sessions

# Search by keyword
nyz sessions "refactor auth"

Lookup matches on ID prefix or title substring.

Resuming a Session

Pick up where you left off:

# Resume the most recent session
nyz --continue

# Resume a specific session by title or ID
nyz --session "refactor auth"

The full conversation history is restored, so the agent has context from the previous work.

Exporting Sessions

Export a session to Markdown for documentation or review:

# Export to a generated timestamped file
nyz export "refactor auth"

# Export to a specific path
nyz export "refactor auth" -o review.md

The export includes all messages and tool interactions formatted as readable Markdown.

Replaying Sessions

View the raw event timeline of a session:

# Replay all events
nyz replay <session-id>

# Filter to specific event types
nyz replay <session-id> --filter tool_call

Useful for debugging or understanding how the agent approached a task.

Managing Sessions

# Rename a session
nyz session rename "refactor auth" "Auth module refactor - March 2025"

# Delete a session
nyz session delete "old experiment"

When multiple sessions match a query, the command shows the candidate list so you can be more specific.

Ephemeral Mode

For one-off tasks where you don’t need history:

nyz exec --ephemeral "format all files in src/"

Ephemeral sessions are not saved to disk.

Tips

  • Search broadly — nyz sessions "auth" finds anything with “auth” in the title
  • Export before sharing — use nyz export to create clean Markdown artifacts for issue reports or PRs
  • Use --continue often — it’s the fastest way to resume where you left off
  • Clean up — delete old sessions periodically to keep your data directory manageable

Next Steps

Back to overview