Session Management

A session is a persistent conversation context between you and the agent. Sessions remember the full message history, total tasks completed, and cost — so you can pick up exactly where you left off.

CLI Sessions

Starting a New Session

Running openclacky always starts a fresh session in the current directory:

openclacky
openclacky --path /path/to/project

Listing Sessions

openclacky -l

Shows recent sessions for the current directory, with their names, task counts, and creation times. Sessions are numbered for easy attachment.

Continuing the Last Session

clacky -c

Resumes the most recent session for the current directory, restoring the full conversation history.

Attaching to a Specific Session

# By number from the list
clacky -a 2

# By session ID prefix
clacky -a b6682a87

Web UI Sessions

In openclacky server mode, sessions are managed through the browser interface:

  • Create — click "New Session" in the left sidebar
  • Switch — click any session in the sidebar to switch
  • Rename — click the session name to edit it inline
  • Delete — remove sessions you no longer need

The server automatically restores the 5 most recent sessions for the current working directory on startup, so sessions survive server restarts.

Session Persistence

Sessions are saved to ~/.clacky/sessions/ as files. Each session file stores:

  • Session ID and name
  • Working directory
  • Full message history (user + assistant messages, tool calls)
  • Task count and accumulated cost
  • Timestamps

Session files are named with the session ID and persist indefinitely until manually deleted.

Session Isolation

Each session is fully isolated:

  • Separate conversation history
  • Separate working directory (can be the same or different)
  • Independent task context — the agent in one session has no awareness of another
  • Independent permission mode (CLI only)

Inactivity Cleanup

In server mode, sessions idle for more than 24 hours are automatically removed from memory to prevent unbounded growth. The session files on disk are not deleted — they remain available for future attachment if needed.

Memory System
Troubleshooting & Bug Reporting