Feature: Session Management & Continuity

Relevant source files

The following files were used as context for generating this wiki page:

• ralph_loop.sh
• lib/date_utils.sh
• CLAUDE.md
• README.md
• ralph_import.sh
• IMPLEMENTATION_STATUS.md
• TESTING.md

The Session Management & Continuity feature in Ralph enables the system to maintain context across multiple autonomous development loops. By preserving the sessionId provided by the Claude Code CLI, Ralph can create more coherent and context-aware development cycles, improving its ability to handle complex, multi-step tasks. This system is enabled by default but can be controlled via CLI flags.

The core of this feature is implemented within the response_analyzer.sh library, which is responsible for parsing the sessionId from Claude's output and persisting it. The main ralph_loop.sh script then utilizes this persisted session information to continue the conversation in subsequent loops. The session has a 24-hour expiration and includes an automatic reset mechanism triggered by key events like project completion or manual interrupts.

Sources: README.md, CLAUDE.md

Architecture and Components

The session management system is composed of shell script logic, state files, and CLI flags that work together to persist and utilize session context.

Sources: CLAUDE.md:20-49

Key Components

Component	Type	Description	Source File
ralph_loop.sh	Script	The main loop orchestrator that uses the session ID.	ralph_loop.sh
lib/response_analyzer.sh	Library	Contains functions to parse, store, and retrieve the session ID.	CLAUDE.md:29-49
ralph_import.sh	Script	Utilizes session ID for potential continuation of PRD conversions.	ralph_import.sh
.claude_session_id	State File	Persists the current session ID and its timestamp.	CLAUDE.md:39, 461-462
.ralph_session_history	Log File	Tracks the last 50 session transitions for debugging.	CLAUDE.md:42, 462

Component Interaction Diagram

This diagram shows how the main loop, response analyzer, and state files interact to manage session continuity.

Session Lifecycle

The session lifecycle is managed through a series of functions that handle initialization, retrieval, storage, and reset. The session is designed to expire after 24 hours to ensure freshness.

Sources: CLAUDE.md:459-480, TESTING.md:113-114

Lifecycle Functions

Function	Description	Source File
init_session_tracking()	Initializes the session file and validates its state at the start of the loop.	CLAUDE.md:465
get_session_id()	Retrieves the current session ID from the .claude_session_id file.	CLAUDE.md:463
should_resume_session()	Checks if the stored session is valid and has not expired (24-hour expiration).	CLAUDE.md:478
store_session_id()	Persists the session ID and a timestamp to the .claude_session_id file after a successful Claude response.	CLAUDE.md:477
reset_session(reason)	Clears the session state and logs the reason for the reset.	CLAUDE.md:464
log_session_transition()	Records session state changes to the .ralph_session_history file.	CLAUDE.md:465

Sources: CLAUDE.md:459-480

Session State Transition Flow

The following diagram illustrates the flow of session state management during a single loop iteration.

State Management Files

Session state is persisted on the filesystem using two hidden files in the project's root directory.

Filename	Purpose	Content Example
.claude_session_id	Stores the current session ID and the epoch timestamp of when it was stored. Used to check for session expiration.	{"session_id": "claude_session_123", "timestamp": 1672531200}
.ralph_session_history	A log file that records the last 50 session transitions (e.g., created, reset, resumed) for debugging purposes.	[timestamp] RESET: Manual reset via --reset-session

Sources: CLAUDE.md:39-42, 461-462, README.md:228-229

Configuration and Control

Session continuity can be controlled via CLI flags passed to the ralph command.

Flag	Description	Default Behavior
--continue	Explicitly enables session continuity (this is the default behavior).	Enabled
--no-continue	Disables session continuity, forcing a fresh session for each loop.	-
--reset-session	Manually clears the current session state, forcing a new session on the next loop.	-

Sources: README.md:213-227, CLAUDE.md:100, 469

Session Auto-Reset

To prevent issues with stale or problematic sessions, Ralph automatically resets the session state under specific conditions. When a reset is triggered, the reset_session(reason) function is called, which clears the .claude_session_id file and logs the event to .ralph_session_history.

Sources: CLAUDE.md:467-469, README.md:222-226

Auto-Reset Triggers

This diagram shows the events that trigger an automatic session reset.

Integration with ralph-import

The session management concept also extends to the ralph-import script. When converting a Product Requirements Document (PRD), the script parses the sessionId from the Claude Code CLI's JSON output. This ID is logged, providing a reference that could potentially be used to continue an interrupted or failed conversion process.

Sources: ralph_import.sh:25, 144, 257

Key Functions in ralph_import.sh

• parse_conversion_response(): This function is responsible for extracting the sessionId from the JSON output of the Claude Code CLI.
• Global Variable PARSED_SESSION_ID: The extracted session ID is stored in this variable for logging and potential future use.

Sources: ralph_import.sh:25, 126-147

Testing

The session management feature is covered by a dedicated test suite to ensure its reliability. The test_session_continuity.bats file contains 26 tests that validate the entire session lifecycle, including creation, expiration, and reset triggers.

Sources: IMPLEMENTATION_STATUS.md:17, TESTING.md:113-114, CLAUDE.md:522, 545

Summary

The Session Management & Continuity feature is a cornerstone of Ralph's ability to perform complex, multi-step development tasks. By persisting the sessionId across loop iterations, it provides the AI with a continuous conversational context, significantly improving its coherence and effectiveness. The system is robust, with features for automatic expiration, event-triggered resets, and manual control via CLI flags, ensuring both powerful continuity and the flexibility to start fresh when needed.

Sources: README.md:213-214, CLAUDE.md:475-480