The cache #

View this page as Markdown

The cache is a copy of your space's issues, kept as files on your computer, that your AI searches with its own file tools before it calls the server. There is one cache per project per computer, shared by every session working there.

The cache needs 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 there your AI keeps no cache and reads the space live. In the Claude desktop app, the Code tab can.

Where it stands #

The cache is a folder named cache:

  • In a Git repository, it is local/tztrack/cache/ under the folder git rev-parse --git-common-dir prints. Every worktree of a clone shares it, and nothing commits it.
  • Anywhere else, it is .tztrack/cache/ in the project's folder.

What it holds #

  • issues/<number>.md, one file per issue, open or closed, with the issue's state on its first line, state: open for example. The file holds the issue's fields, its title, its reports, comments, relations, and history, and its landings and checks. No line is longer than 200 characters, so a search tool reads it whole.
  • index.md, which lists the open issues under their areas. Its first line gives the instant the archive was taken, and its second line gives the writer: writer: tztrack where the server wrote it.

The files show a reporter by its kind alone, never by an identifier, and hold no lease and no report fingerprint. A restricted issue is in the folder like any other, marked restricted in its file and in the index. A restricted issue's title and text go into nothing committed to Git.

How it is filled #

The cache tool answers with a fresh link for your AI alone, which lasts ten minutes. The link gives the space's issues as one archive, a gzip-compressed tar. Your AI downloads it with curl and unpacks it with tar over the cache folder. Both ship with Windows 10 and later, macOS, and Linux, so no Node and no install is needed.

The archive holds index.md last. An unpack that stops partway leaves the old index, so a partial cache only looks old.

How it is refreshed #

To refresh, your AI asks cache what changed since the instant at the top of index.md. The answer gives the count of changed issues, their numbers, and the numbers no longer answered. It also gives a link to an archive of only the changed issues and a fresh index. Your AI deletes the files of the numbers no longer answered and unpacks the archive over the folder. A refresh always overwrites, and the fresh index lists every open issue of the space.

How it is read #

Your AI searches the cache with its own file tools first. Before it changes an issue, it reads the issue live with read, since another session may have changed it since the cache was taken.

When the cache's index.md gives another writer, your AI only reads that cache and never downloads into it. An AI that cannot run commands skips the cache and reads live. Each download counts in the space's rate as a call does, and a link older than ten minutes no longer works.