Auto Cleanup automatically manages your task history by removing old tasks to free up disk space and improve performance. Tasks are intelligently classified and retained based on their type and age, ensuring important work is preserved while temporary or experimental tasks are cleaned up.
Warning: Task deletion is permanent and cannot be undone. Deleted tasks are completely removed from disk, including all conversation history, checkpoints, and associated files.
As you work with Kilo Code, each task creates files containing conversation history, checkpoints, and other data. Over time, this accumulates and can consume significant disk space. Auto-Cleanup solves this by:
- Automatically removing old tasks based on configurable retention periods
- Preserving important tasks by classifying them into different types
- Protecting favorited tasks from deletion
- Managing disk usage without manual intervention
Key Benefits:
- Free up disk space: Automatically remove old task data
- Improve performance: Reduce the size of task history
- Flexible control: Configure different retention periods for different task types
- Safety first: Favorited tasks can be protected from deletion
- Manual override: Run cleanup manually whenever needed
Auto-Cleanup uses an intelligent classification system to determine how long each task should be retained:
Every task is automatically classified into one of these categories:
| Task Type | Description | Default Retention |
|---|---|---|
| Favorited | Tasks you've marked as favorites | Never deleted (or 90 days if configured) |
| Completed | Tasks that successfully finished | 30 days |
| Incomplete | Tasks that were started but not completed | 7 days |
| Regular | Default classification for other tasks | 30 days |
A task is considered "completed" when Kilo Code uses the attempt_completion tool to formally mark it as finished. Tasks without this completion marker are classified as incomplete, even if you consider them done. This distinction helps clean up abandoned or experimental tasks more aggressively.
When Auto-Cleanup runs, it:
- Scans all tasks in your task history
- Classifies each task based on its properties and completion status
- Checks retention periods to determine eligibility for deletion
- Protects active tasks currently in use
- Deletes eligible tasks and their associated files
- Reports results including disk space freed
Access Auto-Cleanup settings through the Kilo Code settings panel:
- Click the gear icon (gear icon) in Kilo Code
- Navigate to the Auto-Cleanup section (under Checkpoints)
Auto-Cleanup settings panel
Check the "Enable automatic task cleanup" option to activate the feature. When enabled, tasks will be automatically removed based on your retention settings.
Configure how long different types of tasks are kept before cleanup:
Default: 30 days
Minimum: 1 day
Sets the base retention period for regular tasks that don't fall into other categories.
Never delete favorited tasks (recommended)
When enabled, favorited tasks are preserved indefinitely regardless of age. This is the safest option to prevent accidental deletion of important work.
If disabled, you can set a custom retention period:
Default: 90 days
Minimum: 1 day
To favorite a task, use the star icon in the task history panel.
Default: 30 days
Minimum: 1 day
Tasks successfully completed via the attempt_completion tool are retained for this period. These tasks typically represent finished work that may still be useful for reference.
Default: 7 days
Minimum: 1 day
Tasks without completion status are retained for a shorter period. This helps clean up experimental or abandoned tasks more quickly while still giving you time to review them.
The settings show when the last cleanup operation ran, helping you understand the cleanup schedule.
Click the "Run Cleanup Now" button to immediately trigger a cleanup operation using your current settings. This is useful when:
- You need to free up disk space urgently
- You've changed retention settings and want them applied immediately
- You want to preview what would be cleaned up (check the output)
For Individual Developers:
- Default retention: 30 days
- Completed tasks: 30 days
- Incomplete tasks: 7 days
- Favorited tasks: Never delete
For Experimentation:
- Default retention: 14 days
- Completed tasks: 14 days
- Incomplete tasks: 3 days
- Favorited tasks: Never delete
For Limited Disk Space:
- Default retention: 14 days
- Completed tasks: 14 days
- Incomplete tasks: 3 days
- Favorited tasks: 60 days
To ensure important tasks are never deleted:
- Mark tasks as favorites using the star icon in task history
- Enable "Never delete favorited tasks" in settings
- Review cleanup results periodically to ensure retention periods are appropriate
Consider these factors when setting retention periods:
- Available disk space: Shorter retention if space is limited
- Task frequency: More tasks = shorter retention needed
- Reference needs: Keep completed tasks longer if you often refer back
- Experimentation: Shorter incomplete task retention for heavy experimentation
Issue: Old tasks remain after cleanup runs
Solutions:
- Verify Auto-Cleanup is enabled in settings
- Check retention periods - they may be too long
- Verify tasks are older than the retention period
- Check if tasks are favorited (they won't be deleted if "Never delete" is enabled)
Issue: A task you needed was removed
Prevention:
- Always favorite important tasks before they age out
- Set longer retention periods for task types you reference frequently
- Consider enabling "Never delete favorited tasks"
- Export or backup critical task data before it ages out
Warning: Deleted tasks cannot be recovered. Always favorite important tasks or adjust retention periods to prevent accidental deletion.
Issue: Cleanup operation impacts system performance
Solutions:
- Check the "Operation duration" in cleanup results
- If slow, consider reducing retention periods to clean fewer tasks at once
- Run manual cleanup during non-working hours
- Ensure adequate system resources during cleanup
Auto-Cleanup automatically protects your currently active task from deletion, even if it meets the age criteria. This ensures you never lose work in progress during a cleanup operation.
When a task is deleted, the following are permanently removed:
- Task directory and all contents
- Conversation history and messages
- Checkpoints (if enabled)
- API request logs
- Task metadata
- Associated temporary files
Task data is stored in your VS Code global storage location:
- macOS:
~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/ - Windows:
%APPDATA%\Code\User\globalStorage\kilocode.kilo-code\ - Linux:
~/.config/Code/User/globalStorage/kilocode.kilo-code/
- Local Operation: All cleanup happens locally on your machine
- No Cloud Backup: Deleted tasks are not backed up automatically
- Telemetry: Anonymous usage statistics (tasks cleaned, disk space freed) are collected if telemetry is enabled
- No Content Sharing: Task content, code, or personal information is never transmitted
- Checkpoints: Version control for tasks that can be restored
- Settings Management: Export/import settings including cleanup configuration
- Task History: Managing and organizing your task history
Yes, when enabled, Auto-Cleanup runs automatically based on the configured schedule. You can also trigger it manually using the "Run Cleanup Now" button.
No, task deletion is permanent. Always favorite important tasks or adjust retention periods to prevent accidental deletion.
No, the active task you're currently working on is automatically protected from deletion.
All checkpoints associated with a deleted task are permanently removed along with the task data.
Yes, simply uncheck the "Enable automatic task cleanup" option in settings. Your configuration is preserved for when you enable it again.
Check if they are:
- Favorited with "Never delete favorited tasks" enabled
- Recently modified (even viewing a task may update its timestamp)
- Protected by a longer retention period based on their type