sting

sting

Query GitHub or GitLab commits, GitHub PR activity during a window, or current personal PR work. Return structured evidence to an LLM agent or a terminal.

sting is a single binary with subcommands:

• sting init — guided first-time setup (strongly recommended).
• sting auth — authenticate with GitHub or GitLab via OAuth (auth github, auth gitlab, auth status, auth logout). The verbose auth login github / auth login gitlab forms are also supported and behave identically.
• sting mcp — runs an MCP server over stdio exposing four read-only tools: get_commits, get_repo_activity, get_prs, and get_pr_inbox.
• sting prs — reports PR opening, merging, and unmerged-closure actions during a window.
• sting inbox — finds current open PRs you authored, are assigned to, or are requested to review.
• sting <query flags> — prints a Markdown or JSON report locally.
• sting activity — summarizes what happened in one GitHub repository over a window, without naming an author.
• sting install / uninstall / install list — register the MCP server with your agent runtimes (Claude Code, Codex, OpenCode, Grok).

Configuration is resolved with viper (defaults < config file < env < flags), so dedicated read-only PATs can live in sting's own config instead of relying on ambient provider tokens.

Install

brew tap skaphos/tools https://github.com/skaphos/homebrew-tools
brew install --cask skaphos/tools/sting

Linux packages

.deb and .rpm packages for x86-64 and arm64 are attached to every release:

sudo dpkg -i sting_<version>_amd64.deb     # Debian, Ubuntu
sudo rpm -i sting-<version>-1.x86_64.rpm   # Fedora, RHEL, openSUSE

There is no hosted apt or yum repository. Shipping a .deb is not the same as running a package repository, and sting does not run one — hosting signed repositories is a materially larger commitment (DECISIONS/0001 puts it out of scope). Upgrading means downloading the next release's package.

Or install from source:

go install github.com/skaphos/sting/cmd/sting@latest

sting version reports the installed module version for this path — the binary reads the version the Go toolchain records, so it is not limited to release builds.

Or build from this repo:

go -C tools tool task build      # -> ./sting

A local build reports a pseudo-version and the revision it was built from, marked (modified) when the working tree is dirty. A build made with -buildvcs=false records nothing, and sting version says so rather than inventing a value.

Upgrading

sting does not update itself. Upgrade through the channel you installed from:

sting version reports what you are running, so you can tell whether an upgrade is needed. Nothing in sting checks for updates in the background.

There is deliberately no sting update subcommand: verifying a release properly in-process would more than double the binary for every user, and shipping a self-updater that skips verification would be worse than shipping none. See ADR 0011.

Getting started

sting init          # guided setup (recommended)
sting auth github   # or sting auth gitlab
sting query --author yourhandle --window 7d

Authentication (recommended)

The modern way to authenticate is with OAuth using sting init and the sting auth commands.

First-time setup

sting init

This is a guided wizard that:

• Defaults to GitHub (the primary/recommended provider)
• Can launch the OAuth flow for you
• Sets your default provider in ~/.config/sting/config.yaml

You can also be explicit:

sting init github     # GitHub (default)
sting init gitlab     # GitLab

Manual authentication

# GitHub (uses the public Skaphos OAuth app on github.com)
sting auth github
sting auth github --hostname ghe.example.com   # GHES / bring-your-own app

# GitLab (device flow, same as `glab`)
sting auth gitlab
sting auth gitlab --hostname gitlab.example.com --client-id <YOUR_ID>

# The verbose `auth login <provider>` form is equivalent to `auth <provider>`:
sting auth login github
sting auth login gitlab

After authenticating you can check status or log out:

sting auth status
sting auth logout github
sting auth logout gitlab --hostname gitlab.example.com

Legacy PAT fallback

Personal Access Tokens are still fully supported as a fallback (especially useful in CI or air-gapped environments). Note that a configured PAT (token/gitlab_token in the config file, or STING_TOKEN/STING_GITLAB_TOKEN in the environment) overrides any stored OAuth credential for that provider/host — it does not merely fill a gap when OAuth is absent. Unset it if you want sting to use the OAuth credential instead.

# config file
token: ghp_xxx
gitlab_token: glpat_xxx

# or environment
export STING_TOKEN=ghp_xxx
export STING_GITLAB_TOKEN=glpat_xxx

See docs/oauth-app-registration.md for how to create the required OAuth applications and for important notes about trust, governance, and when organizations should register their own apps instead of using the public Skaphos ones.

sting auth --help also contains the current recommended patterns.

Agent integration (the main use case)

Register the MCP server with every detected runtime:

sting install                      # auto-detect Claude, Codex, OpenCode, Grok
sting install --claude             # just one runtime
sting install --scope project      # write project-scoped config in CWD
sting install --manual             # print snippets instead of writing
sting install list                 # show registration state per runtime
sting uninstall                    # remove entries (prompts unless --yes)

Running the server from a container

If you would rather not install sting locally, MCP clients that support a docker command can run the published image instead. It needs no Go toolchain and works on x86-64 and arm64:

{
  "mcpServers": {
    "sting": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "STING_TOKEN",
               "ghcr.io/skaphos/sting:latest"],
      "env": { "STING_TOKEN": "ghp_xxx" }
    }
  }
}

The image runs as a non-root user, contains no credentials, and starts the MCP server over stdio with no arguments. Credentials come from the environment, using the same STING_ names as the local binary.

Registering the local binary

install writes a sting mcp entry pointing at the current executable. Because get_commits is read-only (advertised via the MCP readOnlyHint annotation), the Claude snippet also prints a paste-ready permissions.allow block that auto-approves the tool — safe to accept without per-call prompts.

Installation and install --manual forward STING_TOKEN and STING_GITLAB_TOKEN by default, using each runtime's native configuration:

These are variable references, not token values: the installer never copies credentials from its own environment into runtime configuration. Reinstalling fills missing defaults while preserving explicit environment values, custom references, and existing Codex forwarding sources. Unset variables remain optional, so stored Sting OAuth credentials or config-file PATs still work.

The variables must exist in the agent runtime's environment when it starts. A token available in a terminal or an agent's shell tool is not proof that the separate MCP launcher has it. GUI launches may not load .zshrc; launch the runtime from an environment containing the exported variables, or use Sting's credential store. After upgrading Sting, rerun sting install for the selected runtimes and restart their MCP servers to apply the forwarding defaults.

The syntax follows the runtime documentation: Codex, Claude Code, Grok, and OpenCode.

Then ask the agent naturally:

Give me all the commits of mfacenet in the last week and tell me what he's working on.

The tool returns structured commit data plus a Markdown summary, so the agent has clean material to describe the work.

CLI usage

# Last week of an author's commits, anywhere GitHub has indexed (Markdown).
sting --author mfacenet --window 7d

# JSON for piping into other tools.
sting --author mfacenet --window 7d -o json

# Within specific repos (most complete; works on private repos with a token).
sting --author mfacenet --scope repos --repos skaphos/sting,skaphos/other

# Across every repo in an org.
sting --author mfacenet --scope org --org skaphos --window 2w

# GitLab project commits.
sting --provider gitlab --author mfacenet --scope repos --repos skaphos/sting

# GitLab group commits, including projects in subgroups.
sting --provider gitlab --author mfacenet --scope org --org skaphos --window 2w

# Explicit bounds and per-commit line stats.
sting --author mfacenet --since 2026-05-01 --until 2026-05-15 --stats

# File-level evidence without full patches.
sting --author mfacenet --scope repos --repos skaphos/sting --window 7d --files

# Full bounded diffs for LLM analysis. This implies --files.
sting --author mfacenet --scope repos --repos skaphos/sting --window 7d --diffs --max-diff-bytes 60000

Run sting --help (or sting <command> --help) for the full flag list. Queries return at most 100 commits by default to avoid routine rate-limit pressure; pass --max-commits 0 only when you intentionally want an exhaustive scan.

Every query is also bounded by a request ceiling (max_requests, default 500). Reaching it returns the evidence gathered so far rather than aborting, so a bounded run still exits 0. JSON and Markdown report the consumed request cost and a budget-bounded disclosure with the reason and next safe action. If a provider fails after gathering has begun, sting emits the partial evidence and still reports the provider error; it does not replace gathered commits with an empty result.

Repository activity (sting activity)

sting query answers "what did this person do". sting activity answers "what happened in this repository" — no author required:

# What happened in a repository over the last week.
sting activity --repo skaphos/sting --window 7d

# A specific branch and explicit bounds, as JSON.
sting activity --repo skaphos/sting --ref release/1.x \
  --since 2026-07-01 --until 2026-07-08 -o json

# Check the cost before paying it. Gathers no evidence.
sting activity --repo skaphos/sting --window 30d --estimate

# Cap what a run may consume. A bounded run still exits 0.
sting activity --repo skaphos/sting --window 90d --max-requests 50

# Attribute changed paths to specific commits. Costs at least one request per commit.
sting activity --repo skaphos/sting --window 7d --enrich-commits 5

The output has four parts: the window's commits with full messages, the aggregate per-file change set, the correlations between them, and a cost report. It stays cheap by construction — the request count grows with commit pages, not commit count, so a 250-commit window costs about five requests rather than about 250.

The comparison is collected before optional per-commit enrichment. Enrichment fetches commits and their file pages in order, so a small request budget retains the same subset each run. File pagination can cost more than one request per commit; estimates assume one file page per enriched commit and can understate that cost. Estimates include their own probes and do not gather evidence.

JSON includes commits_collected, change_set_collected, and estimate_only flags to distinguish verified empty results from stages that never completed. Provider file caps and other limitations still appear in disclosures. On a provider error or cancellation, gathered commits, file pages, and comparisons are retained with a collection-failed disclosure: the CLI prints them before exiting nonzero, and MCP returns them in a tool error result. Partial enrichment retains files but leaves enriched false until all file pages are fetched.

What it does not cover

• It is a net comparison. The change set compares the window's start and end states, so a file created and deleted inside the window, or edited and then reverted, does not appear, and intermediate revisions are collapsed into one net change. The commit list still shows that work; the change set does not.
• One reference at a time. It covers a single branch or tag. Work on other branches, forks, or unmerged pull requests is not included.
• --author narrows the commits, not the change set. A boundary comparison has no notion of authorship, so the change set covers every author who touched the reference in the window. Boundaries come from an unfiltered listing; a second, author-filtered listing supplies the commit view, even when that author has no matches. These extra listing pages (and an extra estimate probe) are included in request accounting. The result says so explicitly.
• Attribution is labeled. Correlations are observed only when per-commit data was actually fetched (--enrich-commits); otherwise they are inferred from a declared rule, and paths matching no rule are left unattributed rather than guessed at.
• GitHub only. --provider gitlab is rejected with a specific message; GitLab commit queries via sting query are unaffected. The GitHub-only MCP activity tool selects GitHub even when the server defaults to GitLab for get_commits.
• Windows are bounded by committer date, which GitHub's API filters on. That differs from author date after a rebase, cherry-pick, or amend; the result records which basis was used.

Every one of these limits is also emitted as a disclosure in the output, so an agent reading the result sees them rather than having to consult this document.

Evidence depth

The default query returns commit metadata and messages only. Use the evidence flags when you want an agent to explain the actual code changes:

• --stats adds per-commit additions, deletions, and total changed lines.
• --files adds changed file paths, statuses, and per-file line counts (and also populates the per-commit totals).
• --diffs adds patch text for each changed file and implies --files.
• --max-diff-bytes caps patch text per commit; truncated files are marked in JSON and Markdown.
• --prs (GitHub, scope=repos/org) also discovers commits on open pull-request branches. Unmerged work is not on a default branch, so commit search and branch listing miss it; this enumerates open PRs per repo and merges author-matching, in-window commits. Each result carries a source field (search, repo, or pull/<n>) so the discovery origin is auditable, and Markdown flags PR-branch commits with [pull/<n>]. It costs extra API calls (one PR list plus one commit list per open PR), so it is off by default.

GitHub fetches this evidence from per-commit detail calls. GitLab uses with_stats for line stats and commit diff calls for file evidence. Keep full diffs explicit because they cost extra API calls and can be token-heavy for an LLM context. The MCP get_commits tool therefore treats an omitted include_diffs argument as false, even when the server config enables diffs; callers must explicitly pass include_diffs: true to request patch text.

Scopes

Query windows are normalized to UTC by both the commit and activity resolvers. Explicit --since overrides --window; an omitted --until uses the request time. Equivalent RFC3339 offsets represent the same window.

GitHub discovery paths use different date bases:

GitHub results expose window_date_basis as author, committer, or mixed (repository/org queries with PR augmentation enabled). Each returned commit also names its own basis. date remains the author timestamp; the additive committer_date preserves the committer timestamp when supplied. The existing schema version is retained because these fields are additive, not a replacement for date (see ADR 0004). An omitted basis means unspecified, not author date.

After rebasing or cherry-picking, a repository query can return a commit whose author date is outside the window but whose committer date is inside it. Search can select the opposite case. Sting preserves these provider semantics; filtering an already time-limited repository listing by author date would not recover commits omitted by the provider. See the recorded provider verification.

GitLab search scope is not supported yet. GitLab's search API does not map cleanly to sting's date-bounded author query contract, so use repos or org with --provider gitlab.

GitHub search can return HTTP success while reporting incomplete_results. Sting checks every page, retains returned commits, and marks the result truncated with a search-incomplete disclosure. Searches exceeding the 1,000-result bound carry search-capped; sting does not request pages beyond that bound. These limits also apply to empty responses. Narrow the window, retry, or use repository/org scope to gather additional evidence. See GitHub search limits and timeouts.

In org scope sting enumerates the org's repos and then lists each repo's commits. A repo that cannot be listed for a reason specific to that repo — an empty repository (GitHub returns 409), or one that is gone or not visible to the token (403/404/410/451) — is skipped rather than aborting the whole scan, so one bad repo can no longer sink an entire org query. Skipped repos are reported in the result: a skipped array in JSON (each entry has a repo and a reason) and a Skipped line in Markdown. Global failures (rate limits, auth, server errors) still abort, since continuing would only retrip them on every remaining repo. The GitLab org scope skips unreadable projects the same way. The explicit repos scope does not skip: a repo you named yourself fails loudly so a typo or access gap is not silently dropped.

Searching private orgs

A bare search is a global author query, which GitHub limits to public repos. To reach a private org via the search index, scope the query by combining search with --org (or --repos):

# Adds `org:Alaska-Airlines-Shared` to the search query.
sting --author mfacenet --scope search --org Alaska-Airlines-Shared --window 7d

--author accepts either a GitHub login or a commit email. An email is detected automatically and queried with the author-email: qualifier, since GitHub's commit search does not match emails against author:. Note the two can return different results: a login matches commits GitHub attributes to that account, while an email matches the raw commit author regardless of account linkage.

Two requirements for any private-org result:

• Token access — the PAT must have read access to the private repos. If the org enforces SAML/SSO, the token must be SSO-authorized for it (classic PAT) or approved with repo/contents read (fine-grained PAT); otherwise private results are silently excluded.
• Indexing — commit search only covers default branches and skips commits attributed to an email not linked to the GitHub account.

For the most complete private-org coverage (not limited by the search index), prefer --scope org --org Alaska-Airlines-Shared, which lists commits per repo directly. search --org is faster (one query vs. per-repo listings) but subject to the indexing caveats above.

Time window

--window accepts 7d, 2w, 48h, 30m, etc. --since/--until accept YYYY-MM-DD or RFC3339. --since overrides --window; --until defaults to now.

Pull request activity

sting prs --author octocat --window 7d reports PR openings, merges, and unmerged closures during the window, including closures followed by later reopening. Remaining open does not qualify by itself; --time-basis updated explicitly selects latest updates. Current state defaults to all, and drafts are included. --state closed means currently closed without a merge. The MCP equivalent is get_prs.

Results carry an independent schema, qualifying action timestamps, current metadata, request costs, and separate discovery/evidence completeness. Defaults are 100 PRs and 500 requests; explicit zero disables the selected cap. Lifecycle history uses extra budgeted requests per candidate whose record could still hold an in-window action; a PR last updated before the window is skipped without a request, because opening, merging, closing, and reopening each advance that timestamp. Runs that skip records this way say so, and how many, in a history-bounded disclosure. Optional PR details, diffs, and checks are not fetched. Every disclosure carries a next_action when a safe one exists, and unavailable optional metadata is summarized once per field set, with per-record detail in each missing_fields. Unrestricted search is public-only and subject to GitHub search coverage limits. Use explicit targets for credential-visible private work. include_prs on commit queries still means commit discovery from open PR branches. PR activity is GitHub-only.

Repository activity also supports sting prs --scope repos --repos acme/api,acme/web without an author filter. sting prs --scope org --org acme enumerates accessible repositories and discloses individual unreadable targets. Authentication and rate-limit failures stop collection while preserving evidence. Each scope uses the configured activity window.

Personal PR inbox

sting inbox --scope org --org acme finds currently open PRs you authored, are assigned to, or are directly requested to review. Older work stays eligible; drafts are included. --user octocat overrides the user resolved from sting's dedicated GitHub credential. Use --no-draft to exclude drafts. The MCP equivalent is get_pr_inbox.

All three reasons are combined and labeled on one entry per PR. Team-only requests, fulfilled/removed requests without another current relationship, and completed PRs do not qualify. Search verifies relationships through repository PR pages, which share the request budget. Provider changes and interrupted verification are disclosed; an incomplete report may not contain every match. Neither workflow assigns, reviews, closes, or merges PRs.

For example, sting prs --scope org --org acme --time-basis closed --window 2w -o json asks what closed during the window; sting inbox --scope repos --repos acme/api -o json asks what needs attention now. JSON carries all evidence; Markdown displays its facts. Own request/result caps return successful partial reports. Provider/identity failures return partial evidence with a nonzero CLI exit or MCP IsError, including when no PRs were found.

MCP validates shared settings at startup and workflow-specific settings before each call. An invalid activity default cannot block the inbox; an affected activity call fails locally. Malformed configuration or invalid shared settings still prevent MCP startup.

Configuration

Resolved in increasing precedence: built-in defaults → config file → environment (STING_*) → flags. The config file is discovered as config.yaml under $XDG_CONFIG_HOME/sting, ~/.config/sting, ~/.sting, or the current directory, or pointed at explicitly with --config path.yaml.

Keys in parentheses are per-query request flags that override the resolved default for a single invocation. See config.example.yaml.

Development

task tidy vet test # tidy + vet + test
task test-race     # tests under the race detector
go -C tools tool task test-integration # built CLI and MCP stdio end-to-end tests
task run -- --author octocat --scope repos --repos octocat/Hello-World --since 2008-01-01

CI publishes a required Integration Tests check on every pull request. The suite builds sting, executes CLI queries, and initializes/calls both MCP tools over stdio against local HTTP fixtures, with isolated configuration and home directories. It checks JSON stdout, nonzero exits with retained partial evidence, read-only tool annotations, and structured MCP results. It requires no provider credentials or external API access and also runs in task ci.

Package and API reference (godoc):

go doc ./...                # synopsis of every package
go doc ./ghclient Client    # a specific type
go doc ./gitlabclient Client

Documentation

• CHANGELOG.md — notable changes.
• OAuth App Registration Guide — how to create the OAuth apps (public Skaphos apps + bring-your-own for enterprise/self-hosted).
• Architecture Decision Records — design decisions.
• Per-package godoc — see the go doc commands above.

Layout

Public packages (importable; the evidence contract — see ADR 0004):

model/                domain types (leaf) + Result SchemaVersion
config/               Config, viper keys, window/time parsing, query resolution
ghclient/             go-github wrapper + scope dispatch + normalization
gitlabclient/         GitLab REST wrapper + scope dispatch + normalization

Application layer (internal):

cmd/sting/            thin entrypoint -> internal/cli
internal/cli/         cobra command tree + viper wiring
internal/commitclient/ provider client selection
internal/render/      JSON + Markdown rendering
internal/mcpserver/   MCP server; four read-only commit/activity/PR tools
internal/mcpinstall/  runtime adapters (Claude, Codex, OpenCode, Grok)

Skaphos is a project of Rillan AI LLC, a Missouri limited liability company. © 2026 Rillan AI LLC. Released under the MIT License.