agent-quotas: Instructions file for Codex

Claude Quota Monitor — Agent Setup Guide

This guide is for AI agents (Claude Code, Codex CLI, Antigravity, etc.) to set up the quota monitoring hook on a user's machine autonomously.

Prerequisites

Before starting, verify:

• jq is installed: command -v jq should return a path
• curl is installed: command -v curl should return a path
• A quota monitor server is running (ask user if not provided)
• The user has a Personal Access Token (PAT) issued by the server admin

Setup Steps

Step 1: Gather Configuration from User

Ask the user for:

1. Server URL: The address where the quota monitor server is running (e.g., http://192.168.1.100:3000 or http://localhost:3000)
2. Username: A display name for this machine on the dashboard (e.g., MacBook Pro or dev-machine)
3. Token: A Personal Access Token (PAT) obtained from the server admin panel. The user must request this from their admin.

If the user doesn't have a server running yet, direct them to the Server Setup section at the end.

If the user doesn't have a PAT yet, direct them to request one from the admin via the admin panel (/admin).

Step 2: Create Hook Configuration File

Write the configuration to ~/.claude-quota-hook.json:

{
  "server_url": "USER_PROVIDED_SERVER_URL",
  "username": "USER_PROVIDED_USERNAME",
  "token": "PAT_FROM_ADMIN"
}

Example:

{
  "server_url": "http://192.168.1.100:3000",
  "username": "alice",
  "token": "PAT_abc123xyz"
}

All three fields are required. The token authenticates this client with the server and must be a valid PAT issued by the admin.

Step 3: Locate and Verify Hook Scripts

Hook scripts are located in REPO_PATH/hook/:

Tool	Script
Claude Code	hook/claude-quota-hook.sh
Codex CLI	hook/codex-hook.sh
Antigravity	hook/antigravity-hook.sh

Ensure all scripts are executable:

chmod +x REPO_PATH/hook/claude-quota-hook.sh
chmod +x REPO_PATH/hook/codex-hook.sh
chmod +x REPO_PATH/hook/antigravity-hook.sh