Artifacts & Patches

Caboose modifies files through structured tool calls — write_file for creating new files, and edit_file for targeted modifications to existing files. This page covers how edits are applied and how the system protects against unintended changes.

Edit mechanics

The edit_file tool uses a search-and-replace approach. The LLM provides an old_string (the exact text to find) and a new_string (the replacement). Caboose locates the match in the file and applies the substitution. If the old_string is not found or matches multiple locations, the edit fails with an error message sent back to the LLM so it can adjust.

This design avoids the fragility of line-number-based edits, which break when prior changes shift line numbers within the same turn.

Write operations

The write_file tool creates a new file or overwrites an existing one. The full file content is provided by the LLM. Caboose writes the content atomically — the file is written to a temporary location first, then renamed into place, preventing partial writes from corrupting files.

Checkpoints

Caboose takes snapshots before destructive operations so changes can be rolled back. The checkpoint system uses SQLite to store file state, allowing the session to track what was modified and restore previous versions if needed.

Tool output as artifacts

When tools return large outputs (file contents, command results, search results), these are treated as artifacts in the conversation. Each artifact is:

• Capped at 2,000 lines or 50 KB to prevent context window exhaustion
• Truncated with notice so the LLM knows data was omitted and can request targeted reads
• Pruned over time — after several turns, old tool outputs are replaced with [output truncated] to reclaim context space

This pruning is separate from conversation compaction. It specifically targets tool output blocks, which tend to be the largest consumers of context tokens.

File safety

All file operations respect the current permission mode. In Plan mode, writes are blocked entirely. In Create mode, every write requires explicit user approval through the TUI approval dialog. Only in Chug mode do writes execute without prompting.

Each tool operation reports structured results back to the agent loop, including success/failure status and any diagnostic information the LLM needs to proceed.