Log Keeper: install, deploy and operate

1. Why it is needed: the logs vanish

AI coding agents (Claude Code, OpenAI Codex, Cursor, GitHub Copilot CLI, Gemini CLI, Google Antigravity) write a session log on the developer's machine. The log records what the agent was asked, every command it ran, the files it touched and the hosts it contacted. It is the only record of what the agent did on that machine.

The agents own those logs and remove them on their own schedule:

• Claude Code deletes session transcripts after 30 days by default. The deletion runs as a background sweep after a session starts and shows no message. The setting is cleanupPeriodDays (default 30, minimum 1); sub-agent transcripts are removed with their parent session. Source: Claude Code documentation, settings reference and application data, cleaned up automatically. Sessions started or last continued in Claude Desktop or Cowork are kept at any age unless desktopSessionCleanupPeriodDays is set.
• The other agents' retention is set by each vendor and can change between versions. The keeper does not depend on it.
• Any user can delete the logs at any time; they are ordinary files in the user's home folder.

A review, an audit or an incident investigation that starts more than a month after the event will usually find the agent's record gone. The Log Keeper copies each machine's agent logs, on a schedule, into a keep folder before the agents remove them. The AI Agent Tracer reads a keep folder exactly as it reads the live logs.

2. What the keeper copies

Only folders that exist are read. The keeper reads the sources and never modifies or deletes them.

3. How it copies

• Layout. Each machine writes to its own subfolder, <keep folder>/<host>-<user>/, mirroring the source paths (.claude/projects/…, .codex/sessions/…). Several machines can share one keep folder.
• Incremental. A file is copied when it is new or its size or modification time has changed since the last copy; unchanged files are skipped.
• Compressed. Log files are stored xz-compressed as .jsonl.xz (the agents' own JSONL format, one record per line). Database files (state.vscdb, Antigravity .db) are copied unchanged. Compression can be turned off with --no-compress.
• Compaction (optional). --compact replaces every base64 run of 2,000 characters or more (embedded screenshots and context snapshots) with a short marker. The JSON stays valid and every command and message is kept.
• Never deletes. Nothing is ever removed from the keep folder. A log the agent later deletes stays kept, and the manifest marks its source as gone.
• Manifest. codedelta-keep-manifest.json in each machine folder records, per file, the source path, original size and modification time, the SHA-256 of the original, the kept path and size, and the time kept; and, per run, the counts copied and skipped and any refusal.
• Lock. One run per machine folder at a time (.codedelta-keep.lock); a lock older than 6 hours is treated as left by a crash and taken over.

4. Safeguards

• Disk floor. With less than 10 GB free on the keep volume the keeper copies nothing and reports why. It warns below 20 GB free, and when the current growth rate would fill the volume within 90 days.
• Unmounted volume. A keep folder under /Volumes/<name> (macOS) whose volume is not mounted, or on a Windows drive letter that does not exist, is refused; nothing is written to the boot disk in its place.
• Unreadable manifest. If a machine's manifest exists but cannot be read, the run stops and changes nothing, so the record of earlier copies is never replaced.
• Protected folders are refused (next section).

5. Choosing the keep folder: protected folders cannot be used

The scheduled job runs in the background without a window. Operating-system file protection blocks it in certain folders: on macOS a background job was refused files the app itself had written in Desktop and iCloud Drive, with Full Disk Access granted. The keeper therefore refuses these folders in the app (Save, Keep now, Keep automatically), on the command line and in the scheduled job, and nothing is saved, created, copied or scheduled there:

Use a folder directly in the user's home folder, for example ~/tracer logs. On macOS, a background job wrote to such a folder without any permission grant. Include that folder in the machine's normal backup so a copy also exists off the machine.

6. Requirements

• CodeDelta with the Log Keeper: version 2.2.1 or later.
• No licence is needed for the keeper. A lapsed licence never stops logs being kept.
• The keeper runs as the user whose agent logs it copies. It needs read access to that user's agent folders and write access to the keep folder.
• 10 GB or more free on the keep volume.

7. Install on one machine (the app)

1. Open CodeDelta and choose AI Agent Tracer mode. The Log keeper line is under the folder field.
2. Enter or select the keep folder (not a protected folder) and choose Keep images (full copy, compressed) or Maximise compaction. Press Save.
3. Press Keep now for a first copy. A first copy of several hundred MB of logs takes a minute or two; Stop ends it and what is already kept stays.
4. Choose when to keep automatically and tick Keep automatically:
   • after log-in, waiting N minutes (0–240, default 15) — for machines switched off at night;
   • daily at HH:MM — for machines left on or asleep.

The status line shows the last copy (files copied and unchanged, space used, free space, growth rate), the schedule and the folder the automatic job writes to. Saving a new folder or mode moves the installed job to it. Remove keeper removes the automatic job and the setting; kept files are never deleted.

8. Schedules and what each platform installs

The wait after log-in is carried in the job's command as --wait N. Installing a schedule replaces any earlier keeper job for that user.

9. Command line

The program: macOS /Applications/CodeDelta.app/Contents/Resources/codedelta-gui/codedelta-gui; Windows C:\Program Files\CodeDelta\codedelta-gui.exe (default install folder); Linux codedelta-gui in the extracted bundle. Below, codedelta-gui stands for that path.

Exit code 0: the run completed. Exit code 2: refused or failed (protected folder, disk floor, unmounted volume, unreadable manifest, files not kept, invalid schedule), with the reason on standard error.

10. Deploying to many machines

The scheduled job is per user: it is installed in the user's own scheduler and copies that user's logs. Deploy the application as usual, then run the install command in the context of each user (not as root or SYSTEM), for example from your device-management tool's user-context script or a log-in script:

The same command with --remove-nightly removes the job. The keeper writes to a folder and has no network code; to collect copies centrally, point the keep folder at a location your existing backup or file-collection tooling already gathers.

11. Checking that it runs

12. Reading the kept logs

A keep folder is a normal AI Agent Tracer input. Select it as the agent-logs folder in the app, or run:

The report reads the compressed files directly and states in its header that it was produced from a keep folder and the date the copies run to. A keep folder holding several machines' subfolders produces one report across all of them.

13. Limits of this version

• The job and the settings belong to the user. A user can change the keep folder, remove the job, or edit or delete kept files and the manifest. There is no administrator lock in this version.
• The SHA-256 values in the manifest show whether a kept file still matches the original; they do not prevent changes, because the manifest is in the same folder.
• No direct upload to cloud storage (S3, Azure Blob, Google Cloud Storage) in this version.
• Only the six agents in section 2 are covered.