`agy` Timers Utils

README.md

Agent Quota Timer Utils

An Agent Quota model quota timer handling script

It is packaged as a Nix flake, exposing a standalone package, a Home Manager module, and a native NixOS module to run the script periodically via systemd user services and timers so the cooldown is always maxxed

How to use

Flake Input

Add this flake input to your configuration:

inputs.agent-quota-timer-utils = {
  url = "https://gist.github.com/Malix-Labs/663d4910dfb3eb71018b1f1c2d9bcd64";
  type = "git";
  inputs.nixpkgs.follows = "nixpkgs";
};

Home Manager (user-level)

Import the Home Manager module:

imports = [
  inputs.agent-quota-timer-utils.homeModules.default
];

services.agent-quota-timer-utils = {
  enable = true;
  # agy = {
  #   enable = true;          # optional: enable the integration (default: config.programs.antigravity-cli.enable)
  #   package = pkgs.antigravity-cli; # optional: package to use (default: config.programs.antigravity-cli.package)
  #   models = {
  #     internal.enable = true; # optional: enable internal model quota timer handling (default: true)
  #     external.enable = true; # optional: enable external model quota timer handling (default: true)
  #   };
  # };
};

NixOS (system-level)

Import the NixOS module:

imports = [
  inputs.agent-quota-timer-utils.nixosModules.default
];

services.agent-quota-timer-utils = {
  enable = true;
  # agy = {
  #   enable = true;          # optional: enable the integration (default: config.programs.antigravity-cli.enable)
  #   package = pkgs.antigravity-cli; # optional: package to use (default: config.programs.antigravity-cli.package)
  #   models = {
  #     internal.enable = true; # optional: enable internal model quota timer handling (default: true)
  #     external.enable = true; # optional: enable external model quota timer handling (default: true)
  #   };
  # };
};

Standalone Package (no timer)

If you only want the agent-quota-timer-utils script package installed in your path, but do not want to configure the systemd periodic run/timer, you can add it to your packages list:

• Home Manager:

  home.packages = [
    inputs.agent-quota-timer-utils.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];

• NixOS:

  environment.systemPackages = [
    inputs.agent-quota-timer-utils.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];

Run Ad-Hoc (nix run)

To execute the script on-demand without installing it:

nix run git+https://gist.github.com/Malix-Labs/663d4910dfb3eb71018b1f1c2d9bcd64

flake.lock

{
  "nodes": {
    "flake-compat": {
      "flake": false,
      "locked": {
        "lastModified": 1767039857,
        "narHash": "sha256-vNpUSpF5Nuw8xvDLj2KCwwksIbjua2LZCqhV1LNRDns=",
        "owner": "NixOS",
        "repo": "flake-compat",
        "rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
        "type": "github"
      },
      "original": {
        "owner": "NixOS",
        "repo": "flake-compat",
        "type": "github"
      }
    },
    "flake-parts": {
      "inputs": {
        "nixpkgs-lib": [
          "nixpkgs"
        ]
      },
      "locked": {
        "lastModified": 1782949081,
        "narHash": "sha256-vp6Y/Grm98ESt6ceOkWiHWyZRDV3J1RID4w+6NWK9yA=",
        "owner": "hercules-ci",
        "repo": "flake-parts",
        "rev": "17c9d6cdfc60c64f4ee8d306f9bc0b4ccb51481e",
        "type": "github"
      },
      "original": {
        "owner": "hercules-ci",
        "repo": "flake-parts",
        "type": "github"
      }
    },
    "git-hooks": {
      "inputs": {
        "flake-compat": "flake-compat",
        "nixpkgs": [
          "options-utils",
          "nixpkgs"
        ]
      },
      "locked": {
        "lastModified": 1783008725,
        "narHash": "sha256-jGiy6+sxjNWXSjp25uoJuNfyH9zBK1PEDY0lVoL4ibQ=",
        "owner": "cachix",
        "repo": "git-hooks.nix",
        "rev": "bca82caa46d5ec0f5d422c61fb1e30bc51313cbe",
        "type": "github"
      },
      "original": {
        "owner": "cachix",
        "repo": "git-hooks.nix",
        "type": "github"
      }
    },
    "nixpkgs": {
      "locked": {
        "lastModified": 1782723713,
        "narHash": "sha256-T6OhkwGyyGHer1lr4GkbOp//7ii23xLE7HuMmjrdkXI=",
        "rev": "b5aa0fbd538984f6e3d201be0005b4463d8b09f8",
        "type": "tarball",
        "url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1024265.b5aa0fbd5389/nixexprs.tar.xz"
      },
      "original": {
        "type": "tarball",
        "url": "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz"
      }
    },
    "options-utils": {
      "inputs": {
        "flake-parts": [
          "flake-parts"
        ],
        "git-hooks": "git-hooks",
        "nixpkgs": [
          "nixpkgs"
        ],
        "systems": [
          "systems"
        ]
      },
      "locked": {
        "lastModified": 1784047701,
        "narHash": "sha256-wXsyaSY9au94qnVQeny+suMKqUdlHysoJzn2SGvAvx0=",
        "ref": "refs/heads/main",
        "rev": "50e64f7a9ccc3890057b581a95171f723e105490",
        "revCount": 1,
        "type": "git",
        "url": "https://gist.github.com/Malix-Labs/eec30a668f03ca4ad1060c68c3f5c442"
      },
      "original": {
        "type": "git",
        "url": "https://gist.github.com/Malix-Labs/eec30a668f03ca4ad1060c68c3f5c442"
      }
    },
    "root": {
      "inputs": {
        "flake-parts": "flake-parts",
        "nixpkgs": "nixpkgs",
        "options-utils": "options-utils",
        "systems": "systems"
      }
    },
    "systems": {
      "flake": false,
      "locked": {
        "lastModified": 1681028828,
        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
        "owner": "nix-systems",
        "repo": "default",
        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
        "type": "github"
      },
      "original": {
        "owner": "nix-systems",
        "repo": "default",
        "type": "github"
      }
    }
  },
  "root": "root",
  "version": 7
}

flake.nix

{
  description = "Agent Quota Timer Utils";

  inputs = {
    nixpkgs.url = "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz";
    flake-parts = {
      url = "github:hercules-ci/flake-parts";
      inputs.nixpkgs-lib.follows = "nixpkgs";
    };
    systems = {
      url = "github:nix-systems/default";
      flake = false;
    };
    options-utils = {
      url = "https://gist.github.com/Malix-Labs/eec30a668f03ca4ad1060c68c3f5c442";
      type = "git";
      inputs = {
        nixpkgs.follows = "nixpkgs";
        flake-parts.follows = "flake-parts";
        systems.follows = "systems";
      };
    };
  };

  outputs =
    inputs@{
      flake-parts,
      options-utils,
      nixpkgs,
      ...
    }:
    let
      name = "agent-quota-timer-utils";

      makeOptions =
        pkgs:
        let
          inherit (nixpkgs.lib)
            mkOption
            mkEnableOption
            mkPackageOption
            mapAttrs
            types
            getName
            ;
          mkModelOpts = kind: name: {
            enable = mkEnableOption "${kind} model quota timer handling" // {
              default = true;
            };
            name = mkOption {
              type = types.str;
              default = name;
              description = "Model name for the ${kind} model quota timer handling.";
              internal = true;
            };
            interval = mkOption {
              internal = true;
              type = types.submodule {
                options = {
                  short = mkOption {
                    type = types.str;
                    default = "5h";
                    description = "Short interval for running ${kind} model.";
                  };
                  long = mkOption {
                    type = types.str;
                    default = "24h";
                    description = "Long interval for running ${kind} model.";
                    visible = false;
                  };
                };
              };
            };
          };
        in
        {
          enable = mkEnableOption "${name} periodic service";

          agy =
            let
              pkgName = getName pkgs.antigravity-cli;
            in
            {
              enable = mkEnableOption "the ${pkgName} integration";

              package = mkPackageOption pkgs pkgName { };

              models = mapAttrs mkModelOpts {
                internal = "Gemini 3.5 Flash (Low)";
                external = "GPT-OSS 120B (Medium)";
              };
            };
        };

      getDefaultsFor = pkgs: options-utils.lib.getDefaults (makeOptions pkgs);

      makeAgyQuotaTimerStart =
        {
          pkgs,
          cfg ? getDefaultsFor pkgs,
        }:
        pkgs.writeShellScriptBin name ''
          exec ${pkgs.lib.getExe cfg.agy.package} --model "$1" --print 'Reply "OK"'
        '';

      optionsModule =
        {
          pkgs,
          lib,
          config,
          ...
        }:
        let
          inherit (lib) mkIf versionAtLeast getName;
          cfg = config.services.${name};
          minVersion = "1.0.5";
          pkgVersion = cfg.agy.package.version;
        in
        {
          options.services.${name} = makeOptions pkgs;

          config = {
            assertions = mkIf cfg.enable [
              {
                assertion = versionAtLeast pkgVersion minVersion;
                message = "${name} requires ${getName cfg.agy.package} >= ${minVersion}, but version ${pkgVersion} was provided.";
              }
            ];
          };
        };

      makeModule =
        mkConfig:
        {
          lib,
          config,
          options,
          pkgs,
          ...
        }:
        let
          inherit (lib) mkIf;
          cfg = config.services.${name};
          pkg = makeAgyQuotaTimerStart { inherit pkgs cfg; };
        in
        {
          imports = [ optionsModule ];

          config = mkIf cfg.enable (mkConfig lib pkgs config options cfg pkg);
        };

      mkServicesAndTimers =
        {
          lib,
          cfg,
          builders,
        }:
        let
          enabledModels = lib.filterAttrs (_: modelCfg: modelCfg.enable) cfg.agy.models;
          genUnits =
            mkUnit:
            lib.concatMapAttrs (kind: modelCfg: {
              "${name}-${kind}" = mkUnit kind modelCfg;
            }) enabledModels;
        in
        lib.mapAttrs (_: genUnits) builders;
    in
    flake-parts.lib.mkFlake { inherit inputs; } {
      systems = import inputs.systems;

      flake.homeModules.default = makeModule (
        lib: pkgs: config: options: cfg: pkg: {
          services.${name}.agy =
            let
              progName = "antigravity-cli";
            in
            lib.optionalAttrs (options.programs ? ${progName}) (
              lib.mapAttrs (_: lib.mkDefault) {
                inherit (config.programs.${progName}) enable package;
              }
            );

          systemd.user = mkServicesAndTimers {
            inherit lib cfg;
            builders = {
              services = kind: modelCfg: {
                Unit = {
                  Description = "Start ${name} for ${kind} model";
                  After = [ "network-online.target" ];
                  Wants = [ "network-online.target" ];
                };
                Service = {
                  ExecStartPre = lib.getExe (
                    pkgs.writeShellApplication {
                      name = "check-network";
                      runtimeInputs = with pkgs; [ curl ];
                      text = ''
                        for i in 1 2 3 4 5; do
                          [ "$i" -gt 1 ] && sleep 30
                          curl --silent --fail --head --connect-timeout 5 https://one.one.one.one >/dev/null 2>&1 && exit 0
                        done
                        exit 1
                      '';
                    }
                  );
                  ExecStart = "${lib.getExe pkg} '${modelCfg.name}'";
                  Type = "oneshot";
                };
                Install.WantedBy = [ "default.target" ];
              };
              timers = kind: modelCfg: {
                Unit.Description = "Run ${name} periodically for ${kind} model";
                Timer = {
                  OnUnitInactiveSec = modelCfg.interval.short;
                  Persistent = true;
                };
                Install.WantedBy = [ "timers.target" ];
              };
            };
          };
        }
      );

      flake.nixosModules.default = makeModule (
        lib: pkgs: config: options: cfg: pkg: {
          systemd.user = mkServicesAndTimers {
            inherit lib cfg;
            builders = {
              services = kind: modelCfg: {
                description = "Start ${name} for ${kind} model";
                after = [ "network-online.target" ];
                wants = [ "network-online.target" ];
                serviceConfig = {
                  ExecStartPre = lib.getExe (
                    pkgs.writeShellApplication {
                      name = "check-network";
                      runtimeInputs = with pkgs; [ curl ];
                      text = ''
                        for i in 1 2 3 4 5; do
                          [ "$i" -gt 1 ] && sleep 30
                          curl --silent --fail --head --connect-timeout 5 https://one.one.one.one >/dev/null 2>&1 && exit 0
                        done
                        exit 1
                      '';
                    }
                  );
                  ExecStart = "${lib.getExe pkg} '${modelCfg.name}'";
                  Type = "oneshot";
                };
              };
              timers = kind: modelCfg: {
                description = "Run ${name} periodically for ${kind} model";
                timerConfig = {
                  OnUnitInactiveSec = modelCfg.interval.short;
                  Persistent = true;
                };
                wantedBy = [ "timers.target" ];
              };
            };
          };
        }
      );

      perSystem =
        { pkgs, ... }:
        {
          formatter = pkgs.nixfmt-tree;
          packages.default = makeAgyQuotaTimerStart { inherit pkgs; };
        };
    };
}