Hosted Reporting

Semantica can surface AI attribution on GitHub and GitLab through PR or MR comments, provider-native status surfaces, and dashboards. This page explains what the CLI does vs what the backend does, and how the pieces connect.

Architecture boundary

Component	What it does	Where it lives
CLI	Captures AI activity, computes attribution, pushes payload	This repository (`semanticash/cli`)
Backend/API	Receives payloads, renders PR or MR comments, creates GitHub check runs or GitLab commit statuses, serves dashboards	Semantica backend `(private)`

The CLI is fully functional without the backend. All local features - capture, attribution, checkpoints, playbooks, search, rewind, MCP - work offline.

What the CLI sends

After each commit, the background worker POSTs an attribution payload to {endpoint}/v1/attribution:

{
  "remote_url": "git@github.com:org/repo.git",
  "branch": "feature-branch",
  "commit_hash": "abc123...",
  "commit_subject": "Add retry logic",
  "checkpoint_id": "chk_...",
  "ai_exact_lines": 15,
  "ai_formatted_lines": 2,
  "ai_modified_lines": 1,
  "ai_lines": 18,
  "human_lines": 25,
  "total_lines": 43,
  "files_total": 3,
  "files_ai_touched": 2,
  "files": [ ... ],
  "providers": ["claude_code"],
  "provider_details": [{"provider": "claude_code", "model": "sonnet", "ai_lines": 18}],
  "playbook_summary": "Intent: Add retry logic | Outcome: Implemented exponential backoff",
  "cli_version": "0.4.2",
  "attribution_version": "v1",
  "pushed_at": 1710374400000
}

What the backend renders

GitHub PR comments

When a pull request is opened or updated, the backend aggregates attribution payloads for all commits in the PR and posts a summary comment showing:

Aggregate AI percentage across the PR
Per-commit breakdown
Provider and model information
Playbook summary (if available)

GitHub check runs

The backend creates a GitHub check run on each pushed commit with the attribution result. This appears in the PR's checks tab and can be configured as a required status check.

GitLab MR comments

When a merge request is opened or updated, the backend aggregates attribution payloads for all commits in the MR and posts a summary note on the MR.

GitLab notes are currently posted with the connected GitLab user's identity, not a Semantica-owned bot identity.

GitLab commit statuses

The backend creates a GitLab commit status on the MR head commit. This is not a GitHub-style check run. GitLab surfaces it through its commit and MR status UI.

Dashboards

The web dashboard at semantica.sh provides:

Per-repo AI usage trends over time
Team-level attribution aggregates
Per-commit detail drill-down
Provider breakdown

Authentication

The CLI authenticates with the backend via OAuth device flow or API key:

semantica auth login          # opens browser for OAuth (GitHub or GitLab)
semantica connect             # connects the current repo to the dashboard

Alternatively, set SEMANTICA_API_KEY for CI environments.

Tokens are stored in OS secure storage (macOS Keychain, Linux Secret Service) when available, with automatic refresh on expiry. On headless or CI environments without a keyring, credentials fall back to ~/.config/semantica/credentials.json (respects $XDG_CONFIG_HOME) with 0600 permissions.

Provisioning

For hosted reporting to work:

Backend access - your organization must have a Semantica backend instance
Authentication - the CLI must be authenticated (semantica auth login or SEMANTICA_API_KEY)
Repo connected - the current repo must be connected via semantica connect
Provider setup
- GitHub - the Semantica GitHub App must be installed on the target repository if you want PR comments and check runs
- GitLab - the target project must have a Semantica MR webhook. semantica connect attempts to create it automatically. If the connected user cannot manage project webhooks, the CLI prints the manual webhook URL and repo-specific secret to give to a maintainer.

The backend endpoint is resolved from the authenticated session. SEMANTICA_ENDPOINT overrides it for local development and testing.

Failure modes

Scenario	Behavior
Repo not connected	CLI works locally, no push attempted
Not authenticated	CLI works locally, no push attempted
Auth expired	Push fails silently, logged to `.semantica/worker.log`
Backend unreachable	10-second timeout, logged, worker completes normally
GitHub App not installed	Backend can still receive attribution, but cannot post PR comments or check runs
GitLab webhook not configured	Backend can still receive attribution, but cannot post MR comments or commit statuses
GitLab user lacks webhook permission	`semantica connect` still succeeds and prints manual webhook setup details
Playbook not yet generated	First push omits `playbook_summary`; a re-push after auto-playbook adds it

All push failures are best-effort. The CLI never blocks commits, the worker, or any local feature due to a backend issue.

Search documentation