Skip to content

fix(cli): show every cache folder and its size in gaia cache status - #7132

Merged
kovtcharov-amd merged 4 commits into
amd:mainfrom
ityashag:fix/cache-status-every-cache
Nov 10, 2026
Merged

fix(cli): show every cache folder and its size in gaia cache status#7132
kovtcharov-amd merged 4 commits into
amd:mainfrom
ityashag:fix/cache-status-every-cache

Conversation

@ityashag

@ityashag ityashag commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Summary

gaia cache status now lists every cache GAIA keeps under ~/.gaia/cache, each with its size and file count, largest first. Before, it showed only Context7, with no sizes, so it couldn't answer "what is using my disk", which is what the CLI reference says it does.

Why

The issue's audit ran gaia cache status against the CLI reference and found the reference promised sizes and every cache directory. The reference also gave a Windows path (%LOCALAPPDATA%) that GAIA doesn't use; caches live under ~/.gaia/cache/ on every platform.

Linked issue

Closes #3221

Changes

  • gaia cache status lists each cache folder with size and file count, plus a total, then the Context7 sections as before. It doesn't follow symlinks, so a link out of the cache can't inflate the size or walk the disk.
  • The CLI reference matches the command: the real cache location, what status prints, and that clear (including --all) only clears Context7 today. Whether clear --all should cover the other caches is left to the maintainers.
  • gaia init's vision-profile hint said to run gaia cache status to check the vision model is available, which it never showed. It now points to gaia download --list --agent vlm.

Test plan

Run in a python:3.12 container:

  • pytest tests/unit/test_cache_status_cli.py: 6 passed. The 3 new tests fail on main.
  • Full pytest tests/unit: 38,401 passed, 584 skipped, 15 failed, of 38,904 collected, with no crashed workers. The 15 fail the same way on main in this container: 14 shell-guardrail and skill-grant tests refuse gh and npm because neither is installed there, and one expects a folder it can't create, but the container runs as root. 44 tests have :: inside their parameters, so they were rerun by file to account for them.
  • python util/lint.py --all: passes.

Evidence

gaia cache status on a real ~/.gaia (sizes from that machine):

=== GAIA caches (~/.gaia/cache) ===
  rag                3.5 MB        2 files
  factory            1.0 MB        1 file
  context7          40.9 KB        3 files
  llamacpp-arch      2.0 KB        1 file
  Total              4.5 MB        7 files

=== Context7 Service Status ===
...

On main the same command prints only the Context7 sections.

  • Agent exposed in the Agent UI: N/A
  • MCP tools / servers: N/A
  • CLI: output above.
  • HTTP API / REST: N/A

Checklist

  • I have linked a GitHub issue above (Closes #N / Fixes #N / Refs #N).
  • I have described why this change is being made, not just what changed.
  • I have run linting and tests locally (python util/lint.py --all, pytest tests/unit/).
  • I have attached real-world evidence matched to the surface I changed (see Evidence above), or marked each surface N/A.
  • I have updated documentation if user-visible behavior changed (see CONTRIBUTING.md).

@ityashag
fix(cli): show every cache folder and its size in gaia cache status
478a876 
gaia cache status listed only Context7, with no sizes, so it could not
answer what is using the disk, which the CLI reference says it does.

It now lists each folder under GAIA's cache root with its size and file
count, largest first, then the Context7 sections. It doesn't follow
symlinks. The CLI reference gives the real cache location and says that
clear only covers Context7 today, and gaia init's vision-profile hint
points to gaia download --list --agent vlm instead.

Closes amd#3221
@github-actions github-actions Bot added documentation Documentation changes cli CLI changes tests Test changes labels Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Verdict: Approve with suggestions

gaia cache status now lists every folder in GAIA's cache with its size and file count, so it finally answers "what is using my disk", which is what the CLI reference promised. The reference, the --help text and the vision-profile hint in gaia init all now match what the command does. Nothing blocks the merge.

One small honesty gap: if a folder inside the cache can't be opened, its contents are silently left out of the size, even though unreadable files are flagged. Counting that folder in the same "unreadable" note would keep the total from quietly under-reporting.

Real-world evidence

N/A here: this run produced no evidence bundle. The PR description includes real gaia cache status output from a populated ~/.gaia and says that on main the same command prints only the Context7 sections. That matches the CLI surface this change touches. I couldn't run the tests in this environment (pytest isn't installed), so the verdict rests on static review plus the author's evidence.

🔍 Technical details

Issues found

🟢 Folders that can't be listed are dropped without a note (src/gaia/cli.py:8038). os.walk(..., onerror=lambda _e: None) skips a subdirectory that raises PermissionError. Its bytes and files vanish from the row and the total, while an unreadable file in the same folder is reported as (N unreadable). Count both the same way:

    size = files = 0
    unreadable = []

    def _skip(_err: OSError) -> None:
        unreadable.append(_err)

    for dirpath, _dirnames, filenames in os.walk(folder, onerror=_skip):
        for name in filenames:
            try:
                stat = os.lstat(os.path.join(dirpath, name))
            except OSError:
                unreadable.append(None)
                continue
            size += stat.st_size
            files += 1
    return size, files, len(unreadable)

🟢 A top-level cache file deleted between iterdir() and entry.lstat() raises FileNotFoundError (src/gaia/cli.py:8066). The outer except Exception then aborts the whole status with ❌ Error. This only happens if another process is writing the cache at that moment. Wrapping the call in try/except OSError and counting the entry as unreadable would keep the rest of the report.

Checks done

  • Sibling paths: the Context7 cache resolves to gaia_home() / "cache" / "context7" (context7_cache.py:59), the same root the new listing uses, so GAIA_HOME is honoured on both. On a cold start the listing correctly prints "No caches yet."
  • Doc drift: the old %LOCALAPPDATA%/gaia/cache/ claim and the "--all removes every cache directory" claim appear nowhere else in docs/, hub/ or README.md. The only other mention is a planning note in docs/plans/claude-session-harvest.md, which is fine.
  • The new gaia init hint gaia download --list --agent vlm is valid: --list routes through get_agent_profile("vlm"), which exists in AGENT_PROFILES.

Strengths

  • The listing doesn't follow symlinks at the top level or inside folders, so a link to ~/.gaia/models can't inflate the numbers or walk the disk. A test covers this.
  • The tests check the exact rows, ordering and singular/plural output against a real temp tree under GAIA_HOME, not a mock.
  • The hint in gaia init that sent vision users to a command that never showed the model is fixed, not just the docs.

ityashag and others added 3 commits November 10, 2026 18:37
@ityashag
fix(cli): count unreadable cache folders and files removed mid-listing
7b22a7c 
A cache folder that couldn't be read dropped out of the size without a
note, while unreadable files were flagged. A top-level file removed while
the listing ran aborted the whole report. Both are now counted as
unreadable and the rest of the report still prints.
@ityashag
Merge branch 'main' into fix/cache-status-every-cache
d606d02
@ityashag
Merge branch 'main' into fix/cache-status-every-cache
4708cf9
@kovtcharov-amd
kovtcharov-amd added this pull request to the merge queue Nov 10, 2026
Merged via the queue into amd:main with commit a8fd61a Nov 10, 2026
58 checks passed
@kovtcharov kovtcharov mentioned this pull request Nov 11, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kovtcharov-amd kovtcharov-amd Awaiting requested review from kovtcharov-amd kovtcharov-amd is a code owner

Assignees

No one assigned

Labels

cli CLI changes documentation Documentation changes tests Test changes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

gaia cache status reports only the Context7 cache and prints no sizes, contradicting size and location of each cache directory

2 participants

@ityashag @kovtcharov-amd