ai-limits 0.1.0__tar.gz

ai_limits-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agniv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_limits-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md
+recursive-include tests *.py *.json
+recursive-include docs *.md
+recursive-include gnome-extension *.md *.sh *.js *.json *.css *.xml

ai_limits-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: ai-limits
+Version: 0.1.0
+Summary: AI subscription usage limits (Claude, Codex) for your desktop panel. Offline by default.
+Author: jointsome0-lgtm
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jointsome0-lgtm/ai-limits
+Project-URL: Repository, https://github.com/jointsome0-lgtm/ai-limits
+Project-URL: Issues, https://github.com/jointsome0-lgtm/ai-limits/issues
+Project-URL: Documentation, https://github.com/jointsome0-lgtm/ai-limits#readme
+Keywords: claude,codex,usage,limits,gnome,offline,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ai-limits
+
+See how much of your AI subscriptions is left — Claude and Codex, any number of accounts — right
+in the GNOME top bar.
+
+```
+                                   ✳ 42%   ◎ 19%   Oct 27 15:49
+```
+
+```
+ Claude Max
+   Session (5h)   ████░░░░░░  42%   ↻ 18:30 (in 2h10m)
+   Week           ██░░░░░░░░  18%   ↻ Sun 19:00 (in 5d3h)
+ Codex · personal                         ★ most headroom
+   Week           ██░░░░░░░░  19%   ↻ Thu 12:00 (in 2d21h)
+ Codex · work                             updated 8h ago
+   Week           █████████░  91%   ↻ 18:00 (in 2h)
+```
+
+**Offline by default.** ai-limits reads only what Claude Code and Codex already saved on your
+machine. It sends no requests and does not read your tokens unless you turn on network mode, and
+network mode refuses to send anything unless the route goes through the VPN interface you name.
+
+> Unofficial. Not affiliated with Anthropic or OpenAI. The local formats and the usage endpoint it
+> reads are undocumented and may change.
+
+## Install
+
+```sh
+uv tool install ai-limits        # or: pipx install ai-limits
+ai-limits                       # check it sees your accounts
+```
+
+For the optional GNOME Shell 45–49 extension, install from a checkout (it is not in the wheel):
+
+```sh
+git clone https://github.com/jointsome0-lgtm/ai-limits.git
+cd ai-limits
+./gnome-extension/install.sh
+```
+
+### Platforms
+
+Python **3.11–3.14**, with no runtime dependencies. On distributions with an older system Python
+(e.g. Ubuntu 22.04 ships 3.10), use `uv tool install ai-limits`: uv fetches a suitable Python itself.
+**Linux** supports the offline CLI,
+Claude tap, and VPN-guarded network mode (`ip` from iproute2 is required for network mode).
+**macOS and Windows** support the offline CLI and Claude tap; network mode refuses to run
+there, before reading credentials or looking up the host. The GNOME extension is Linux-only.
+
+Config and cache use `~/.config/ai-limits` and `~/.cache/ai-limits` on all platforms, unless
+`XDG_CONFIG_HOME` / `XDG_CACHE_HOME` override them. On Windows, `~` is the user profile directory
+and cache privacy relies on Windows ACLs; on POSIX, directories/files use 0700/0600.
+Files and CLI streams use UTF-8. Reset times display in the local timezone; timestamps without
+an explicit timezone are interpreted as UTC.
+
+## Where the numbers come from
+
+| Provider | Offline source | Network source (opt-in) |
+|---|---|---|
+| Codex | rate-limit snapshots in `~/.codex/sessions/**/rollout-*.jsonl`, updated whenever you use Codex | — |
+| Claude | `rate_limits` Claude Code passes to its status line; saved by `ai-limits tap claude` | `api.anthropic.com/api/oauth/usage` (adds per-model weekly limits) |
+
+When a window's reset time has passed, the limit is shown as `~0%` until fresh data arrives.
+
+### Claude: add the tap to your status line
+
+In `~/.claude/settings.json`:
+
+```jsonc
+"statusLine": { "type": "command", "command": "ai-limits tap claude --print" }
+// already have a status line? pass stdin through to it:
+"statusLine": { "type": "command", "command": "ai-limits tap claude | bash ~/.claude/statusline.sh" }
+```
+
+## Several accounts
+
+Both CLIs keep each login in its own directory (`CLAUDE_CONFIG_DIR=…`, `CODEX_HOME=…`). List them in
+`~/.config/ai-limits/config.toml`:
+
+```toml
+[[account]]
+provider = "claude"
+label    = "Claude Max"
+home     = "~/.claude"
+
+[[account]]
+provider = "codex"
+label    = "Codex · personal"
+home     = "~/.codex"
+
+[[account]]
+provider = "codex"
+label    = "Codex · work"
+home     = "~/.codex-work"
+```
+
+Without a config file, `~/.claude` and `~/.codex` are picked up automatically. With two or more
+accounts of one provider, the one with the most headroom gets a ★ and is the one shown in the panel.
+
+## Network mode (Linux only, behind a VPN)
+
+```toml
+[network]
+enabled = true
+require_interface = "tun0"     # mandatory: no interface, no network
+min_interval_seconds = 300
+```
+
+Before every request ai-limits:
+
+1. checks the interface exists — if not, it stops before even a DNS lookup;
+2. resolves the host and asks the kernel which interface the packet would leave by
+   (`ip route get`, which honours policy routing as used by sing-box / xray / WireGuard);
+3. sends an anonymous probe (no token, no cookies) to the same host and IP, e.g.
+   `api.anthropic.com/v1/models`. Being the same domain, it takes the same routing rule in your VPN
+   client, so a `direct` rule or a dead tunnel shows up here. Only the exact answer an allowed
+   region gets for a missing token (`401 authentication_error`) passes; a region block (403), a
+   timeout or anything unexpected stops here;
+4. only then sends the real request, to exactly that IP, ignoring proxy environment variables.
+
+Every socket is also bound to the interface (`SO_BINDTODEVICE`), so if the VPN drops between the
+checks and the request, the kernel refuses to send it another way. Any failure means no request
+with your token, and the panel shows `⏸` next to the last known numbers. Tokens are only read,
+never refreshed, never put on a command line, and never written anywhere.
+
+**What this cannot see:** what your VPN client does *inside* the tunnel. If its rules send
+`anthropic.com` to a `direct` outbound (or fall back to direct when the proxy is down), traffic
+enters `tun0` and still leaves from your real IP. The probe catches a region block, but the only
+real guarantee is in your VPN config: route these domains to the proxy with no direct fallback,
+or block them when the proxy is down (a kill switch).
+
+## CLI
+
+```
+ai-limits               summary
+ai-limits --version     installed version
+ai-limits json          state for UIs (docs/state-schema.md), also written to ~/.cache/ai-limits/state.json
+ai-limits accounts      configured / detected accounts
+ai-limits tap claude    status line helper (see above)
+```
+
+## Development
+
+```sh
+python3 -m unittest discover tests
+python3 -m ai_limits json
+```
+
+Releases go to PyPI through Trusted Publishing: run the **Build or publish to PyPI** workflow
+(`publish.yml`) on `main` with mode `publish`; `build-only` just builds and checks the packages.
+The PyPI publisher is owner `jointsome0-lgtm`, repository `ai-limits`, workflow `publish.yml`,
+environment `pypi`. No API token is needed.
+
+The GNOME extension only runs `ai-limits json` and draws the result; adding a provider means one
+module in `ai_limits/providers/`.
+
+## License
+
+MIT

ai_limits-0.1.0/README.md

@@ -0,0 +1,160 @@
+# ai-limits
+
+See how much of your AI subscriptions is left — Claude and Codex, any number of accounts — right
+in the GNOME top bar.
+
+```
+                                   ✳ 42%   ◎ 19%   Oct 27 15:49
+```
+
+```
+ Claude Max
+   Session (5h)   ████░░░░░░  42%   ↻ 18:30 (in 2h10m)
+   Week           ██░░░░░░░░  18%   ↻ Sun 19:00 (in 5d3h)
+ Codex · personal                         ★ most headroom
+   Week           ██░░░░░░░░  19%   ↻ Thu 12:00 (in 2d21h)
+ Codex · work                             updated 8h ago
+   Week           █████████░  91%   ↻ 18:00 (in 2h)
+```
+
+**Offline by default.** ai-limits reads only what Claude Code and Codex already saved on your
+machine. It sends no requests and does not read your tokens unless you turn on network mode, and
+network mode refuses to send anything unless the route goes through the VPN interface you name.
+
+> Unofficial. Not affiliated with Anthropic or OpenAI. The local formats and the usage endpoint it
+> reads are undocumented and may change.
+
+## Install
+
+```sh
+uv tool install ai-limits        # or: pipx install ai-limits
+ai-limits                       # check it sees your accounts
+```
+
+For the optional GNOME Shell 45–49 extension, install from a checkout (it is not in the wheel):
+
+```sh
+git clone https://github.com/jointsome0-lgtm/ai-limits.git
+cd ai-limits
+./gnome-extension/install.sh
+```
+
+### Platforms
+
+Python **3.11–3.14**, with no runtime dependencies. On distributions with an older system Python
+(e.g. Ubuntu 22.04 ships 3.10), use `uv tool install ai-limits`: uv fetches a suitable Python itself.
+**Linux** supports the offline CLI,
+Claude tap, and VPN-guarded network mode (`ip` from iproute2 is required for network mode).
+**macOS and Windows** support the offline CLI and Claude tap; network mode refuses to run
+there, before reading credentials or looking up the host. The GNOME extension is Linux-only.
+
+Config and cache use `~/.config/ai-limits` and `~/.cache/ai-limits` on all platforms, unless
+`XDG_CONFIG_HOME` / `XDG_CACHE_HOME` override them. On Windows, `~` is the user profile directory
+and cache privacy relies on Windows ACLs; on POSIX, directories/files use 0700/0600.
+Files and CLI streams use UTF-8. Reset times display in the local timezone; timestamps without
+an explicit timezone are interpreted as UTC.
+
+## Where the numbers come from
+
+| Provider | Offline source | Network source (opt-in) |
+|---|---|---|
+| Codex | rate-limit snapshots in `~/.codex/sessions/**/rollout-*.jsonl`, updated whenever you use Codex | — |
+| Claude | `rate_limits` Claude Code passes to its status line; saved by `ai-limits tap claude` | `api.anthropic.com/api/oauth/usage` (adds per-model weekly limits) |
+
+When a window's reset time has passed, the limit is shown as `~0%` until fresh data arrives.
+
+### Claude: add the tap to your status line
+
+In `~/.claude/settings.json`:
+
+```jsonc
+"statusLine": { "type": "command", "command": "ai-limits tap claude --print" }
+// already have a status line? pass stdin through to it:
+"statusLine": { "type": "command", "command": "ai-limits tap claude | bash ~/.claude/statusline.sh" }
+```
+
+## Several accounts
+
+Both CLIs keep each login in its own directory (`CLAUDE_CONFIG_DIR=…`, `CODEX_HOME=…`). List them in
+`~/.config/ai-limits/config.toml`:
+
+```toml
+[[account]]
+provider = "claude"
+label    = "Claude Max"
+home     = "~/.claude"
+
+[[account]]
+provider = "codex"
+label    = "Codex · personal"
+home     = "~/.codex"
+
+[[account]]
+provider = "codex"
+label    = "Codex · work"
+home     = "~/.codex-work"
+```
+
+Without a config file, `~/.claude` and `~/.codex` are picked up automatically. With two or more
+accounts of one provider, the one with the most headroom gets a ★ and is the one shown in the panel.
+
+## Network mode (Linux only, behind a VPN)
+
+```toml
+[network]
+enabled = true
+require_interface = "tun0"     # mandatory: no interface, no network
+min_interval_seconds = 300
+```
+
+Before every request ai-limits:
+
+1. checks the interface exists — if not, it stops before even a DNS lookup;
+2. resolves the host and asks the kernel which interface the packet would leave by
+   (`ip route get`, which honours policy routing as used by sing-box / xray / WireGuard);
+3. sends an anonymous probe (no token, no cookies) to the same host and IP, e.g.
+   `api.anthropic.com/v1/models`. Being the same domain, it takes the same routing rule in your VPN
+   client, so a `direct` rule or a dead tunnel shows up here. Only the exact answer an allowed
+   region gets for a missing token (`401 authentication_error`) passes; a region block (403), a
+   timeout or anything unexpected stops here;
+4. only then sends the real request, to exactly that IP, ignoring proxy environment variables.
+
+Every socket is also bound to the interface (`SO_BINDTODEVICE`), so if the VPN drops between the
+checks and the request, the kernel refuses to send it another way. Any failure means no request
+with your token, and the panel shows `⏸` next to the last known numbers. Tokens are only read,
+never refreshed, never put on a command line, and never written anywhere.
+
+**What this cannot see:** what your VPN client does *inside* the tunnel. If its rules send
+`anthropic.com` to a `direct` outbound (or fall back to direct when the proxy is down), traffic
+enters `tun0` and still leaves from your real IP. The probe catches a region block, but the only
+real guarantee is in your VPN config: route these domains to the proxy with no direct fallback,
+or block them when the proxy is down (a kill switch).
+
+## CLI
+
+```
+ai-limits               summary
+ai-limits --version     installed version
+ai-limits json          state for UIs (docs/state-schema.md), also written to ~/.cache/ai-limits/state.json
+ai-limits accounts      configured / detected accounts
+ai-limits tap claude    status line helper (see above)
+```
+
+## Development
+
+```sh
+python3 -m unittest discover tests
+python3 -m ai_limits json
+```
+
+Releases go to PyPI through Trusted Publishing: run the **Build or publish to PyPI** workflow
+(`publish.yml`) on `main` with mode `publish`; `build-only` just builds and checks the packages.
+The PyPI publisher is owner `jointsome0-lgtm`, repository `ai-limits`, workflow `publish.yml`,
+environment `pypi`. No API token is needed.
+
+The GNOME extension only runs `ai-limits json` and draws the result; adding a provider means one
+module in `ai_limits/providers/`.
+
+## License
+
+MIT

ai_limits-0.1.0/ai_limits/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ai_limits-0.1.0/ai_limits/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

ai_limits-0.1.0/ai_limits/cli.py

@@ -0,0 +1,129 @@
+"""ai-limits: AI subscription usage limits, offline by default.
+
+  ai-limits                 human-readable summary
+  ai-limits --version       installed version
+  ai-limits json            state JSON (docs/state-schema.md), also saved to ~/.cache/ai-limits/state.json
+  ai-limits accounts        configured / detected accounts
+  ai-limits tap claude      for Claude Code's statusLine: saves rate_limits from stdin, passes stdin through
+  ai-limits tap claude --print   same, but prints a short status line instead of passing stdin through
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import time
+from datetime import datetime
+
+from . import __version__, config
+from .core import build_state, format_duration, write_state
+from .model import normalise_home
+from .providers import claude
+
+DIM, RESET = "\033[2m", "\033[0m"
+
+
+def main(argv: list[str] | None = None) -> int:
+    # JSON and Claude's status-line protocol are UTF-8, including redirected Windows streams.
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(encoding="utf-8")
+    args = sys.argv[1:] if argv is None else argv
+    cmd = args[0] if args else "show"
+
+    if args == ["--version"]:
+        print(f"ai-limits {__version__}")
+        return 0
+    if cmd in ("-h", "--help", "help"):
+        print(__doc__.strip())
+        return 0
+    if cmd == "tap":
+        return _tap(args[1:])
+    if cmd not in ("show", "json", "accounts") or len(args) > 1:
+        # before loading config or providers: a typo must never trigger collection (or network)
+        print(f"ai-limits: unknown command {' '.join(args)!r} (see --help)", file=sys.stderr)
+        return 2
+
+    try:
+        cfg = config.load()
+    except config.ConfigError as e:
+        print(f"ai-limits: {e}", file=sys.stderr)
+        return 2
+
+    if cmd == "accounts":
+        print(f"config: {cfg.path or '(none, auto-detected)'}")
+        net = cfg.network
+        print(f"network: {'on via ' + net.require_interface if net.active else 'off'}")
+        for acc in cfg.accounts:
+            print(f"  {acc.id:22} {acc.provider:7} {acc.label!r:24} {acc.home}")
+        return 0
+
+    state = build_state(cfg)
+    write_state(state)
+    if cmd == "json":
+        json.dump(state, sys.stdout, ensure_ascii=False, indent=1, allow_nan=False)
+        print()
+    else:
+        _show(state, color=sys.stdout.isatty())
+    return 0
+
+
+def _tap(args: list[str]) -> int:
+    if not args or args[0] != "claude":
+        print("usage: ai-limits tap claude [--print]", file=sys.stderr)
+        return 2
+    if isinstance(sys.stdin, io.TextIOWrapper):
+        sys.stdin.reconfigure(encoding="utf-8")
+    raw = sys.stdin.read()
+    claude.tap_from_stdin(normalise_home(os.environ.get("CLAUDE_CONFIG_DIR") or "~/.claude"), raw)
+    if "--print" in args:
+        try:
+            rl = json.loads(raw).get("rate_limits") or {}
+        except (ValueError, AttributeError):
+            rl = {}
+        parts = [f"{label} {rl[key]['used_percentage']:.0f}%" for key, label in (("five_hour", "5h"), ("seven_day", "7d"))
+                 if isinstance(rl.get(key), dict) and rl[key].get("used_percentage") is not None]
+        print(" · ".join(parts) or "no limit data yet")
+    else:
+        sys.stdout.write(raw)
+    return 0
+
+
+def _show(state: dict, color: bool) -> None:
+    dim, reset = (DIM, RESET) if color else ("", "")
+    now = int(time.time())
+    if not state["accounts"]:
+        print("No accounts found (no ~/.claude or ~/.codex). See ~/.config/ai-limits/config.toml.")
+    for acc in state["accounts"]:
+        head = acc["label"] + (f" {dim}{acc['plan']}{reset}" if acc["plan"] else "")
+        if acc["recommended"]:
+            head += "  ★ most headroom"
+        if acc["status"] == "stale" and acc["updated_at"]:
+            head += f"  {dim}[updated {format_duration(now - acc['updated_at'])} ago]{reset}"
+        elif acc["status"] != "ok":
+            head += f"  {dim}[{acc['status']}{': ' + acc['message'] if acc['message'] else ''}]{reset}"
+        print(head)
+        for lim in acc["limits"]:
+            pct = f"{'~' if lim['estimated'] else ''}{lim['used_percent']:.0f}%"
+            bar = _bar(lim["used_percent"])
+            print(f"  {lim['label']:16} {bar} {pct:>5}  {dim}{_reset_text(lim['resets_at'], now)}{reset}")
+    net = state["network"]
+    print(f"{dim}network: {'on via ' + net['interface'] if net['enabled'] else 'off (offline mode)'}{reset}")
+
+
+def _bar(pct: float, width: int = 12) -> str:
+    filled = round(min(max(pct, 0), 100) / 100 * width)
+    return "█" * filled + "░" * (width - filled)
+
+
+def _reset_text(resets_at: int | None, now: int) -> str:
+    if not resets_at:
+        return ""
+    try:
+        when = datetime.fromtimestamp(resets_at)
+    except (ValueError, OverflowError, OSError):
+        return "reset time out of range"
+    same_day = when.date() == datetime.fromtimestamp(now).date()
+    return f"↻ {when.strftime('%H:%M' if same_day else '%a %H:%M')} (in {format_duration(resets_at - now)})"

ai_limits-0.1.0/ai_limits/config.py

@@ -0,0 +1,124 @@
+"""~/.config/ai-limits/config.toml, with auto-detection when no accounts are listed.
+
+    stale_after_hours = 6
+
+    [network]                      # off unless enabled AND require_interface is set
+    enabled = false
+    require_interface = "tun0"
+    min_interval_seconds = 300
+
+    [[account]]
+    provider = "codex"
+    label = "Codex · work"
+    home = "~/.codex-work"
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .model import AccountConfig, normalise_home
+
+PROVIDERS = ("claude", "codex")
+DEFAULT_HOMES = {
+    "claude": ("CLAUDE_CONFIG_DIR", "~/.claude", "Claude"),
+    "codex": ("CODEX_HOME", "~/.codex", "Codex"),
+}
+
+
+@dataclass
+class NetworkConfig:
+    enabled: bool = False
+    require_interface: str | None = None
+    min_interval_seconds: int = 300
+
+    @property
+    def active(self) -> bool:
+        # without a required interface there is nothing to check against -> stay offline
+        return self.enabled and bool(self.require_interface)
+
+
+@dataclass
+class Config:
+    accounts: list[AccountConfig] = field(default_factory=list)
+    network: NetworkConfig = field(default_factory=NetworkConfig)
+    stale_after_hours: float = 6.0
+    path: Path | None = None
+
+
+def config_dir() -> Path:
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "ai-limits"
+
+
+def cache_dir() -> Path:
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "ai-limits"
+
+
+class ConfigError(Exception):
+    pass
+
+
+def load(path: Path | None = None) -> Config:
+    path = path or config_dir() / "config.toml"
+    raw: dict = {}
+    if path.exists():
+        try:
+            raw = tomllib.loads(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, tomllib.TOMLDecodeError) as e:
+            raise ConfigError(f"{path}: {e}") from e
+
+    net = raw.get("network", {})
+    if not isinstance(net, dict):
+        raise ConfigError(f"{path}: [network] must be a table")
+    cfg = Config(
+        network=NetworkConfig(
+            # strict types: `enabled = "false"` must not switch the network on
+            enabled=_typed(path, "network.enabled", net.get("enabled", False), bool),
+            require_interface=_typed(path, "network.require_interface", net.get("require_interface"), str, None) or None,
+            min_interval_seconds=_typed(path, "network.min_interval_seconds", net.get("min_interval_seconds", 300), int),
+        ),
+        stale_after_hours=float(_typed(path, "stale_after_hours", raw.get("stale_after_hours", 6), (int, float))),
+        path=path if path.exists() else None,
+    )
+    if cfg.network.min_interval_seconds < 60:
+        raise ConfigError(f"{path}: network.min_interval_seconds must be at least 60")
+    if not (math.isfinite(cfg.stale_after_hours) and cfg.stale_after_hours > 0):
+        raise ConfigError(f"{path}: stale_after_hours must be a positive number")
+
+    accounts = raw.get("account", [])
+    if not isinstance(accounts, list) or not all(isinstance(e, dict) for e in accounts):
+        raise ConfigError(f"{path}: accounts must be [[account]] tables")
+    for i, entry in enumerate(accounts):
+        provider = entry.get("provider")
+        if provider not in PROVIDERS:
+            raise ConfigError(f"{path}: account #{i + 1}: provider must be one of {', '.join(PROVIDERS)}")
+        env, default_home, default_label = DEFAULT_HOMES[provider]
+        home = entry.get("home") or os.environ.get(env) or default_home
+        acc = AccountConfig(provider, _typed(path, "account.label", entry.get("label"), str, None) or default_label,
+                            normalise_home(_typed(path, "account.home", home, str)))
+        if any(a.id == acc.id for a in cfg.accounts):
+            raise ConfigError(f"{path}: account #{i + 1}: {provider} {acc.home} is listed twice")
+        cfg.accounts.append(acc)
+
+    if not cfg.accounts:
+        cfg.accounts = detect_accounts()
+    return cfg
+
+
+def _typed(path, key, value, types, *allowed):
+    if value in allowed or (isinstance(value, types) and not (isinstance(value, bool) and types is not bool)):
+        return value
+    raise ConfigError(f"{path}: {key} has the wrong type ({type(value).__name__})")
+
+
+def detect_accounts() -> list[AccountConfig]:
+    found = []
+    for provider, (env, default_home, label) in DEFAULT_HOMES.items():
+        home = normalise_home(os.environ.get(env) or default_home)
+        if os.path.isdir(home):
+            found.append(AccountConfig(provider, label, home))
+    return found