AgentMeter User Guide¶

AgentMeter is a desktop usage tool for coding Agents. It lets you view the account, quota, and Token usage of coding Agents on your local machine. After connecting AgentMeter to Guance, you can also report usage metrics and Agent runtime traces to the current Workspace for unified analysis of Agent usage, performance, and invocation processes.

AgentMeter currently supports Codex, Claude Code, and WorkBuddy. The data available from each Agent differs:

Install AgentMeter¶

Before installation, install and sign in to the Agents you want to view on the current device. Then download the installation package that matches your operating system and processor architecture:

macOS¶

1. Open the downloaded DMG file;
2. Drag AgentMeter into Applications;
3. Launch AgentMeter from the Applications folder.

After AgentMeter starts, it stays in the menu bar and does not show a Dock icon.

Windows¶

1. Extract the downloaded ZIP file;
2. Run the installer inside;
3. Launch AgentMeter after installation.

After AgentMeter starts, it stays in the system tray.

Linux¶

Use the following command to install the DEB package on Debian or Ubuntu:

sudo apt install ./AgentMeter-latest-linux-<architecture>.deb

Use the following command to install the RPM package on Fedora or RHEL:

sudo dnf install ./AgentMeter-latest-linux-<architecture>.rpm

Replace <architecture> with arm64 or amd64. After installation, launch AgentMeter from the application list.

View Agent Usage¶

After launching AgentMeter, click the AgentMeter icon in the menu bar or system tray to open the floating panel. AgentMeter automatically detects the Agents installed on the current device and displays the usage information it can read.

• Click Refresh to immediately update account, quota, and usage data;
• Click the Token metric to view historical usage displayed by day, calendar, or trend chart;
• Go to Settings > Agents to select the Agents to display in the floating panel or system tray, and drag to adjust the display order;
• Go to Settings > General to configure language, appearance, and launch at login;
• Go to Settings > About to check for and install AgentMeter updates.

After Claude Code is first connected for quota reading, open or restart a Claude Code session once. If the current account or Claude Code version does not return the subscription quota field, AgentMeter can still display local Token history.

Integrate with Guance¶

To report Agent data to Guance, go to Settings > Service Integration. Service Integration includes the following two collection tiers:

Basic Collection is built into AgentMeter; Enhanced Collection is managed by AgentMeter through obs-agent-connector. The two collection tiers can be enabled separately for each Agent.

Step 1: Configure the Connection¶

Go to Agent Monitoring > Summary > Agent Integration, and obtain the Data Endpoint and X-Token for the current Workspace on the Agent Integration Configuration page. Then, in Settings > Service Integration > Connection Configuration, import a JSON configuration file or manually fill in the following information:

The import file uses the following format:

{
  "schemaVersion": 1,
  "ingestEndpoint": "<Data Endpoint>",
  "xToken": "<X-Token>",
  "user_id": "<User ID>",
  "user_name": "<User Name>"
}

The configuration file must use the .json extension and be no larger than 64 KB. After saving, AgentMeter hides the X-Token and does not display the full value in the interface.

Step 2: Enable Basic Collection¶

In the Basic Collection area, enable the switch for the Agents whose usage metrics you want to report. Once enabled, AgentMeter reports data immediately, and then reports the latest snapshot every 60 seconds.

Basic Collection data is written to the agent_runtime Measurement, and AgentMeter metric fields start with agent_meter_. Basic Collection contains only usage and account snapshots; it does not generate Session or Trace data.

Step 3: Enable Enhanced Collection¶

1. In the Enhanced Collection area, click Install Connector;
2. After installation, enable Enhanced Collection for the Agents whose runtime traces you want to collect;
3. Complete configuration and validation according to the on-page prompts;
4. Restart running Agent sessions to apply the collection configuration;
5. Start a new session or task with the Agent.

AgentMeter only manages Agents that are detected and supported on the current device. After the connector is installed, you can continue to enable, disable, validate, or remove integrations per Agent on the Service Integration page.

Validate the Data¶

After completing the Service Integration, you can validate data by collection tier:

• Basic Collection: In Metrics Analysis, select the agent_runtime Measurement and query metric fields starting with agent_meter_;
• Enhanced Collection: Go to Agent Monitoring > Explorer and view data by Agent type, User, Session, or Trace;
• Trend Analysis: Go to Agent Monitoring > Analysis Dashboard and filter data by Agent type, Agent ID, or Agent name.

If you have just enabled Enhanced Collection, complete one new task with the Agent before querying. The collection configuration does not backfill complete Trace data from before it was enabled.

Configure Long Task Notifications¶

AgentMeter supports sending notifications through a Lark group bot after a Codex long task completes.

1. Go to Settings > Notifications;
2. Enable notifications and Long Task Completion Notifications;
3. Enter the Webhook URL of the Lark group bot;
4. If signature verification is enabled for the bot, also enter the signing secret;
5. Set the long task threshold and save;
6. Click Test Notification to confirm that the group chat receives messages properly.

Completion notifications are sent only for Codex tasks whose execution time reaches the threshold.

FAQ¶

Agent Not Detected¶

Confirm that the Agent is installed and has started successfully at least once, then click Refresh in Settings > Agents. Codex also requires you to sign in to your account. Linux does not currently support detecting WorkBuddy Desktop.

Claude Code Has No Quota Data¶

Open or restart a Claude Code session and wait for AgentMeter to receive the first quota response. Some account plans or Claude Code versions do not provide quota fields; in that case, Token history remains available.

Basic Collection Has No Data¶

Confirm that the connection configuration is saved and that Basic Collection is enabled for the target Agent, then wait for at least one reporting cycle. Then click View Basic Collection Diagnostics to check the latest collection time, report time, and error messages.

Enhanced Collection Has No Trace¶

Confirm that the connector is installed and that Enhanced Collection is enabled and validated for the target Agent. Restart the Agent, start a new task, and then query in the Agent Monitoring Explorer. If there is still no data, click View Diagnostic Information to check the connector status.

View Diagnostic Logs¶

AgentMeter diagnostic logs do not record task content, full Tokens, Webhooks, or signing secrets. The default log paths are as follows:

Historical logs use suffixes from .1 to .4. When submitting an issue, we recommend providing the AgentMeter version, operating system, Agent type, and redacted diagnostic logs.

Further Reading¶