feat(cli): add dimos cache clean

[TomCC7]

Contribution path

• Small, safe change that does not need a tracking issue
• Follow-up for robot asset caching in feat: in-house robot asset manager #2505

Problem

DimOS writes regenerable assets to several unrelated platform, state, and temporary directories, but users have no single command to clear them. This becomes more important with #2505, which adds cached robot source checkouts and derived URDFs.

Solution

Move all DimOS-owned caches beneath the platform-specific CACHE_DIR, then add dimos cache clean to remove that hierarchy.

The command:

• preserves logs, recordings, datasets, configuration, and third-party caches;
• refuses to clean while a DimOS run is active unless --force is supplied;
• preserves robot asset Git checkouts with local changes or local-only commits unless forced;
• displays the cache root and deletion policy, then requires y/N confirmation by default;
• supports non-interactive cleanup with --yes, independently of --force;
• reports filesystem failures and incomplete cleanup with a nonzero exit code; and
• centralizes cache paths so cache writers and the CLI use the same locations.

How to Test

dimos cache clean
uv run pytest dimos/utils/test_cache.py dimos/robot/cli/test_dimos.py dimos/robot/cli/test_cli_startup.py dimos/utils/test_ament_prefix.py -q

AI assistance

OpenAI Codex with GPT-5 implemented and tested the change under the author's direction.

Checklist

• I have read and approved the CLA.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟢 Ready	View Preview	Jul 25, 2026, 4:12 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[codecov]

Codecov Report

❌ Patch coverage is 97.20280% with 8 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/robot/cli/cache.py	93.87%	3 Missing ⚠️
dimos/utils/cache.py	97.33%	2 Missing ⚠️
dimos/utils/test_cache.py	96.66%	1 Missing and 1 partial ⚠️
dimos/utils/ament_prefix.py	50.00%	1 Missing ⚠️

@@            Coverage Diff             @@
##             main    #3178      +/-   ##
==========================================
- Coverage   74.17%   73.78%   -0.39%     
==========================================
  Files        1108     1113       +5     
  Lines      104052   104660     +608     
  Branches     9530     9595      +65     
==========================================
+ Hits        77179    77223      +44     
- Misses      24129    24741     +612     
+ Partials     2744     2696      -48     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	67.79% <97.18%> (+0.14%)	⬆️
OS-ubuntu-latest	69.84% <97.20%> (+0.11%)	⬆️
Py-3.10	69.83% <97.20%> (+0.12%)	⬆️
Py-3.11	69.83% <97.20%> (+0.11%)	⬆️
Py-3.12	69.83% <97.20%> (+0.10%)	⬆️
Py-3.13	69.84% <97.20%> (+0.11%)	⬆️
Py-3.14	69.84% <97.20%> (+0.11%)	⬆️
Py-3.14t	69.83% <97.20%> (+0.11%)	⬆️
SelfHosted-Large	29.66% <38.46%> (+<0.01%)	⬆️
SelfHosted-Linux	36.06% <34.61%> (-0.17%)	⬇️
SelfHosted-macOS	?

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/manipulation/planning/utils/mesh_utils.py	35.93% <100.00%> (-25.00%)	⬇️
dimos/manipulation/visualization/viser/scene.py	83.17% <100.00%> (+0.03%)	⬆️
dimos/robot/cli/dimos.py	68.65% <100.00%> (+0.25%)	⬆️
dimos/robot/cli/test_cache.py	100.00% <100.00%> (ø)
dimos/robot/cli/test_dimos.py	100.00% <100.00%> (ø)
dimos/utils/deno.py	75.00% <100.00%> (+0.39%)	⬆️
dimos/utils/ament_prefix.py	85.71% <50.00%> (-6.35%)	⬇️
dimos/utils/cache.py	97.33% <97.33%> (ø)
dimos/utils/test_cache.py	96.66% <96.66%> (ø)
dimos/robot/cli/cache.py	93.87% <93.87%> (ø)

... and 35 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Greptile Summary

Adds a coordinated cache-cleaning command and centralizes regenerable assets beneath the platform cache directory.

• Adds dimos cache clean with confirmation, active-run detection, cleanup reporting, and non-interactive --yes support.
• Introduces file-based guards that prevent cache cleanup from overlapping dimos run startup or execution.
• Moves URDF, Viser, ament, and downloaded Deno artifacts beneath CACHE_DIR.
• Adds focused CLI and concurrency tests, documentation, and the filelock dependency.

Confidence Score: 5/5

The PR appears safe to merge, with no blocking failures remaining in the fixes related to the previous review threads.

The cleanup gate and per-run usage marker now mutually exclude cache deletion and run startup throughout the relevant lifecycle.

Important Files Changed

Filename	Overview
dimos/utils/cache.py	Implements cache deletion and a gate-plus-usage-lock protocol that closes the previously reported startup/cleanup race.
dimos/robot/cli/cache.py	Adds the cache-clean command with confirmation, active-run checks, guarded deletion, and explicit failure reporting.
dimos/robot/cli/dimos.py	Registers the cache subcommand and keeps the cache-usage marker around the complete dimos run lifecycle.
dimos/utils/ament_prefix.py	Relocates the generated ament prefix beneath the shared cache root.
pyproject.toml	Declares the bounded filelock runtime dependency used by the new coordination protocol.
uv.lock	Updates the frozen dependency graph consistently with the new direct dependency.

Sequence Diagram

sequenceDiagram
    participant Run as dimos run
    participant Gate as Cleanup gate lock
    participant Usage as Usage marker lock
    participant Clean as dimos cache clean
    participant Cache as CACHE_DIR

    Run->>Gate: acquire
    Run->>Usage: create and acquire marker
    Run-->>Gate: release
    Run->>Run: build and execute blueprint
    Clean->>Gate: wait to acquire
    Clean->>Usage: test existing markers
    Usage-->>Clean: locked / cache in use
    Clean-->>Clean: refuse cleanup
    Run-->>Usage: release and remove marker
    Clean->>Gate: acquire
    Clean->>Usage: verify no active markers
    Clean->>Cache: remove cache hierarchy
    Clean-->>Gate: release

Loading

_{Reviews (12): Last reviewed commit: "fix(cache): synchronize cleanup with run..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟡 Building	–	Jul 25, 2026, 4:11 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.