Agent Cat Connectors

English | 한국어

Agent Cat Connectors lets the Agent Cat menu bar app see local CLI-agent
activity from Codex, Claude Code, Gemini CLI, and other supported agent tools.

It installs a small local collector, keeps data under ~/.agentcat, and patches
supported CLI settings so future sessions can report activity without sending
prompts to a remote server. This single public connector powers the product
with local monitoring, provider breadth, quota state, basic costs, budget caps,
and weekly report inputs.

License

Agent Cat Connectors is source-available under the
PolyForm Shield License 1.0.0. It is not OSI open source.

Commercial competitive use is prohibited. Do not use this connector to
build, operate, sell, or distribute a competing product, hosted service,
analytics tool, quota monitor, reporting product, or team/admin product without
a separate commercial license from Trappist.

You may inspect, install, modify, and distribute the connector for permitted
purposes, including use with Agent Cat. You may not use it to provide, package,
host, sell, or distribute a product or service that competes with Agent Cat or
Trappist's Agent Cat-related connector, monitoring, quota, analytics, reporting,
account, or team tooling without a separate commercial license.

See NOTICE for the required copyright and line-of-business notices.
For commercial licensing, contact [email protected].

Install

The normal user path is app-led:

1. Open Agent Cat.
2. Go to Home -> Agents / Connector.
3. Click Install connector.
4. Wait for the app to show live provider data.

The app-led path is preferred because it explains what will change, keeps a
rollback backup, and verifies the local daemon after install. Use the commands
below only for development, CI, remote support, or when the app cannot open the
installer.

Advanced Windows PowerShell:

irm https://raw.githubusercontent.com/yong076/agentcat-connectors/main/install.ps1 | iex

Advanced macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/yong076/agentcat-connectors/main/install.sh | bash

Development from a cloned checkout:

./install.sh

Connector archive integrity

The public installers fetch connector-manifest.json from the latest GitHub
release, download its versioned archive, and verify the manifest SHA-256 before
extracting or executing connector code. They then use
scripts/public_channel_install.py to validate the contract, stage the new
source beside the active source, run the installer, and validate the live
daemon. A failed health check restores the previous source and daemon.

A dirty legacy git checkout is never force-checked out or deleted. The updater
stores its tracked patch, untracked-file copies, and status under
~/.agentcat/backups/connector-source/legacy-dirty-*, then stops so the user can
port or review those changes. App-led/local QA installs may pin a different
archive only when URL, version, and SHA-256 are supplied together via
AGENTCAT_CONNECTORS_ARCHIVE_URL, AGENTCAT_CONNECTORS_VERSION, and
AGENTCAT_CONNECTORS_SHA256.

Development on Windows from a cloned checkout:

.\install.ps1

Then verify:

agentcat snapshot

If an agent runtime needs manual setup text after installation, copy the
fallback prompt:

agentcat setup-prompt

What It Installs

• ~/.local/bin/agentcat or %USERPROFILE%\.local\bin\agentcat.cmd: local collector CLI
• ~/Library/LaunchAgents/com.trappist.agentcatd.plist or Windows startup task AgentCatD: local daemon on 127.0.0.1:8765. If task registration is unavailable, Windows uses the current user's HKCU Run entry instead. Both start the daemon hidden through wscript.exe and ~/.agentcat/AgentCatD.vbs (no console window at sign-in), or through cmd.exe when Windows Script Host is missing or disabled; the installer no longer creates a script in the Startup folder.
• ~/.agentcat/events.sqlite: local event store
• ~/.agentcat/latest-snapshot.json: latest normalized usage snapshot
• timestamped backups under ~/.agentcat/backups/

Provider Support

Included Insights Engine

The single public connector includes today (the current local calendar day),
week (seven local calendar days including today), month (thirty local
calendar days including today), and all (all-time) insights; burn
rate, automatic quota estimates, and provider recommendations; per-project
daily cost; OpenAI API-key usage with a secure local set-key command; Codex
usage-source breakdowns; Antigravity history; and reset-safe model baselines
that avoid recording counter resets as new usage.

Multiple Provider Homes

A provider's usage can live under more than one home on the same machine: a
second profile via $CODEX_HOME / $CLAUDE_CONFIG_DIR, or a runtime home
another local tool created by mirroring the default one. The daemon reads the
home its environment named when the launch job was created, so anything else is
invisible — and a mirror that quietly stops receiving new sessions still holds a
plausible-looking lifetime total, which makes the gap hard to notice.

agentcat doctor reports homes holding usage the connector is not reading, and
distinguishes two cases: untracked_home (a second profile) and stalled_home
(the home being read has gone quiet while an unread one keeps growing). It also
reports env_drift when the daemon's launch job pins a path that no longer
matches the current shell.

agentcat homes                                   # list homes and which are read
agentcat homes --provider codex --adopt <path>   # start counting a home
agentcat homes --provider codex --exclude <path> # never read or suggest it
agentcat homes --provider codex --forget <path>  # back to the default state

Discovery is automatic, adoption is not: reading an extra home changes every
number the product reports, so it stays an explicit choice. Adopted homes are
deduplicated by inode and session identity, so a mirror that hardlinks or copies
its sessions is counted once, never twice.

One command per account

Agent Cat never switches which account a CLI is logged into. For a second
account, give it its own home and a launcher command:

agentcat profile add codex work      # creates ~/.local/bin/codex-work
codex-work login                     # log in with the CLI itself
agentcat profile list                # provider, command, home, adopted, logged in
agentcat profile remove codex work   # add --delete-home to delete the home too

add creates a private home under ~/.agentcat/homes/ (or --home PATH), writes
a launcher that runs the real CLI with CODEX_HOME / CLAUDE_CONFIG_DIR /
KIMI_CODE_HOME set, and adopts the home for Codex and Claude. It never creates
or copies credentials, and it refuses to overwrite a file it did not write.

Orca Claude account quotas

When the local Orca IDE CLI is available, the connector reads orca account list --json at most once per minute and adds host Claude profiles to providerInstances.
The selected system-default profile and each managed profile have separate quota
rows. Active quotas are matched against both the host selection and the quota's
own authentication provenance, so a pending account switch cannot attach the
previous profile's quota to the new one. Inactive quotas require the same exact
profile/provenance match. Missing quotas stay unknown, not zero or a copy of the
default quota. Session, weekly, and Fable weekly windows are normalized separately.

IDs are device-local HMACs and labels are masked (Claude · Orca · …). Orca profile
IDs are not verified native Claude account IDs: identityConfidence is
profile_only, and the default row represents a mutable system-default slot.
There is no cross-source account deduplication by email, label, or quota similarity.
active means selected in Orca, not that a terminal is running. This bridge
does not attribute terminals, tokens, costs, or historical sessions to accounts,
and does not adopt additional transcript homes. WSL profiles are not imported yet.

Only normalized quota rows are cached in memory. The raw account response,
emails, organization IDs, authentication provenance, credential paths, and error
text are neither logged nor persisted. Source data older than five minutes is
marked stale; after fifteen minutes (or without a valid source timestamp), quotas
are hidden. A CLI failure clears bridge rows and leaves the existing single-account
Claude collector unchanged. Calls time out after two seconds and failed probes
also wait one minute before retrying. The bridge never launches the Orca app,
reads credential files, changes accounts, or refreshes OAuth credentials itself.

Set AGENTCAT_ORCA_ACCOUNTS=0 in the daemon environment to disable discovery.
AGENTCAT_ORCA_CLI optionally names a single executable path (no shell arguments).
Otherwise the bridge respects ORCA_CLI_COMMAND/ORCA_DEV_REPO_ROOT, then searches
PATH and ~/.local/bin. Linux uses orca-ide, never the GNOME orca screen reader.
The host CLI contract was verified with Orca 1.4.193 on macOS; incompatible/missing
CLI versions safely fall back to the existing collector.

Account cards also receive planType from local profile metadata, not usage
percentages. The selected system-default slot reads ~/.claude.json's
oauthAccount; managed profiles read only
<Orca data directory>/claude-accounts/<profile>/auth/oauth-account.json.
Managed metadata must have the matching directory marker, email, and organization
from Orca's account list. Those identifiers never leave the reader. This is not
account deduplication, and a missing managed plan never inherits the default plan.
OAuth credential files and Keychain are not read by this bridge.

Explicit Max tiers render as Max 5x / Max 20x; otherwise only a recognized
coarse plan is shown. An individual tier takes precedence over the organization's
tier. Unknown plans remain absent. Metadata must have been fetched in the last
24 hours and must not predate the managed profile's latest authentication by more
than five seconds (Orca fetches profile metadata before committing the login).
planSource and planUpdatedAt describe this cached metadata observation; they
are not a live billing lookup. Quota freshness is checked independently.

Set AGENTCAT_ORCA_PLANS=0 to disable only plan discovery. The standard Orca data
directory is ~/Library/Application Support/orca on macOS, %APPDATA%/orca on
Windows, or $XDG_CONFIG_HOME/orca (default ~/.config/orca) on Linux.
AGENTCAT_ORCA_DATA_DIR selects another local data directory. CLI/dev-runtime
overrides require this explicit metadata directory before plan discovery runs,
so they cannot silently attach production profile metadata to another runtime.
The metadata layout was verified on macOS; missing/incompatible layouts on other
hosts leave plans unknown without affecting quota discovery.

Privacy

The connector is local-first.

• No prompt text is intentionally stored.
• Claude/Gemini hook payloads are recursively sanitized before persistence.
• The local daemon listens only on 127.0.0.1.
• Nothing is uploaded by this repo. Server sync is a later product layer.

HTTP API

curl http://127.0.0.1:8765/healthz
curl http://127.0.0.1:8765/v1/snapshot
curl http://127.0.0.1:8765/v1/contract

/v1/contract is the connector-owned compatibility contract for both apps. It
declares the snapshot schema, shared and platform-specific capabilities,
compatibility aliases, and safe fallback behavior. Golden app fixtures live in
contracts/fixtures/.

Agent Cat can read ~/.agentcat/latest-snapshot.json or call the local API. The snapshot includes usage plus activity.processes, activity.countsByProvider, activity.totalCPUPercent, activity.totalMemoryBytes, activity.memoryBytesByProvider, activity.runnableProcessCount, activity.activityScore, and activity.motionStage so sandboxed Mac builds can use the connector instead of direct process scanning.

activity.motionStage is based on current activity, not raw agent count. The connector uses totalCPUPercent + runnableProcessCount * 4 as the activity score and emits the same four stages as the app: sleeping when no agent process is present, walking while processes are present but mostly waiting, running from 7 points, and sprinting from 22 points.

Memory usage is local RSS memory from /bin/ps, exposed per process as memoryBytes and grouped by provider as memoryBytesByProvider. It does not inspect prompts, transcripts, or model responses.

activity.runtimeModes is an optional local-only signal for high-effort agent sessions. Claude Code UserPromptSubmit hooks detect ultrathink / ultracode in memory, discard the prompt text, and persist only a short-lived flag such as mode=ultrathink, confidence=exact, and privacy=prompt_text_discarded. Metadata-only effort signals such as effort.level=xhigh and Codex model_reasoning_effort=xhigh are normalized as mode=effort_xhigh without reading prompts or transcripts. Claude Stop hooks clear the flag. No prompt text, file paths, transcripts, or conversation bodies are persisted.

On Windows, Agent Cat prefers PowerShell 7 (pwsh) when available, tries a fast Get-Process scan first, and only falls back to richer command-line scanning or tasklist when needed. Slow corporate environments can raise the scan timeout in ~/.agentcat/settings.json:

{
  "windowsProcessScanTimeoutSeconds": 8
}

Limits

GET /v1/snapshot and the background snapshot loop are local-only: they read local logs, configured caps, and native local status artifacts without calling provider quota APIs or discovered credentials. Managed OAuth account cards refresh their own remote quota separately, and GET /v1/usage remains the explicit legacy on-demand compatibility endpoint.

When a remote quota refresh is explicitly requested, Agent Cat reports remaining quota when a provider exposes it through the same local auth state used by its CLI:

• Codex: reads ~/.codex/auth.json, then calls the ChatGPT Codex usage endpoints for rolling 5-hour/7-day utilization, reset times, available reset credits, and Codex credit/spend-cap state. Reset credits are reported only as availability/metadata; this connector never redeems them.
• Claude Code: reads Claude Code OAuth credentials from Keychain or ~/.claude, then calls the Claude Code OAuth usage endpoint for 5-hour/7-day/model utilization plus monthly extra-usage credits.
• Gemini CLI: reads ~/.gemini/oauth_creds.json and ~/.gemini/settings.json, then calls Gemini Code Assist loadCodeAssist and retrieveUserQuota for model request quota fractions and reset times.
• Fallback: if live quota lookup fails, Codex/Claude still use the latest local status-line or session token_count event when available.

The normalized snapshot includes providers.<name>.limits.quotas[]. Each quota entry prefers remaining or remainingPercent, with usedPercent and resetAt for progress meters. Some providers expose percentages only, not absolute token or request counts; Agent Cat marks unavailable values as unavailable instead of guessing.

For missing or manually managed caps, use ~/.agentcat/limits.json; configured values override compatible auto-detected token caps while live quota cards remain visible.

Example:

{
  "providers": {
    "codex": {
      "week": 1000000000,
      "month": 4000000000,
      "session": 200000
    },
    "claude": {
      "week": 500000000,
      "month": 2000000000,
      "session": 200000
    },
    "gemini": {
      "week": 500000000,
      "month": 2000000000,
      "session": 1000000
    }
  }
}

Uninstall

curl -fsSL https://raw.githubusercontent.com/yong076/agentcat-connectors/main/uninstall.sh | bash

For a cloned checkout:

./uninstall.sh

Uninstall removes the LaunchAgent, binary link, and Agent Cat-managed config entries. Local usage data under ~/.agentcat is retained unless you remove it manually.

Development

python3 -m py_compile bin/agentcat scripts/install.py
bin/agentcat snapshot --json

Codex Skill

This repo also includes skills/agentcat-usage/SKILL.md so Codex-style agents can be taught to call agentcat snapshot --json instead of guessing local usage.