timeline-cleanup

Delete low-value chat messages from web timelines by keyword patterns with media protection.

847|79|Updated Feb 17, 2026
One-click install
npx skills add https://github.com/rcarmo/piclaw --skill timeline-cleanup
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: timeline-cleanup
Source: https://github.com/rcarmo/piclaw/tree/main/skel/.pi/skills/timeline-cleanup
Command: npx skills add https://github.com/rcarmo/piclaw --skill timeline-cleanup

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Long-running chat timelines accumulate noise such as reload notices, compaction messages, greetings, and one-word acknowledgments, bloating the SQLite message database and making history hard to browse. This Skill removes those low-value messages in bulk while protecting messages that carry user-uploaded media.

Core Features & Use Cases

  • Pattern-based deletion: Match messages by SQL LIKE patterns or exact content, filtered by sender, length, rowid, or timestamp, with dry-run preview before deleting.
  • Built-in cleanup groups: Run cleanupAll() to sweep twelve predefined groups covering reloads, compaction, greetings, slash commands, git operations, build noise, and package installs.
  • Session scope resolution: Automatically expands web:* chats to the full session tree so branch chats are cleaned alongside the root chat.
  • Optional vacuum: Copies the database to /tmp, vacuums it, and swaps it back with a brief piclaw restart to reclaim disk space.
  • Use Case: After weeks of agent sessions, run a dry-run cleanup with the built-in groups to preview matches, then delete thousands of noise messages and vacuum the database to shrink it.

Quick Start

Ask the agent to run the timeline cleanup in dry-run mode with the built-in pattern groups to preview which low-value messages would be deleted from the web chat history.

Frequently Asked Questions about timeline-cleanup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I delete old chat messages by keyword from a SQLite database?

Use cleanupTimeline with a list of keyword patterns; it builds SQL LIKE queries against the messages table and deletes matches through the internal HTTP API. Add dryRun: true to preview matches before deleting anything.

How to clean up noisy agent chat history automatically?

Call cleanupAll() to run twelve built-in pattern groups covering reloads, compaction notices, greetings, slash commands, git operations, and build noise. Each group returns matched, skipped, deleted, and failed counts.

Does timeline cleanup delete messages with image attachments?

No, messages with media attachments are skipped by default to protect user-uploaded images. You must explicitly set includeMedia: true or pass --include-media to delete media-bearing messages.

Can I preview deletions before actually removing messages?

Yes, set dryRun: true or pass --dry-run on the CLI. The cleanup reports how many messages matched and would be skipped without performing any deletions or vacuuming.

Why does vacuuming the message database require a restart?

SQLite VACUUM needs exclusive database access, so the helper copies the database to /tmp, vacuums the copy, then swaps it in while piclaw is briefly stopped via supervisorctl. The swap runs as a detached script.

How are rate limits handled during bulk message deletion?

Deletes are throttled by default at 1100ms between requests. When the API returns HTTP 429, the helper backs off and retries up to two times, both configurable via throttleMs, retryOn429, and maxRetries options.