Overview & Concepts#

What is Gittensory?#

Gittensory is a deterministic control plane for Gittensor OSS contribution work 1. It gives contributors and maintainers structured signals before work turns into noisy PRs: official Gittensor context, repo queue health, collision risk, branch preflight, scoreability, maintainer packet context, and public-safe PR guidance 2.

Think of Gittensory as a decision-support and preflight tool. Before you spend time on a branch, Gittensory can tell you whether it's worth opening, what blockers stand between your diff and a merged PR, and what the estimated reward picture looks like under several scenarios. It ranks your next moves and drafts clean PR packets — but every action still requires your explicit approval 3.

Who is it for?#

Gittensory serves three distinct audiences 4:

• Miners — find the next move, clear queue pressure, and ship a PR packet that won't get flagged
• Maintainers — get confirmed-miner context without noisy check runs or score numbers polluting the public thread
• Coding agents — consume deterministic, structured tool schemas via MCP that an agent can actually plan against

Relationship to Gittensor (Bittensor Subnet SN74)#

What is Gittensor?#

Gittensor is Bittensor Subnet 74 (SN74) — a permissionless subnet that accelerates open source software development by rewarding meaningful contributions. Miners earn TAO tokens by making real, merged pull requests to recognized open source repositories. Validators authenticate account ownership, verify merged contributions, and score them based on code quality before publishing reward estimates 5.

How Gittensory fits in#

Gittensory sits between the miner and the subnet as an intelligence layer. It consumes official Gittensor registry data and scoring signals, then surfaces that context to help miners plan better work and help maintainers keep their review queue manageable.

Key points about this relationship:

• Gittensory depends on upstream Gittensor registry, scoring, and issue-discovery behavior. Scheduled drift detection continuously compares Gittensory's snapshots against upstream Gittensor sources to flag stale assumptions before they break your plan 6.
• When official Gittensor API stats are available, Gittensory uses them as the authoritative source for miner-recognized totals. Cached GitHub context is a clearly labeled fallback, not a primary source 7.
• Gittensory itself is a registered Gittensor repo target — it dogfoods its own registration-readiness logic 8.

What Gittensory is NOT#

To be precise about the boundaries 3:

Gittensory does not edit code, open PRs, post comments, close issues, merge pull requests, or apply labels without an explicit user- or maintainer-triggered flow 3. V1 ranks, explains, preflights, and drafts public-safe packets — nothing more 9.

Core Design Principles#

Three principles are foundational to every decision in Gittensory's design 10. Understanding them helps explain why the tool works the way it does.

1. Deterministic#

Gittensory's core decisions are predictable and repeatable. The same inputs always produce the same outputs. This means you can trust a plan recommendation today and re-run it tomorrow and get a consistent baseline to reason against 11.

Deterministic sorting, signal ranking, and regression tests are baked into the validation pipeline 12. Even when optional AI prose generation is enabled, the rule is explicit: "deterministic signals must remain authoritative. AI should rewrite facts, not decide them." 13 AI can make an explanation more readable, but it cannot change the underlying signal values.

Every agent run produces an auditable snapshot — a record of what was ranked, what was blocked, and why — so decisions are traceable 14.

2. Privacy-Preserving#

Gittensory analyzes your local branch without uploading source code 15. The MCP wrapper inspects local git metadata and sends only that metadata to the API. Attempting to enable source upload is an enforced failure: GITTENSORY_UPLOAD_SOURCE=true is not supported and fails closed 16.

Authentication uses GitHub Device Flow — Gittensory never asks for a Personal Access Token. The CLI exchanges the Device Flow result for a Gittensory session token backed by your GitHub identity. Your GitHub credentials never leave the authentication flow 17.

The public/private output boundary is strictly enforced 10:

• Private surfaces (MCP/API responses): full scoreability scenarios, trust context, wallet/hotkey info, blockers, maintainer friction
• Public surfaces (GitHub PR comments, check runs): sanitized, miner-confirmed status only — no scores, no estimated rewards, no wallet addresses

3. Non-Autonomous#

Gittensory is a base-agent layer, not an agent executor. Its role is to inform your decisions, not to make them for you 18.

The agent mode is explicitly described as copilot-only: it ranks, explains, preflights, and drafts public-safe packets. It does not edit code, open PRs, post comments, close issues, merge, or label from the local wrapper 9. Every action surface requires an explicit user or maintainer trigger.

This is a deliberate product boundary: Gittensory helps "people decide, act, configure, and measure contribution quality" — it does not become the actor 18. The tool is designed to remain quiet and useful without creating noise or taking actions you didn't ask for.

What Gittensory Provides#

Gittensory bundles several capabilities that are usually scattered across different tools — or simply unavailable to Gittensor miners — into a single structured signal layer 2.

Role-Aware Contributor Context#

Every analysis is filtered through the lens of your role. A miner sees decision packs and PR preflight results. A maintainer sees reviewability packets and confirmed-miner context. A coding agent receives structured JSON schemas designed for deterministic planning. The same underlying data surfaces differently depending on who's asking 19.

Official Gittensor Stats Integration#

Gittensory pulls from the official Gittensor API as its authoritative data source. When those stats are available, they are used directly — not approximated from cached GitHub data. Contributor profiles, outcome history, and scoring context all flow from the upstream registry 7.

Local MCP Preflight#

Before you open a pull request, run a preflight check against your local branch. Gittensory inspects git metadata, calls the API with your branch context, and returns a structured report: lane fit, scoreability blockers, open PR pressure, collision risk, and a ranked next-action recommendation — all without your source code ever leaving your machine 15 20.

Queue Health Monitoring#

Open PR pressure is one of the most common hidden blockers for Gittensor miners. Gittensory tracks how many open PRs are in flight, what their current state is, and how that pressure affects your estimated scoreability scenarios 21.

Collision Risk Detection#

Opening a PR that duplicates in-progress work is a costly mistake. Gittensory detects duplicate risk before you open, surfacing whether another miner is working on the same issue, whether similar diffs are already in queue, and what the risk-adjusted priority of your branch looks like 21.

Reviewability Assessment#

Not every diff is ready to review. Gittensory analyzes what's blocking your branch from being reviewed cleanly — unsquashed commits, missing issue links, hygiene issues, or maintainer friction — and projects what your scoreability would look like once each blocker is resolved 22.

Repository Configuration Quality Analysis#

For repo owners and maintainers, Gittensory tracks whether a repository is correctly configured for Gittensor participation: lane correctness, registry alignment, label/config quality, bounty tracking, and sync fidelity with the upstream registry 23.

Copilot-Only Next-Action Planning#

The base-agent mode produces a deterministic ranked list of next actions — what to work on, in what order, and why. This output is designed to be consumed directly by a coding agent (Codex, Claude, Cursor) without requiring the agent to reason about Gittensor internals. Gittensory supplies the structured context; the agent supplies the execution 11.

Scoreability Scenarios#

Every branch analysis returns up to six scoreability projections — estimates only, never guarantees, and never shown publicly 22:

These numbers appear only in private MCP/API responses and are never written to public GitHub surfaces 22.

Four Deployment Surfaces#

Gittensory operates across four distinct surfaces, each serving a different integration pattern and audience 24.

1. Worker API#

What it is: The backend intelligence engine, built on Cloudflare Workers + Hono + D1 + Queues.

Where it runs: https://gittensory-api.aethereal.dev

The Worker API is the authoritative processing layer. It handles contributor profiles, decision packs, PR packets, repository intelligence, agent run orchestration, bounty tracking, upstream registry sync, and GitHub webhook processing. All other surfaces are clients of this API 25.

The canonical API exposes 30+ endpoints organized around key workflows 26:

• Registry snapshots and change detection
• Contributor profiles and decision packs
• Agent planning, preflight, and PR packet generation
• Maintainer reviewability packets
• Bounty advisories
• GitHub webhook ingestion

Authenticated endpoints use Authorization: Bearer <token> with either a Gittensory API token or an OAuth session 27.

2. Frontend Worker#

What it is: A TanStack Start web application for browser-based access.

Where it runs: https://gittensory.aethereal.dev/

The frontend is deployed as a separate Cloudflare Worker and provides a visual interface to the same intelligence the API and MCP expose. It is the home for the documentation hub, the workbench application, and public-facing docs 28 29.

3. MCP Package#

What it is: A local stdio MCP wrapper — the first-class base-agent surface.

Install: npm install -g @jsonbored/gittensory-mcp@latest

The @jsonbored/gittensory-mcp npm package is the primary integration point for coding agents and individual contributors 30. It inspects local git metadata and calls the Gittensory API without uploading source contents 20.

It exposes five MCP tools to connected clients 31:

Compatible with Codex, Claude Desktop, and Cursor via init-client config generation. Also usable as a standalone CLI with commands for login, status, branch analysis, preflight, and diagnostics 32.

4. GitHub App#

What it is: Quiet PR inspection and maintainer commands, installed directly on GitHub repositories.

Default behavior: Low-noise. Non-miner, bot, and maintainer-associated PR authors produce no public output. Only confirmed Gittensor miners get output 33.

The GitHub App provides 34:

• One sticky public-safe comment per confirmed-miner PR — no scores, no wallet info, no reward estimates
• One configured label (default: gittensor) applied to confirmed-miner PRs
• Explicit @gittensory commands that maintainers and authorized authors can invoke
• Private maintainer reviewability packets returned to the requester — not posted publicly

Required repository permissions are intentionally minimal: metadata (read), pull requests (read), and issues (write). Optional check write permission is available only when minimal check runs are explicitly enabled 35.

Important: Private reviewability, scoring, wallet, hotkey, and reward/risk context never appears in public GitHub comments or checks 33.

Key Capabilities in Depth#

This section expands on the seven core capabilities introduced above, with more detail on how each works under the hood.

Building Private Contributor Decision Packs#

A decision pack is a canonical private payload assembled per contributor. It combines official Gittensor stats with cached GitHub context to produce a structured picture of your current standing: outcome history, lane context, active repo targets, data freshness indicators, and provenance metadata 36.

Decision packs are private by design — they contain Gittensor-specific scoring context that is never surfaced publicly. Access requires authentication through the MCP or API.

Analyzing Local Branches Without Uploading Source#

Branch analysis is local-first. The MCP wrapper reads git metadata from your working directory — commit history, branch structure, diff stats, file types — and sends only that metadata to the Gittensory API. Your source code never leaves your machine 15.

For contributors who want a local score preview before the API call, an optional scorer command can be wired in via the GITTENSOR_SCORE_PREVIEW_CMD environment variable. This scorer runs entirely on your machine and reads branch metadata JSON from stdin. Reference implementations ship with the package in both Node.js and Python (with tree-sitter) 37.

Explaining Private Reward and Risk Context#

When Gittensory returns analysis results, it explains the full reward and risk picture across six dimensions 21:

• Score blockers — specific issues (e.g., unsquashed commits, missing issue link) that gate scoreability
• Open PR pressure — how your in-flight queue affects current and projected scores
• Lane fit — whether this contribution targets a lane that's currently open and well-matched to your history
• Duplicate risk — probability that similar work is already in queue or has recently been merged
• Credibility assumptions — what your current credibility signal implies about reward projections
• Maintainer friction — signals that suggest a maintainer may be slow to review or has concerns about this type of contribution

Generating Public-Safe PR Packets#

When you're ready to open a pull request, Gittensory can generate a PR packet — structured content that helps you write a cleaner, more complete submission 38.

PR packets are designed to be public-safe: they contain context a reviewer needs (issue linkage, scope summary, hygiene notes) without leaking any private Gittensor signals (scores, wallet info, estimated rewards). The same sanitizer that governs GitHub App output applies to every PR packet 39.

Repository Intelligence Tracking#

For repo owners and maintainers, Gittensory continuously tracks the health of a repository's Gittensor participation 23:

• Lane correctness — are contributions targeting the right lanes?
• Registry changes — has the upstream Gittensor registry changed in a way that affects this repo?
• Queue health — is the open PR queue growing faster than it's being resolved?
• Label and config quality — are the Gittensor-related labels, issue templates, and config files in good shape?
• Collision tracking — are multiple miners targeting the same issue?
• Bounty tracking — what bounties are currently active and available?
• Sync fidelity — how closely does the repo's current state match what the upstream registry expects?

Upstream Drift Detection#

Gittensory runs scheduled comparisons between its cached snapshots and the live upstream Gittensor registry. When the registry changes — new scoring rules, new repo whitelist entries, updated issue templates — drift is flagged so you can update your assumptions before committing to a plan 6.

Next Steps#

Gittensory's documentation is organized into lanes based on your role. Start in the lane that fits your use case, then dip into core concepts as you need them 19.

For Miners#

You want to find better work, reduce queue risk, and ship cleaner PRs.

1. Quickstart — Install the MCP, sign in with GitHub Device Flow, and run your first branch analysis in under two minutes 17
2. Miner workflow — End-to-end guide for using Gittensory as part of your contribution workflow
3. Branch analysis — Understand what the MCP analyzes and how to interpret results
4. Scoreability — Deep dive into the six projection scenarios and what moves the needle

For Maintainers#

You want confirmed-miner context without check noise.

1. Install the GitHub App — Set up the GitHub App on your repository with minimal permissions
2. Maintainer workflow — Using @gittensory commands and private maintainer packets
3. Upstream drift — How Gittensory detects and surfaces registry drift

For Repo Owners#

You want to understand how your repository is positioned for Gittensor participation.

1. App install + scopes — Required and optional permissions explained
2. Privacy & security — Full public/private boundary documentation
3. Troubleshooting — Common configuration issues and fixes

For Agent Authors (Codex, Claude, Cursor)#

You want to wire Gittensory into your coding agent as a structured MCP data source.

1. MCP client setup — Connect Gittensory as a stdio MCP server
2. Branch analysis schema — Full JSON schema for tool inputs and outputs
3. AI summary boundaries — What AI can and cannot be used for in Gittensory outputs

Quick install:

⧉

npm install -g @jsonbored/gittensory-mcp@latest
gittensory-mcp login
gittensory-mcp doctor

Then head to the Quickstart to run your first analysis. 40