Skip to content

Commit eee74ca

Browse files
catrielmullercatrielmuller
committed
feat: auto cleanup documentation
1 parent 8cdf510 commit eee74ca

File tree

3 files changed

+277
-1
lines changed

3 files changed

+277
-1
lines changed

‎.changeset/yellow-monkeys-tease.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
"kilo-code": minor
33
---
44

5-
Auto Cleanup Task History
5+
Auto Cleanup automatically manages your task history by removing old tasks to free up disk space and improve performance - https://kilocode.ai/docs/advanced-usage/auto-cleanup

‎apps/kilocode-docs/docs/advanced-usage/auto-cleanup.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# Auto Cleanup
2+
3+
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.
4+
5+
:::warning Important
6+
Task deletion is permanent and cannot be undone. Deleted tasks are completely removed from disk, including all conversation history, checkpoints, and associated files.
7+
:::
8+
9+
## Overview
10+
11+
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:
12+
13+
- **Automatically removing old tasks** based on configurable retention periods
14+
- **Preserving important tasks** by classifying them into different types
15+
- **Protecting favorited tasks** from deletion
16+
- **Managing disk usage** without manual intervention
17+
18+
:::info Key Benefits
19+
20+
- **Free up disk space**: Automatically remove old task data
21+
- **Improve performance**: Reduce the size of task history
22+
- **Flexible control**: Configure different retention periods for different task types
23+
- **Safety first**: Favorited tasks can be protected from deletion
24+
- **Manual override**: Run cleanup manually whenever needed
25+
:::
26+
27+
## How Auto-Cleanup Works
28+
29+
Auto-Cleanup uses an intelligent classification system to determine how long each task should be retained:
30+
31+
### Task Classification
32+
33+
Every task is automatically classified into one of these categories:
34+
35+
| Task Type | Description | Default Retention |
36+
| -------------- | ----------------------------------------- | ---------------------------------------- |
37+
| **Favorited** | Tasks you've marked as favorites | Never deleted (or 90 days if configured) |
38+
| **Completed** | Tasks that successfully finished | 30 days |
39+
| **Incomplete** | Tasks that were started but not completed | 7 days |
40+
| **Regular** | Default classification for other tasks | 30 days |
41+
42+
#### Understanding Task Completion
43+
44+
A task is considered "completed" when Kilo Code uses the [`attempt_completion`](../features/tools/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.
45+
46+
### Cleanup Process
47+
48+
When Auto-Cleanup runs, it:
49+
50+
1. **Scans all tasks** in your task history
51+
2. **Classifies each task** based on its properties and completion status
52+
3. **Checks retention periods** to determine eligibility for deletion
53+
4. **Protects active tasks** currently in use
54+
5. **Deletes eligible tasks** and their associated files
55+
6. **Reports results** including disk space freed
56+
57+
## Configuration
58+
59+
Access Auto-Cleanup settings through the Kilo Code settings panel:
60+
61+
1. Click the gear icon (<i class="codicon codicon-gear"></i>) in Kilo Code
62+
2. Navigate to the **Auto-Cleanup** section (under Checkpoints)
63+
64+
### Enable Auto-Cleanup
65+
66+
<img src="/docs/img/auto-cleanup/settings.png" alt="Auto-Cleanup settings panel" width="600" />
67+
68+
Check the **"Enable automatic task cleanup"** option to activate the feature. When enabled, tasks will be automatically removed based on your retention settings.
69+
70+
### Retention Period Settings
71+
72+
Configure how long different types of tasks are kept before cleanup:
73+
74+
#### Default Retention Period
75+
76+
```
77+
Default: 30 days
78+
Minimum: 1 day
79+
```
80+
81+
Sets the base retention period for regular tasks that don't fall into other categories.
82+
83+
#### Favorited Tasks
84+
85+
**Never delete favorited tasks** (recommended)
86+
87+
When enabled, favorited tasks are preserved indefinitely regardless of age. This is the safest option to prevent accidental deletion of important work.
88+
89+
If disabled, you can set a custom retention period:
90+
91+
```
92+
Default: 90 days
93+
Minimum: 1 day
94+
```
95+
96+
To favorite a task, use the star icon in the task history panel.
97+
98+
#### Completed Tasks
99+
100+
```
101+
Default: 30 days
102+
Minimum: 1 day
103+
```
104+
105+
Tasks successfully completed via the [`attempt_completion`](../features/tools/attempt-completion) tool are retained for this period. These tasks typically represent finished work that may still be useful for reference.
106+
107+
#### Incomplete Tasks
108+
109+
```
110+
Default: 7 days
111+
Minimum: 1 day
112+
```
113+
114+
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.
115+
116+
### Last Cleanup Display
117+
118+
The settings show when the last cleanup operation ran, helping you understand the cleanup schedule.
119+
120+
### Manual Cleanup
121+
122+
Click the **"Run Cleanup Now"** button to immediately trigger a cleanup operation using your current settings. This is useful when:
123+
124+
- You need to free up disk space urgently
125+
- You've changed retention settings and want them applied immediately
126+
- You want to preview what would be cleaned up (check the output)
127+
128+
## Best Practices
129+
130+
### Recommended Retention Periods
131+
132+
**For Individual Developers:**
133+
134+
- Default retention: 30 days
135+
- Completed tasks: 30 days
136+
- Incomplete tasks: 7 days
137+
- Favorited tasks: Never delete
138+
139+
**For Experimentation:**
140+
141+
- Default retention: 14 days
142+
- Completed tasks: 14 days
143+
- Incomplete tasks: 3 days
144+
- Favorited tasks: Never delete
145+
146+
**For Limited Disk Space:**
147+
148+
- Default retention: 14 days
149+
- Completed tasks: 14 days
150+
- Incomplete tasks: 3 days
151+
- Favorited tasks: 60 days
152+
153+
### Protecting Important Work
154+
155+
To ensure important tasks are never deleted:
156+
157+
1. **Mark tasks as favorites** using the star icon in task history
158+
2. **Enable "Never delete favorited tasks"** in settings
159+
3. **Review cleanup results** periodically to ensure retention periods are appropriate
160+
161+
### Balancing Disk Space and History
162+
163+
Consider these factors when setting retention periods:
164+
165+
- **Available disk space**: Shorter retention if space is limited
166+
- **Task frequency**: More tasks = shorter retention needed
167+
- **Reference needs**: Keep completed tasks longer if you often refer back
168+
- **Experimentation**: Shorter incomplete task retention for heavy experimentation
169+
170+
## Troubleshooting
171+
172+
### Tasks Not Being Cleaned Up
173+
174+
**Issue**: Old tasks remain after cleanup runs
175+
176+
**Solutions**:
177+
178+
1. Verify Auto-Cleanup is enabled in settings
179+
2. Check retention periods - they may be too long
180+
3. Verify tasks are older than the retention period
181+
4. Check if tasks are favorited (they won't be deleted if "Never delete" is enabled)
182+
183+
### Important Task Was Deleted
184+
185+
**Issue**: A task you needed was removed
186+
187+
**Prevention**:
188+
189+
1. Always favorite important tasks before they age out
190+
2. Set longer retention periods for task types you reference frequently
191+
3. Consider enabling "Never delete favorited tasks"
192+
4. Export or backup critical task data before it ages out
193+
194+
:::warning
195+
Deleted tasks cannot be recovered. Always favorite important tasks or adjust retention periods to prevent accidental deletion.
196+
:::
197+
198+
### Cleanup Using Too Much Disk I/O
199+
200+
**Issue**: Cleanup operation impacts system performance
201+
202+
**Solutions**:
203+
204+
1. Check the "Operation duration" in cleanup results
205+
2. If slow, consider reducing retention periods to clean fewer tasks at once
206+
3. Run manual cleanup during non-working hours
207+
4. Ensure adequate system resources during cleanup
208+
209+
### Active Task Protection
210+
211+
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.
212+
213+
## Technical Details
214+
215+
### What Gets Deleted
216+
217+
When a task is deleted, the following are permanently removed:
218+
219+
- Task directory and all contents
220+
- Conversation history and messages
221+
- Checkpoints (if enabled)
222+
- API request logs
223+
- Task metadata
224+
- Associated temporary files
225+
226+
### Storage Location
227+
228+
Task data is stored in your VS Code global storage location:
229+
230+
- **macOS**: `~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/`
231+
- **Windows**: `%APPDATA%\Code\User\globalStorage\kilocode.kilo-code\`
232+
- **Linux**: `~/.config/Code/User/globalStorage/kilocode.kilo-code/`
233+
234+
## Privacy & Data Handling
235+
236+
- **Local Operation**: All cleanup happens locally on your machine
237+
- **No Cloud Backup**: Deleted tasks are not backed up automatically
238+
- **Telemetry**: Anonymous usage statistics (tasks cleaned, disk space freed) are collected if telemetry is enabled
239+
- **No Content Sharing**: Task content, code, or personal information is never transmitted
240+
241+
## Related Features
242+
243+
- [**Checkpoints**](../features/checkpoints): Version control for tasks that can be restored
244+
- [**Settings Management**](../features/settings-management): Export/import settings including cleanup configuration
245+
- [**Task History**](../basic-usage/the-chat-interface): Managing and organizing your task history
246+
247+
## Frequently Asked Questions
248+
249+
### Does Auto-Cleanup run automatically?
250+
251+
Yes, when enabled, Auto-Cleanup runs automatically based on the configured schedule. You can also trigger it manually using the "Run Cleanup Now" button.
252+
253+
### Can I recover deleted tasks?
254+
255+
No, task deletion is permanent. Always favorite important tasks or adjust retention periods to prevent accidental deletion.
256+
257+
### Does cleanup affect my current task?
258+
259+
No, the active task you're currently working on is automatically protected from deletion.
260+
261+
### What happens to checkpoints when a task is deleted?
262+
263+
All checkpoints associated with a deleted task are permanently removed along with the task data.
264+
265+
### Can I temporarily disable cleanup?
266+
267+
Yes, simply uncheck the "Enable automatic task cleanup" option in settings. Your configuration is preserved for when you enable it again.
268+
269+
### Why are some old tasks not being deleted?
270+
271+
Check if they are:
272+
273+
1. Favorited with "Never delete favorited tasks" enabled
274+
2. Recently modified (even viewing a task may update its timestamp)
275+
3. Protected by a longer retention period based on their type

‎apps/kilocode-docs/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@ const sidebars: SidebarsConfig = {
150150
],
151151
},
152152
"features/auto-launch-configuration",
153+
"advanced-usage/auto-cleanup",
153154
"features/experimental/experimental-features",
154155
],
155156
},

0 commit comments

Comments
 (0)