Keep a local cache #

View this page as Markdown

Prompt:

Keep a local copy of our open issues so you can search them quickly.

Also works: "Cache the tzTrack issues on this machine." "Refresh the issue cache."

What your tool does #

  • Finds the cache folder for the project, and reads the instant at the top of its index.md if there is one.
  • Calls cache for a fresh link, downloads the archive with curl, and unpacks it with tar over the folder.
  • Refreshes by asking cache what changed since that instant, deleting the files of the numbers no longer answered, and unpacking the changed issues with a fresh index.
  • Searches the cache with its own file tools first, and reads an issue live with read before it changes it.

What you need #

  • A tool that runs commands on your computer, such as Claude Code or Codex. The chat in Claude and ChatGPT cannot reach files on your computer, so it keeps no cache. There, your AI reads the space live. In the Claude desktop app, the Code tab can.

Before your AI starts #

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

  • A shell with curl and tar, as Claude Code and Codex have. Both ship with Windows 10 and later, macOS, and Linux. Without one, as in Claude or ChatGPT, skip the cache and read live.
  • The cache folder. In a Git repository, it is local/tztrack/cache/ under the folder git rev-parse --git-common-dir prints; elsewhere it is .tztrack/cache/.
  • Whether the cache's index.md gives another writer on its second line. If it does, only read that cache, and never download into it.

Steps #

1. Find the folder #

In a Git repository, print the common folder:

git rev-parse --git-common-dir

The cache is local/tztrack/cache/ under the folder it prints. Elsewhere, the cache is .tztrack/cache/ in the project's folder. Create the folder if it does not exist.

2. Fill it #

Call cache for a fresh link. The link is yours alone and lasts ten minutes. Download the archive and unpack it over the folder, with the link in place of <link> and the folder in place of <cache folder>:

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

Delete the downloaded file once it is unpacked. The archive holds index.md last, so a partial unpack only looks old.

3. Refresh it #

Read the instant on the first line of index.md, and call cache with that instant as since. The answer gives the count, the numbers changed, and the numbers no longer answered. Delete issues/<number>.md for each number no longer answered. Then download and unpack the link's archive of the changed issues and a fresh index, as in step 2.

4. Read it #

Search index.md and the issues/ files with your own file tools first. The first line of each issue's file is its state, so grep -L "^state: closed" over a search's answers keeps the open ones. Read an issue live with read before you change it.

Expected result #

The cache folder holds index.md, with its instant on its first line, writer: tztrack on its second, and the open issues under their areas. It holds one issues/<number>.md per issue, its state on its first line. A refresh changes only the files of the issues that changed, and replaces the index.

Refusals #

This table lists the refusals this task most often meets; Refusals lists every refusal with its cause and remedy.

Refusal Status Cause Remedy
rate_limited 429 Too many calls within the minute: into the space, from your account on calls that work no space, or from one address with no valid sign-in. The detail names which. Each download counts in the space's rate. Wait for the minute to turn, then repeat the call.
invalid_request 400 Input is malformed or missing, or names something the server does not take. The detail names the member. In cache, it can be a since that is not an instant as index.md writes it. Correct the member the detail names, then repeat the call. For since, pass the first line's instant as written.
space_mismatch 403 The space named is not one your account owns or is a member of. Name a space your account owns or is a member of, or leave space out.
credential_required 401 The call carried no sign-in, or the sign-in did not finish. Sign in again through your tool.

A link older than ten minutes no longer answers: curl reports a 401. Call cache for a fresh one.

  • The cache explains what the cache holds and why index.md comes last.
  • The tools lists cache and read.
  • Refusals lists every refusal.