[Feature]: load readable conversation history when switching sessions

[dnv]

Pre-submission Checklist

• I have searched existing issues and discussions
• I have read the documentation
• This is a feature request, not a bug report

Problem Statement

Currently switching sessions does switch context, but the readable conversations seemingly stored in .json are not loaded into view to be readable by the user when switching between sessions.

Proposed Solution

Loading saved previous conversation and making it fully browsable in the terminal when switching sessions would be a massive UX improvement.

Which area would this affect?

Terminal UI / UX

Alternatives Considered

No response

Examples / References

No response

Would you be willing to contribute?

None

Additional Context

No response

[CLIO-Bot]

Automated Triage Summary

Field	Value
Classification	enhancement
Priority	medium
Completeness	90%

Analysis: Reporter is correct: history is persisted in .clio/sessions/.json (verified - the active session files are 350-525KB and contain a history array), and Manager::load() successfully hydrates $state->{history} when switching sessions, but Session::handle_switch_command only displays metadata ("Messages in history: N") and never renders the messages themselves. The chat UI maintains an in-memory screen_buffer that repaint_screen uses to redraw prior turns; on session switch nothing populates that buffer from the loaded $state->{history}, so the user sees a blank chat surface. The building blocks all exist: Chat::add_to_buffer accepts user/assistant/system/error types, Chat::repaint_screen knows how to replay them, Session::get_conversation_history() returns the array, and Session::Export::export_html shows the maintainers already built a non-interactive browser for the same data. The reasonable shape is a new /session view (or similar) command that streams $state->{history} through add_to_buffer and calls repaint_screen, plus an automatic call from handle_switch_command after a successful load (likely paginated for long histories). Architectural fit is clean - no new persistence or schema work needed; the work is purely in the UI projection layer. Recommend ready-for-review so the maintainer can scope the UX (auto-replay on switch vs explicit command, pagination behavior, whether to skip system messages). Severity is 'none' because nothing is broken - the data path works - but it's a real UX gap and a reasonable enhancement to prioritize.

Root Cause Analysis

Confidence: high

Relevant files:

• lib/CLIO/UI/Commands/Session.pm
• lib/CLIO/UI/Chat.pm
• lib/CLIO/Session/Manager.pm
• lib/CLIO/Session/Export.pm
• lib/CLIO/Session/State.pm

Relevant functions:

• handle_switch_command
• get_conversation_history
• repaint_screen
• add_to_buffer
• export_html

Conversation history IS already persisted to disk per session (each session stores a JSON file containing the full history array under $state->{history}, with .clio/sessions/*.json files ranging 350-525KB in active projects). The bug-or-feature gap is at the UI layer: Session::handle_switch_command in lib/CLIO/UI/Commands/Session.pm (line 737) successfully calls CLIO::Session::Manager->load() and updates $self->{chat}->{session}, but only emits a metadata summary ("Messages in history: N", "Working directory: ...") rather than rendering the actual messages. There is no code path that iterates $new_session->get_conversation_history() and pushes entries into Chat.pm's screen_buffer (which is what repaint_screen reads to redraw prior turns). The infrastructure to do this exists - Chat::add_to_buffer($type, $content) is the entry point used today by the live request loop, and Chat::repaint_screen knows how to render user, assistant, system, and error buffer entries. The reporter's framing ("readable conversations seemingly stored in .json are not loaded into view") is accurate: the data is loaded into $state->{history} but never projected into the visible buffer. There is already an HTML escape hatch (/session export -> Session::Export::export_html) so the maintainers clearly considered read-only browsing a real need, just not in-terminal.

Affected Areas

• lib/CLIO/UI/Commands/Session.pm - handle_switch_command needs a 'render previous history into screen_buffer' branch after the successful load
• lib/CLIO/UI/Chat.pm - may want a helper like Chat::replay_session_history($state) that walks $state->{history} and pushes formatted entries into screen_buffer; add_to_buffer already handles user/assistant/system/error types but tool_calls/tool_results need a defined rendering path
• lib/CLIO/UI/CommandHandler.pm - tab completion for any new subcommand (/session view, /session show history, etc.)
• PaginationManager - replaying a long history will need paging controls similar to /session list to avoid dumping hundreds of messages to the terminal at once

---

This is an automated analysis. A maintainer will review shortly.

[fewtarius]

@CLIO-Bot what's the LoE to add this feature? Consider two options - full session replay and partial (perhaps last 100 / 500 / 1000 messages). The original state must be restored in the UI replay, tool calls and all.

[CLIO-Bot]

Direct Reply (Re: mention)

CLIO-Bot was directly addressed in a recent comment. Re-engaged with the thread based on what you said.

Field	Value
Classification	enhancement
Priority	medium
Completeness	85%

Analysis: LoE answer for the maintainer (and @dnv):

Shared foundational work (required for both options): ~2-3 days

• Extend screen_buffer schema (or build a parallel replay renderer) to represent tool_calls and tool_results. Currently the buffer only stores {type, content, timestamp} with type ∈ {user, assistant, system, error} — tool flows are rendered live during streaming and have no buffer representation at all. ~0.5-1 day.
• Extend repaint_screen() (Chat.pm L2616) to render the new types. ~0.5 day.
• Build a history→renderable adapter — translate $state->{history} entries ({role, content, tool_calls, tool_call_id, timestamp, reasoning_content, ...}) into buffer chunks. Session::Export::export_html (Export.pm L63) is the existing reference for this translation logic. ~0.5-1 day.
• Tests against long / tool-heavy sessions, including the orphan-tool_calls repair path that already runs in State.pm L351. ~0.5 day.

Option A — Full session replay (all messages, paginated): ~5-7 days total

• Adds pagination UX on top of the foundation (PaginationManager already exists at Chat.pm L21). Long sessions can have thousands of messages; tool_call pairs cannot be split arbitrarily across page boundaries, so the paginator needs to be aware of tool message pairing. ~2-3 days.
• Risk: very long sessions produce a slow replay; tool result bodies may be large (image attachments, long file reads) — needs a "truncate/expand" interaction model.

Option B — Partial replay (last 100 / 500 / 1000 messages): ~3-4 days total

• Cap the replay slice to N most-recent. Per the user's option set, default 100 is probably the right floor (matches the existing max_buffer_size cap at Chat.pm L72). ~1 day on top of the foundation.
• Risk: deciding "last N for what" — last N user turns, or last N raw messages? Tool calls are paired with tool results (State.pm L351 enforces this on load), so slicing by raw message index breaks pairs. Need to either slice by turn (user→assistant→tool cycle) or include the assistant's preceding tool_calls when a tool result is in the window. Recommend slicing by turn.

Recommendation: ship both as a hybrid — auto-replay last 100 messages on /session switch (matches user expectation, no new command needed), and add an explicit /session view or /session replay [N|all] for the full case. The shared foundation is paid once; UX defaults match the user's instinct that "switching should show the conversation."

Open UX decisions for the maintainer (not me to decide):

• Auto-replay on switch vs. explicit command only.
• Pagination behavior during full replay (page at terminal height? scroll? quit-any-time?).
• Skip system messages? Skip tool result bodies by default? (Export.pm already exposes include_system / include_tool_results flags — reuse the same toggle pattern.)
• Whether user input echoes should be displayed (current repaint_screen intentionally suppresses them, per Chat.pm L2641-ish — confirm we keep that policy on replay).

Root Cause Analysis

Confidence: high

Relevant files:

• lib/CLIO/UI/Commands/Session.pm
• lib/CLIO/UI/Chat.pm
• lib/CLIO/UI/Display.pm
• lib/CLIO/Session/Manager.pm
• lib/CLIO/Session/State.pm
• lib/CLIO/Session/Export.pm

Relevant functions:

• CLIO::UI::Commands::Session::handle_switch_command
• CLIO::UI::Chat::add_to_buffer
• CLIO::UI::Chat::repaint_screen
• CLIO::Session::Manager::load
• CLIO::Session::Manager::get_conversation_history
• CLIO::UI::Display::display_user_message
• CLIO::UI::Display::display_assistant_message

Verified against the tree: handle_switch_command (Session.pm ~L731-L953) successfully loads a new session via CLIO::Session::Manager::load(), updates $self->{chat}->{session}, then prints only metadata ("Messages in history: N"). It never iterates $state->{history} to repopulate $self->{chat}->{screen_buffer} and never calls repaint_screen(). The session history itself is intact — Manager::load() (Manager.pm L235) hydrates $state->{history} from disk, and get_conversation_history() (Manager.pm L343) returns it on demand. The HTML export path (Session::Export::export_html, Export.pm L63) already demonstrates the maintainers know how to render each {role, content, tool_calls, tool_call_id, timestamp, ...} entry — it is the blueprint for the text replay path. The hard part is fidelity: screen_buffer (Chat.pm L71) currently stores only {type, content, timestamp} with type ∈ {user, assistant, system, error}, and repaint_screen (Chat.pm L2616) only handles user/assistant. Tool calls and tool results have NO buffer representation today — they are rendered live during streaming via WorkflowOrchestrator and live in ToolResultStore keyed by tool_call_id. To truthfully restore "the original state, tool calls and all" the buffer schema and repaint_screen need to learn about tool messages and tool_calls, OR a parallel replay path is needed that bypasses the buffer and streams through the existing render machinery. Either way, the foundational work is the same.

Affected Areas

• lib/CLIO/UI/Chat.pm (screen_buffer schema, repaint_screen, max_buffer_size policy)
• lib/CLIO/UI/Display.pm (display_user_message / display_assistant_message buffer hooks)
• lib/CLIO/UI/Commands/Session.pm (handle_switch_command auto-replay hook + new /session view command)
• lib/CLIO/UI/PaginationManager.pm (replay pagination for long histories)
• lib/CLIO/Session/State.pm (orphan tool_calls repair at L351 already runs on load — verify it does not strip messages needed for replay fidelity)
• lib/CLIO/Session/Export.pm (existing source of truth for how to render each role/tool_calls/tool_results)

---

This is an automated analysis. A maintainer will review shortly.

[dnv]

If loading particularly long sessions in their entirety into browsable history becomes unfeasible for one reason or another, I think a good UX approach would be to have a certain threshhold in steps or total lines that is loaded and when the user reaches it by scrolling back, clio informs the user that the rest is available in /path/to/file.json and asks whether the user wishes to export the file into HTML for reading.

Sidenote: was unsure how to reach you directly (wanted to mention that the name Clio seems to also be in use by some legal AI software, making googling this software a bit confusing and could potentially eventually result in a dispute) and noticed that over at syntheticautonomicmind.org the the Discord link points to an expired invite and the Discussions link is a 404.

[fewtarius]

I think this is a pretty good idea, and a reasonable request - CLIO laid out the plan pretty well and I'll start working on it soon. I'm sometimes in the LocalLLama discord but I often avoid socials completely so I can focus - those links are outdated and need to be cleaned up, I'll take care of that. I don't think there's any conflict with the name but I've considered renaming CLIO to make it easier to find - I just haven't come up with a new name that's worthy. :)

[CLIO-Bot]

Follow-up Triage

Re-analysis triggered by new activity on this issue. Updated triage based on the latest comments.

Field	Value
Classification	enhancement
Priority	medium
Completeness	92%

Analysis: Re-analysis of #30, in light of @dnv's 2026-08-08T09:54:49Z comment proposing a thresholded in-terminal replay that degrades to an HTML export at the back-end of the scrollback. The reporter is engaged, exploring design space, not retracting the request. There is no new evidence that contradicts the prior root-cause analysis (and no new evidence the feature is already implemented): CLIO::Session::Manager::load (Manager.pm L235) and get_conversation_history (Manager.pm L343) still hydrate $state->{history} from .clio/sessions/<uuid>.json, and handle_switch_command (Session.pm L737) still ends with a metadata-only summary at L920-L931, never repopulating Chat::screen_buffer (Chat.pm L71). The new comment is best read as a UX refinement: keep in-terminal browsing for the recent window, but for very long sessions surface the JSON path and offer to run CLIO::Session::Export::export_to_file (Export.pm L157) on it. That maps cleanly onto the existing PaginationManager::display_content (PaginationManager.pm L456) plus a follow-up y/N prompt that calls _export_session (Session.pm L476). The session-file path is reachable from the loaded session via CLIO::Util::PathResolver::get_session_file($session_id) (PathResolver L168) so the prompt can show the exact .clio/sessions/<id>.json path the user mentions. Reaffirming the LoE and UX decision points from the prior triage still applies, with the threshold/offload idea now first-class. Recommendation stays ready-for-review with enhancement/area:ui/area:session/priority:medium so the maintainer can decide between (a) the full-replay foundation + the threshold/offload UX on top, or (b) shipping the threshold/offload first and adding the full-replay foundation later. The two stale project links the reporter also called out (expired Discord invite on syntheticautonomicmind.org and 404 Discussions link) are unrelated to the feature but are worth routing to a docs/site issue - they don't change this triage.

Root Cause Analysis

Confidence: high

Relevant files:

• lib/CLIO/UI/Commands/Session.pm
• lib/CLIO/UI/Chat.pm
• lib/CLIO/UI/Display.pm
• lib/CLIO/UI/PaginationManager.pm
• lib/CLIO/Session/Manager.pm
• lib/CLIO/Session/State.pm
• lib/CLIO/Session/Export.pm
• lib/CLIO/Session/ToolResultStore.pm

Relevant functions:

• CLIO::UI::Commands::Session::handle_switch_command
• CLIO::UI::Commands::Session::_export_session
• CLIO::UI::Chat::add_to_buffer
• CLIO::UI::Chat::repaint_screen
• CLIO::UI::Chat::writeline
• CLIO::UI::Display::display_user_message
• CLIO::UI::Display::display_assistant_message
• CLIO::UI::Display::display_system_message
• CLIO::UI::PaginationManager::display_list
• CLIO::UI::PaginationManager::display_content
• CLIO::Session::Manager::load
• CLIO::Session::Manager::get_conversation_history
• CLIO::Session::Export::export_html
• CLIO::Session::Export::_render_message
• CLIO::Session::State::load
• CLIO::Session::State::_validate_and_repair_history

On /session switch, handle_switch_command (Session.pm L737-L931) successfully calls CLIO::Session::Manager->load (Manager.pm L235-L304), which in turn runs CLIO::Session::State->load (State.pm L182) to hydrate $state->{history} from disk (PathResolver.get_session_file -> .clio/sessions/<uuid>.json, project-local at PathResolver L122). The path then updates $self->{chat}->{session} and re-applies theme/style (Session.pm L906-L918) but only emits a metadata summary Messages in history: N / Working directory / Session ID (Session.pm L920-L931). Nothing is ever pushed into $self->{chat}->{screen_buffer} (Chat.pm L71) so repaint_screen (Chat.pm L2616) has nothing to replay; the in-memory buffer only ever receives entries via add_to_buffer (Chat.pm L2595), which is called from the live request path in Display.pm (L120 user, L139 assistant, L175 system, L213 error, L237 success, L261 warning, L285 info) and from Chat::_handle_ai_response (Chat.pm L910/L920/L927). Tool flows have no buffer representation at all: the WorkflowOrchestrator renders tool headers/diffs/expanded content through CLIO::UI::ToolOutputFormatter (display_tool_header L109, display_action_detail L183, display_expanded_content L319) and only persists the post-shape via add_message calls (WorkflowOrchestrator.pm L1586-L1610) - they never reach screen_buffer. The exported HTML path already proves the maintainers know how to render each role from {role, content, tool_calls, tool_call_id, timestamp, ...}: see CLIO::Session::Export::export_html (Export.pm L63) plus _render_message (L170) and _format_tool_calls (L223). The HTML escape hatch exists today via /session export -> _export_session (Session.pm L467-L524), which writes a self-contained HTML file using atomic_write. Pagination infrastructure (CLIO::UI::PaginationManager::display_list and display_content L445) already supports both inline and fullscreen (alternate-buffer) modes with arrow-key navigation and Q-to-quit. The reporter's threshold + 'offer HTML export' proposal is a small but real architectural fit: instead of holding the entire history in the in-memory screen_buffer (capped at max_buffer_size=100, Chat.pm L72), the replay path can cap a N most-recent slice, then on scroll-back to the boundary (or as a follow-up action) hand off to CLIO::Session::Export::export_to_file so the user can read the rest in a browser. The orphan-tool_calls repair already runs on every State::load (State.pm _validate_and_repair_history) so replaying an old session won't break API correlation on the next turn.

Affected Areas

• lib/CLIO/UI/Commands/Session.pm (handle_switch_command needs a post-load replay hook, plus a new /session view|replay [N|all] subcommand)
• lib/CLIO/UI/Chat.pm (add_to_buffer schema is currently {type, content, timestamp} with type in {user, assistant, system, error, success, warning, info} per repaint_screen branches L2641-L2761; tool_calls/tool_results have no buffer representation today)
• lib/CLIO/UI/Display.pm (display_user_message/display_assistant_message already wire add_to_buffer; new path needs to project history entries through them or a sibling translator)
• lib/CLIO/UI/PaginationManager.pm (display_list/display_content already paginate large inputs; replay needs to be aware of tool_call/tool_result pairs that must not be split across page boundaries)
• lib/CLIO/Session/Export.pm (existing render reference for {role, content, tool_calls, tool_call_id, timestamp} - the natural template for the replay adapter)
• lib/CLIO/Session/State.pm (the orphan-repair path on load may strip messages needed for replay fidelity - needs verification)
• lib/CLIO/UI/Chat/Help.pm (any new /session subcommand must be added to the help index)

---

This is an automated analysis. A maintainer will review shortly.