OpenCode History Cleaner

A lightweight, cross-platform utility script to safely clear chat history, wipe prompt drafts, truncate log files, and optimize the local SQLite database of the OpenCode desktop application.

It automatically shrinks the local database size (often from gigabytes down to a few kilobytes) using SQLite's VACUUM process.

🚀 Features

• App Shutdown: The clean command gracefully terminates OpenCode before cleanup; targeted commands leave it running.
• Database Optimization: Clears all message/session tables (or trims old sessions with --retain) and executes SQLite VACUUM to free up disk space.
• Cache Clean: Wipes prompt history, drafts, scroll positions, and notifications.
• Log Truncation: Empties application log files to 0 bytes.
• History Statistics: Reports session counts and estimated stored data size by project without changing anything.
• Cross-Platform: Supports macOS, Windows, and Linux.

---

🛠️ How to Use

Running the Python script with no command is safe: it only displays the help text and performs no cleanup. Cleanup commands ask for confirmation unless --yes is supplied.

# Show help (does not change anything)
python3 clear_opencode_history.py

# Clean everything, with confirmation
python3 clear_opencode_history.py clean

# Clean everything non-interactively
python3 clear_opencode_history.py clean --yes

# Run one operation only
python3 clear_opencode_history.py database --yes

# Trim old sessions but retain the last 30 days
python3 clear_opencode_history.py database --retain 30d --yes

# Vacuum the database without deleting any data
python3 clear_opencode_history.py vacuum --yes

# The same retention option can be used with the complete cleanup
python3 clear_opencode_history.py clean --retain 4w --yes
python3 clear_opencode_history.py caches --yes
python3 clear_opencode_history.py logs --yes
python3 clear_opencode_history.py outputs --yes

# Preview database cleanup without changing anything
python3 clear_opencode_history.py database --retain 30d --dry-run

# Show session counts and sizes (read-only; no confirmation required)
python3 clear_opencode_history.py stats

# Test a copied database explicitly (never the default live database)
python3 clear_opencode_history.py database --db-path /tmp/opencode-test.db --yes

Use python3 clear_opencode_history.py --help for all commands. quit only closes OpenCode; clean closes it before cleaning. stats reports logical session, message, and part payload sizes by project, plus the total database file size; it does not modify the database.

🍎 macOS / Linux

1. Download clear_opencode_history.py and clear_opencode_history.command to the same folder.
2. Run ./clear_opencode_history.command clean from Terminal to clean everything.
   • Note: If macOS prevents execution, open Terminal and run chmod +x clear_opencode_history.command first.

🪟 Windows

1. Make sure you have Python 3 installed on your system.
2. Download clear_opencode_history.py and clear_opencode_history.bat to the same folder.
3. Run clear_opencode_history.bat clean from Command Prompt to clean everything.

---

🔒 Safety First

This utility only deletes your chat sessions, message history, logs, and prompt caches. It preserves your custom settings, VCS configurations, and open project directories, so you won't lose your workspace preferences.

🧪 Tests

The database tests use an immutable, read-only snapshot of tests/opencode.db and mutate only per-test temporary copies. Run them with:

python -m unittest discover -s tests -t .

The --db-path option is accepted by database, vacuum, and stats so a database override cannot accidentally make clean operate on live cache or log directories.

--dry-run is available for database and clean. It opens the database read-only and reports sessions and event aggregates that would be removed, including their fractions and percentages of the database totals. For safety, clean --dry-run previews database cleanup only; it does not evaluate caches, logs, or outputs. The old --no-pause option remains accepted for compatibility, but commands no longer pause after completion.

The vacuum command only reclaims unused SQLite pages; it does not delete sessions or other rows. --retain accepts a positive number followed by d (days), w (weeks), or m (months), for example 30d, 4w, or 5m. Months are treated as 30 days. Retention is based on the session's last-updated time. Retained sessions keep their complete parent and child session tree, including the corresponding durable event history; expired session trees remove their event aggregates as well. Without --retain, the database operation removes all sessions and events as before. clean --retain still clears caches, logs, and tool outputs; retention applies only to database sessions and their event history.