Session Management

Kiro CLI automatically saves all chat sessions on every conversation turn. Sessions are stored per-directory in the database, allowing you to resume from any previous session, export to files, or integrate with custom storage solutions.

Automatic: Every conversation turn saved to database
Scope: Per-directory (each project has own sessions)
Storage: Local database (~/.kiro/)
Session ID: UUID for each session

# Resume most recent session
kiro-cli chat --resume

# Interactive picker
kiro-cli chat --resume-picker

# Resume a specific session by ID
kiro-cli chat --resume-id <SESSION_ID>

# List all sessions
kiro-cli chat --list-sessions

# Delete session
kiro-cli chat --delete-session <SESSION_ID>

# Start a fresh conversation (saves current session automatically)
/chat new

# Start a fresh conversation with an initial prompt
/chat new how do I set up a React project

# Resume session (interactive)
/chat resume

# Print the current session ID
/session-id

# Save to file
/chat save <path>

# Load from file
/chat load <path>

Sessions started with --cloud run in a managed cloud sandbox and are stored in your account's cloud session store rather than the local per-directory database — see Cloud sessions. They appear alongside local sessions in --list-sessions and the in-session /sessions picker, with columns showing each session's environment and status.

--resume-id detects a cloud session ID automatically, so no --cloud flag is needed to resume — and because the session lives in the cloud, you can resume it from any machine:

kiro-cli --resume-id <SESSION_ID>

/chat save and /chat load operate on the local session archive and aren't available in cloud sessions.

Use custom scripts to save/load sessions from version control, cloud storage, or databases.

/chat save-via-script <script-path>

Script receives session JSON via stdin.

Example: Save to Git Notes

#!/bin/bash
COMMIT=$(git rev-parse HEAD)
TEMP=$(mktemp)
cat > "$TEMP"
git notes --ref=kiro/notes add -F "$TEMP" "$COMMIT" --force
rm "$TEMP"
echo "Saved to commit ${COMMIT:0:8}" >&2

/chat load-via-script <script-path>

Script outputs session JSON to stdout.

Example: Load from Git Notes

#!/bin/bash
COMMIT=$(git rev-parse HEAD)
git notes --ref=kiro/notes show "$COMMIT"

Database: Sessions auto-saved per-directory
Files: Manual export via /chat save
Custom: Script-based integration

Session ID: UUID format (e.g., f2946a26-3735-4b08-8d05-c928010302d5)

kiro-cli chat --resume

Continues most recent conversation.

kiro-cli chat --resume-picker

Shows list of sessions to choose from.

/chat save backup.json

Exports current session to file.

# Save to git notes
/chat save-via-script ./scripts/save-to-git.sh

# Load from git notes
/chat load-via-script ./scripts/load-from-git.sh

Symptom: "Failed to start session: Session is active in another process (PID XXXXX)"
Cause: You're trying to resume a session that's already open in another terminal window or tab.
Solution: Sessions can only be active in one process at a time to prevent conversation corruption. You have two options:

1. Close the other terminal that has the session open, then resume.
2. Fork the session into a new one using /chat save in the original terminal, then /chat load in the new terminal. This creates a separate copy you can use independently.

Symptom: "No saved chat sessions"
Cause: No sessions in current directory
Solution: Sessions are per-directory. Navigate to correct directory.

Symptom: Script exits with error
Cause: Script returned non-zero exit code
Solution: Test script manually. Ensure it exits 0 on success.

Symptom: Can't load session
Cause: Script didn't output valid JSON
Solution: Test script outputs valid session JSON to stdout.

• Sessions can only be active in one process at a time (no multi-window sharing)
• Sessions stored per-directory
• Auto-save to database only (not files)
• Session IDs are UUIDs (not human-readable)
• Local sessions don't sync across machines (use scripts for custom storage); cloud sessions are stored in the cloud and resume from anywhere
• No session search by content

Storage: SQLite database in ~/.kiro/

Scope: Sessions keyed by directory path

Auto-save: After every conversation turn

Script interface:

• Save: JSON via stdin, exit 0 on success
• Load: JSON via stdout, exit 0 on success

• Learn about Chat Commands
• See Interactive Chat Mode
• Review Context Management
• Use Rewind to fork a conversation at an earlier turn