ORGONAUT
Login Signup
Docs
Imports and setup
Orgonaut Docs

AI Tooling usage sync (Claude Code)

Plan availability: AI Tooling usage sync is available on the business, enterprise, and agency plans.

Use Settings → AI Tooling to connect AI coding-tool providers and ingest per-user usage analytics into Orgonaut. Usage data is matched to actors by email address and surfaced on actor profiles, team pages, and department pages.

The AI Tooling settings page is visible only to roles that include integration management. In the default tenant role bundles that means owner and admin.

Unlike HRIS integrations (one provider per tenant), multiple AI Tooling providers can be active simultaneously. The first supported provider is Claude Code via the Anthropic Admin API; additional providers (Cursor, Copilot, Codex) will follow.

Connect Claude Code

  1. Open /settings/integrations/ai-tooling.
  2. Click the Connect action on the Claude Code card.
  3. Enter your Anthropic Admin API key (begins with sk-ant-admin...). This key is available from the Anthropic Console under Settings → Admin API keys. The key must have organisation-level read access for usage reports.
  4. Choose where incoming usage data applies:
    • Live Baseline
    • one or more active scenarios
    • all future scenarios (optional)
  5. Click Test connection to validate the key against the Anthropic API (GET /v1/organizations/me). A successful test confirms the organisation name and API connectivity.
  6. Save the connector to activate nightly sync.

The API key is stored encrypted at rest in the config_encrypted column on the integration record. It is never displayed in the UI after saving.

What data is synced

Each nightly sync fetches the previous day's Claude Code usage report from the Anthropic Admin API (GET /v1/organizations/usage_report/claude_code). The report contains one record per user per day, identified by the user's email address.

Fields ingested per daily record:

Field Description
source_email Email address from the Anthropic usage report
usage_date The calendar date of usage
sessions_count Number of Claude Code coding sessions
lines_added Lines of code added
lines_removed Lines of code removed
commits_count Number of commits made
pull_requests_count Number of pull requests created
total_input_tokens Total input tokens consumed across all models
total_output_tokens Total output tokens generated
total_cache_read_tokens Cache read tokens
total_cache_creation_tokens Cache creation tokens
total_cost_cents Total cost in USD cents
tool_actions Tool action counts (e.g. edit_tool accepted/rejected)
model_breakdown Per-model token breakdown

Actor matching

The sync engine matches each usage record to an Orgonaut actor by email address:

  1. Look up actors where email matches the source_email from the usage report.
  2. If a match is found, the record is linked to that actor and appears on their profile.
  3. If no match is found, the record is stored with actor_id = null and the email appears in the Unmatched emails section on the AI Tooling settings page.

Unmatched records are retained and will automatically match if a matching actor is created or their email is updated later. Re-running a sync will re-attempt matching for previously unmatched records.

Nightly sync schedule

  • Nightly sync runs at 03:00 server time.
  • The sync fetches the previous day's usage data.
  • Each active AI Tooling integration dispatches a separate queued job.
  • Matched usage records queue aggregate refresh jobs for affected placements, so team and department rollups update after the queue finishes processing rather than being recomputed live on page load.
  • Sync results are recorded in integration_sync_logs with kind = reconcile.
  • Syncs are idempotent — re-running for the same date upserts records rather than creating duplicates.
  • If a tenant is downgraded below AI Tooling plan availability, scheduled sync jobs no-op until the tenant upgrades.

Backfill historical data

To import usage data from before the connector was activated:

  1. Open /settings/integrations/ai-tooling.
  2. Use the Backfill action on the connected provider.
  3. Enter a start date and end date for the historical range.
  4. Click Run backfill to queue a backfill job.

Backfill runs are logged with kind = backfill in the sync logs. The Anthropic Admin API supports historical data retrieval, so backfill can cover any period for which data exists in your Anthropic organisation.

Scenario targeting

AI Tooling usage data respects the same scenario targeting as HRIS sync:

  • Baseline: usage records are written to the live baseline (scenario_id = null).
  • Specific scenarios: records are also written to each selected active scenario.
  • All future scenarios: when enabled, newly created scenarios automatically receive usage data from subsequent syncs.
  • Archived scenarios and snapshots are excluded from sync writes.

You can update scenario targeting at any time from the AI Tooling settings page.

Where usage data appears

Actor profiles

When an actor has matched AI Tooling usage data, their profile page (/people/{id}) displays an AI Tooling Usage section with:

  • Summary cards: last month cost, month-to-date cost, sessions, commits, pull requests, lines added, lines removed, and active providers.
  • Cost trend chart: daily cost over a selectable time range (MTD, Last Month, 3M, 6M, All).
  • Activity chart: daily sessions, commits, and pull requests as a stacked bar chart.

If no usage data exists for an actor, the section is hidden.

Team pages

Team show pages display aggregated AI Tooling metrics for all team members:

  • Last month cost, month-to-date cost, and active user count.
  • Cost trend chart for the team.
  • Per-member breakdown table showing individual cost and activity.

Department pages

Department show pages display both direct and subtree aggregated metrics:

  • Direct metrics: actors placed directly in the department's org unit.
  • Subtree metrics: all actors across the department and its descendant org units.
  • Cost cards for direct and subtree, monthly and month-to-date.
  • Aggregated session, commit, PR, and lines-added counts.
  • Cost trend chart for the department subtree, rendered from the stored aggregate snapshot after background rollups complete.

Manage an existing connection

From the AI Tooling settings page you can:

  • Sync now: trigger an immediate sync for yesterday's data.
  • Backfill: import a historical date range.
  • Pause sync processing.
  • Resume sync processing.
  • Disconnect to deactivate the integration and remove stored credentials.

The page also shows:

  • current connection status
  • last sync timestamp
  • recent sync log entries
  • unmatched email addresses (usage records that could not be matched to an actor)

Operational runbook

Where to look when sync fails

  1. Open /settings/integrations/ai-tooling.
  2. Review the connection status badge and last sync timestamp.
  3. Check Recent sync logs for failed entries.
  4. Open View run on a failed log entry for detailed diagnostics including error messages and affected records.

How to re-run a sync

Use the Sync now action to re-run the sync for yesterday's data. For older dates, use the Backfill action with a specific date range. Both operations are idempotent and safe to repeat.

Common issues

Symptom Likely cause Resolution
Test connection fails with 401 Invalid or revoked Admin API key Generate a new key in the Anthropic Console
Test connection fails with 403 Key lacks organisation-level permissions Check key scopes in the Anthropic Console
Sync completes but no data appears No Claude Code usage for the synced date Verify usage exists in the Anthropic Console usage dashboard
Records appear as unmatched Actor email does not match source email Update the actor's email in Orgonaut or verify the email in Anthropic
Costs show as $0.00 Usage exists but Anthropic reports zero cost Check the Anthropic usage dashboard for the same period

API endpoints

AI Tooling usage data is available through the REST API for programmatic access. All endpoints require the integrations.ai-tooling feature and the ai-tooling.manage ability on the Bearer token.

Endpoint Description
GET /api/v1/ai-tooling/usage Paginated daily usage records with actor, provider, and date filters
GET /api/v1/ai-tooling/actors/{id}/summary Actor cost and usage summary (last month + MTD)
GET /api/v1/ai-tooling/actors/{id}/series Daily time series for charts
GET /api/v1/ai-tooling/teams/{id}/summary Team aggregate cost and usage
GET /api/v1/ai-tooling/departments/{id}/summary Department aggregate with scope=direct or scope=subtree

See the API reference for full parameter and response documentation.

Connection health

Connection health is indicated by a status badge on the AI Tooling settings page:

  • active: connector is live and syncing nightly.
  • paused: connector is configured but sync is suspended.
  • error: the last sync or connection test failed.
  • disconnected: connector has been removed.

When a connection transitions from healthy to error state, tenant owners and admins receive a notification and email alert. A cooldown (default 24h) suppresses repeated alerts for the same ongoing failure. Recovery from error back to healthy triggers an informational notification.