---
title: Manage the local cache
description: Let your AI download and refresh a local issue cache for faster searches. Learn the file layout, writer checks, and safe refresh steps.
slug: /reference/manage-the-local-cache
order: 8
visibility: public
redirects_from: []
---

# Manage the local cache

These instructions are for an AI tool managing a local issue cache. The person does not need to maintain its files. Download and refresh issue files for local searches, then read the current issue from tzTrack before making a change.

Caching is optional. If local commands, `curl`, or `tar` are unavailable, read issues directly from tzTrack.

The Turn Zero connection lists tzTrack tools with `tztrack_` before the name: `find` is `tztrack_find`. This page uses the shorter names. [The tools](/tztrack/reference/the-tools/) lists the full names.

## Prerequisites

- Confirm command access and check that `curl` and `tar` are available. In Windows PowerShell, use `curl.exe` to avoid its `curl` alias.
- Select the intended space and determine the cache folder before writing files.
- Read an existing `index.md`. Refresh it only if its second line is `writer: tztrack`; otherwise, read the cache without overwriting it.

## Steps

### 1. Find the folder

For a Git repository, run this from the project folder:

```text
git rev-parse --git-common-dir
```

Use `local/tztrack/cache/` under the reported common Git folder. Resolve a relative result from the directory where you ran the command. Worktrees share this cache. Outside Git, use `.tztrack/cache/` in the project folder.

Create the folder if needed. If its location cannot be determined safely, use live reads rather than guessing.

### 2. Download the issues

Call `cache` for a download link, valid for ten minutes. Replace the placeholders below. Run the download first and check that it succeeded before unpacking:

```text
curl -fsS -o tztrack-cache.tar.gz "<link>"
tar -xzf tztrack-cache.tar.gz -C "<cache folder>"
```

Treat the link as a credential and keep it out of reports. Delete the archive after a successful extraction. `index.md` comes last, but an extraction error still means the cache is incomplete; retry successfully or read live before using it.

### 3. Refresh the cache

The first line of `index.md` reads `# Issue cache, taken <timestamp>`. Extract only the timestamp and pass it as `since` to `cache`; do not pass the whole heading.

Download the returned archive and confirm success before changing local files. Delete `issues/<number>.md` for each issue the response says is no longer available, then extract the changed files and fresh index.

A refresh overwrites matching files. Confirm extraction succeeded before trusting the new index.

### 4. Read the cache

Search `index.md` and the issue files with your own file tools. The index lists open issues; each issue file starts with its state. Read the issue live with `read` before changing it, because another session may have updated it.

## Expected result

The folder contains one Markdown file per accessible issue, including closed issues, and an index of open issues. A successful refresh updates changed files, removes unavailable ones, and replaces the index.

## Refusals

Common refusals are below; [Refusals](/tztrack/reference/refusals/) lists the rest.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `rate_limited` | 429 | Too many requests; downloads also count. | Wait for the rate window to reset, then retry. |
| `invalid_request` | 400 | A field is invalid, such as a malformed `since`. | Pass the index's first-line timestamp as written. |
| `space_mismatch` | 403 | The account cannot access the selected space. | Check the space and sign-in. |
| `credential_required` | 401 | Sign-in is incomplete. | Complete sign-in through the AI tool. |

An expired link returns 401. Request a new one with `cache`; do not retry the old link indefinitely.

## Related

- [The cache](/tztrack/concepts/the-cache/) explains what the cache holds and why `index.md` comes last.
- [The tools](/tztrack/reference/the-tools/) lists `cache` and `read`.
- [Refusals](/tztrack/reference/refusals/) lists every refusal.