From a680c71a9df74cd8fe700f2726b19d3ea94db3f7 Mon Sep 17 00:00:00 2001 From: Alec Thomas Date: Tue, 13 Jan 2026 11:46:40 +1100 Subject: [PATCH] docs: add AGENTS.md --- AGENTS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..525fee8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +This codebase is a tiered, caching, protocol-aware, pass-through HTTP proxy. The cache is designed for software +engineering machines, in CI, interactive in the cloud, or locally. + +The cache server is tiered, in that it runs locally on workstations, but backs onto remote instances of the cache +server. If the local instance doesn't have an object, it will automatically fall back to the remote instance. + +Logically, it's broken up into two main components - cache backends, and caching strategies. Cache backends are object +stores with some extra metadata and per-object TTLs. Strategies are protocol-aware caching mechanisms. For example, the +github-releases strategy knows how to retrieve and cache private and public GitHub releases artefacts. Another strategy +example is for Git, where the proxy is aware of the Git protocol and uses it to reduce the impact on upstream Git +servers. + +The way the two components interact is that the strategies have access to a Cache implementation, which they use to +cache and restore data. Strategies are not limited to using the Cache though; for example the Git strategy could +keep a local bare checkout of upstream Git repositories and serve packs from the repo directly. + +The codebase uses Hermit to manage toolchains. It is written in Go, and uses Just for running common tasks.