---
title: "Check for new versions at most once a day · Agent Wranglers"
url: https://agentwranglers.se/playbook/developer-tools/help-completion-and-updates/version-check
id: DEV-17
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1129
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Check for new versions at most once a day and never in scripts

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Help, completion and updates](https://agentwranglers.se/playbook/developer-tools/help-completion-and-updates.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: DEV-17
- Level: Recommended
- Chapter: [Help, completion and updates](https://agentwranglers.se/playbook/developer-tools/help-completion-and-updates.md)
- Rule: Look for a newer version at most once per 24 hours and cache the answer. Skip the check when `CI` is set, when standard output or standard error is not a terminal, or when the opt-out variable is set. The check never delays or fails the command.
- Check: A test runs a command three times within an hour against a fake release server, which gets 1 request. With `CI=true`, with output piped or with `EXAMPLE_NO_UPDATE_CHECK=1`, it gets 0 requests. With a release server that never answers, the command ends within 1 second of its usual time with its usual exit code. The notice never appears on standard output.
- How: A tool that calls home on every run slows scripts, breaks offline work and floods the release server. Run the check in the background with a 2 second time limit, or show the answer cached from the last check. Store the cache under `$XDG_CACHE_HOME`, as [Read settings in one documented order from standard folders](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/config-precedence.md) says. Print the notice to standard error after the command's own output. JSON on standard output then stays clean, as [Write results to stdout and everything else to stderr](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/stdout-stderr.md) says. Name the upgrade command for the way the tool was installed, such as `brew upgrade example`. Never update without asking. A tool that updates itself verifies the download as [Verify every update's signature before installing it](https://agentwranglers.se/playbook/desktop-apps/update-integrity/signed-updates.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
import { isatty } from 'node:tty'

const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000

function shouldCheckForUpdate(env, cache, now = Date.now()) {
  if (env.CI || env.EXAMPLE_NO_UPDATE_CHECK === '1') return false
  if (!isatty(1) || !isatty(2)) return false
  return !cache.checkedAt || now - cache.checkedAt >= CHECK_INTERVAL_MS
}
```

### Python example

```python
import os, sys, time

CHECK_INTERVAL_SECONDS = 24 * 60 * 60

def should_check_for_update(cache, env=os.environ, now=None) -> bool:
    if env.get("CI") or env.get("EXAMPLE_NO_UPDATE_CHECK") == "1":
        return False
    if not (sys.stdout.isatty() and sys.stderr.isatty()):
        return False
    now = now or time.time()
    return cache.checked_at is None or now - cache.checked_at >= CHECK_INTERVAL_SECONDS
```

## Related rules

- DEV-14 [Read settings in one documented order from standard folders](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/config-precedence.md) in Developer tools, SDKs and CLIs
- DEV-2 [Write results to stdout and everything else to stderr](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/stdout-stderr.md) in Developer tools, SDKs and CLIs
- DSK-6 [Verify every update's signature before installing it](https://agentwranglers.se/playbook/desktop-apps/update-integrity/signed-updates.md) in Desktop apps and extensions

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/developer-tools/help-completion-and-updates/version-check">Agent Wranglers developer tools, SDKs and CLIs playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Ship shell completion generated from the command definitions](https://agentwranglers.se/playbook/developer-tools/help-completion-and-updates/shell-completion.md)
- [Help, completion and updates](https://agentwranglers.se/playbook/developer-tools/help-completion-and-updates.md)