Session Persistence

Never lose your AI conversations again. Learn how Cliio keeps your sessions alive across app restarts and system reboots.

What is Session Persistence?

Session persistence means your AI conversations continue exactly where you left off, even if you close Cliio or restart your computer. Your terminal history, AI context, and ongoing work are all preserved.

With Persistence

  • Sessions survive app restarts
  • Full terminal history preserved
  • AI context maintained
  • Background processes keep running

Without Persistence

  • Fresh session on each open
  • History lost on close
  • Context must be re-established
  • Processes terminate with app

How It Works

Cliio uses tmux (terminal multiplexer) to run sessions in the background. When you close Cliio, the tmux sessions keep running. When you reopen Cliio, it automatically reconnects to your existing sessions.

Setting Up tmux

To enable session persistence, you need to install tmux. It's a one-time setup that takes less than a minute.

1

Check if tmux is already installed

Open your terminal and run:

tmux -V

If you see a version number (like "tmux 3.3a"), you're all set! Skip to step 3.

2

Install tmux via Homebrew

If tmux isn't installed, install it using Homebrew:

brew install tmux

This typically takes 30-60 seconds to complete.

3

Restart Cliio

Close and reopen Cliio to enable tmux integration. You should see a green indicator in the bottom-left corner showing tmux is active.

All Set!

Your sessions will now persist automatically. Try creating an agent, then close and reopen Cliio - your conversation will still be there.

How Persistence Works

Session Storage

Each agent runs in its own tmux session named cli-manager-[agent-id]. These sessions run independently of Cliio's main process.

What's preserved:

  • •Complete terminal scrollback history (up to 10,000 lines)
  • •AI conversation context and memory
  • •Working directory and environment variables
  • •Active processes running in the session

Auto-Recovery

When you reopen Cliio, it automatically:

  1. 1.Scans for existing tmux sessions with the cli-manager- prefix
  2. 2.Matches them to your saved agent configurations
  3. 3.Reconnects each agent to its tmux session
  4. 4.Restores the full scrollback history in the terminal view

Manual Management

You can also manage tmux sessions manually if needed:

List all sessions:

tmux list-sessions

Attach to a session directly:

tmux attach-session -t cli-manager-abc123

Kill a session manually:

tmux kill-session -t cli-manager-abc123

Fallback Mode (Without tmux)

If tmux isn't installed, Cliio still works perfectly fine - you just won't have session persistence. Each time you open Cliio, you'll start with fresh terminal sessions.

Running Without tmux

Without tmux, your sessions will terminate when you close Cliio. Any ongoing AI conversations, terminal history, and background processes will be lost. We strongly recommend installing tmux for the best experience.

Common Issues

Sessions not persisting after restart

Make sure tmux is installed and Cliio has been restarted after installation. Check the status indicator in the bottom-left corner - it should show a green "tmux active" badge.

# Verify tmux is installed
tmux -V

# Should output something like: tmux 3.3a

Old sessions still appearing

If you deleted an agent but its tmux session is still running, you can manually kill it:

# List sessions to find the ID
tmux list-sessions

# Kill the specific session
tmux kill-session -t cli-manager-abc123

Performance issues with many sessions

Each tmux session uses minimal resources when idle, but if you have dozens of old sessions running, consider cleaning them up. You can kill all Cliio-related sessions at once:

# Kill all Cliio tmux sessions
tmux list-sessions | grep cli-manager | cut -d: -f1 | xargs -I {} tmux kill-session -t {}

Next Steps

Now that you understand session persistence, customize your Cliio setup with configuration options.

Configuration Guide