llm-tools AGENTS.md

AGENTS.md

Scope

This repo contains small Linux Python CLIs for Codex, Claude Code, GitHub Copilot, and Kilo Code CLI:

• llm-usage — show local usage/quota for each provider, optionally through a local Unix-socket sampler service.
• llm-scheduler — submit a prompt to a provider CLI once usage data says it is usable (optionally waking/suspending around a scope reset).
• ralph-robin — keep using one configured provider until it is exhausted, then rotate to the next provider and delegate launch/suspend behavior to llm-scheduler. Holds an OS idle inhibitor for the whole run so a desktop idle timer cannot suspend the machine mid-work, and when every provider is rate-limited it sleeps the machine itself via a verified RTC wake (see Suspend/wake reliability below).
• llm-sleep-soak — repeatedly suspend and wake the machine using the exact production suspend path to prove sleep/resume is reliable on this hardware. Real-hardware test; cannot run in CI.
• llm_tools/common.py — shared helpers (provider readers, normalization, time/reset formatting, subprocess execution, usage decisions, PTY capture, wake diagnostics, and common CLI plumbing: argument validation, run-dir logging, prompt loading, argv/JSON conversion).
• llm_tools/usage_service.py — local-only llm-usage sampler service (Unix socket, latest snapshot, append-only history; systemd user service / launchd LaunchAgent install helpers).
• llm_tools/capacity.py — generic ProviderId, CapacityKind, CapacityScope, ProviderSnapshot, and UsageDecision dataclasses plus the decide/validate_scope/scope_pace helpers. All provider-specific reader code lives outside this module.
• llm_tools/providers/kilo.py — Kilo Code CLI adapter (parser for kilo stats --days <MTD> output, env-var fallback, command construction).
• llm_tools/providers/minimax.py — MiniMax adapter (parser for mmx quota show --output json output, env-var fallback, command construction).
• Python modules: llm_tools/usage.py, llm_tools/scheduler.py, llm_tools/ralph_robin.py, llm_tools/sleep_soak.py, llm_tools/copilot_refresh.py, and package marker llm_tools/__init__.py.
• Public direct-run command files: llm-usage, llm-scheduler, ralph-robin, llm-sleep-soak.
• Regression tests: tests/ with pytest and fake provider commands.
• Test helpers: tests/conftest.py; main suites: tests/test_contracts.py, tests/test_additional_paths.py, tests/test_capacity.py, tests/test_kilo.py, tests/test_minimax.py, tests/test_ralph_kilo.py, tests/test_zai.py.
• Project/package config: pyproject.toml.
• Import/test bootstrap: sitecustomize.py.
• CI: .github/workflows/test.yml.
• User docs: README.md.
• Local planning/work logs: PLANS.md, WORKLOG.md.
• Runtime data root: ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools, one subdirectory per tool. Legacy ~/.cache/llm-usage, ~/.cache/llm-scheduler, and ~/.cache/ralph-robin dirs are auto-migrated by migrate_legacy_cache_dirs in llm_tools/common.py.
• Usage cache and samples log: ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools/llm-usage (claude-status.json, claude-usage-api.json, llm-usage.log)
• Usage service history/logs: ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools/llm-usage/service (latest.json, history.jsonl, service logs)
• Usage service socket/pid: ${XDG_RUNTIME_DIR:-/tmp/llm-tools-$UID} (llm-usage.sock, llm-usage.pid) so Unix socket paths stay below platform length limits.
• Copilot background refresh helper: llm_tools/copilot_refresh.py, launched by read_copilot for detached cache refreshes.
• Scheduler run logs: ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools/llm-scheduler/logs
• Ralph Robin run logs: ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools/ralph-robin/logs
• Ralph Robin state: ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools/ralph-robin/state.json
• Suspend cycle ledger (durable, fsync'd; shared by ralph-robin and the soak): ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools/ralph-robin/suspend-ledger.jsonl
• Sleep-soak run logs: ${XDG_CACHE_HOME:-$HOME/.cache}/llm-tools/llm-sleep-soak/logs