global-executables

Global Executables

A public cross-ecosystem dataset of executable names, continuously collected from package ecosystems and exposed to AI agents via MCP.

global-executables builds and maintains a machine-readable index of executable names found across software package ecosystems.

It is designed to answer a deceptively simple question:

Is this executable name already in use?

This is especially useful when naming new CLI tools. Searching package names, repositories, or the web is not sufficient because a package name and the executable it installs are not necessarily the same.

Global Executables collects executable-level information, publishes it as structured data on GitHub, and makes the dataset directly accessible to AI agents through MCP.

Quick start: use it from your AI agent

The MCP server is read-only and needs no API key and no local dataset. It fetches only the files a query needs from the public dictionary branch and caches them in your user cache directory (revalidated with ETag; cached files keep working offline). It requires uv (uvx) or Docker.

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json or a project's .cursor/mcp.json):

{
  "mcpServers": {
    "global-executables": {
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}

Claude Code:

claude mcp add global-executables -- uvx global-executables mcp

VS Code (.vscode/mcp.json):

{
  "servers": {
    "global-executables": {
      "type": "stdio",
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}

Docker (any client; replace the command/args above):

{
  "command": "docker",
  "args": ["run", "-i", "--rm", "ghcr.io/asopitech-labs/global-executables-mcp:latest"]
}

Then ask, for example, "Is the command name envc already taken?". The agent calls check_executables; found: true is a collision, while status: "unknown" means "not in the current index", not "free", because some sources are partial.

Variable	Effect
GLOBAL_EXECUTABLES_DATASET_ROOT	use a local checkout of the dictionary branch instead of HTTPS
GLOBAL_EXECUTABLES_CACHE_DIR	cache location (default ~/.cache/global-executables, ~/Library/Caches/global-executables, or %LOCALAPPDATA%\global-executables\Cache)
GLOBAL_EXECUTABLES_OFFLINE=1	serve only cached files, never touch the network

uvx global-executables mcp --help lists the same options as flags. The package is published to PyPI from release 1.3.0; see docs/MCP.md for HTTP transport and running from a source checkout.

---

Why Global Executables?

Suppose you are designing a new CLI and considering:

envc
evcr
evpk
envcp

Before recommending or adopting one of these names, you want to know whether it is already installed as a command by an existing package.

The relevant relationship is:

executable
    ↓
provider
    ↓
package
    ↓
ecosystem

rather than simply:

package name

Global Executables creates this missing cross-ecosystem index.

---

Goals

Global Executables aims to provide:

• a public dataset of real-world executable names;
• cross-ecosystem coverage;
• traceable provenance for every collected executable;
• reproducible dataset generation;
• Git-friendly structured data;
• machine-readable indexes for efficient lookup;
• historical tracking of executable names;
• MCP access for AI agents;
• explicit dataset coverage and freshness information.

The dataset itself is the primary artifact.

The MCP server is an access layer over that public data, not the source of truth.

Try the live Index Playground to inspect crawl progress and run read-only check, search, similar, coverage, and assess queries directly in a browser. The playground is a static GitHub Pages client over the public JSON dataset; no query data is sent to a third-party API.

The program and published data have independent lifecycles. Program source, schemas, tests, and documentation live on main; the generated JSON dictionary lives on the orphan dictionary branch. The stable raw-data base URL is:

https://raw.githubusercontent.com/asopitech-labs/global-executables/dictionary

See the dictionary branch migration note for the branch contract, local setup, and the main URL cutover.

Go development follows the JetBrains Modern Go Guidelines. See the Go crawler development and build contract for the versioned review, build, test, security, and release workflow.

---

Architecture

Package ecosystems
        │
        ├── Debian / Ubuntu
        ├── Arch Linux
        ├── Homebrew
        ├── npm
        ├── PyPI
        ├── crates.io
        ├── Go modules
        ├── RubyGems
        ├── Packagist / Composer
        ├── ConanCenter
        ├── vcpkg
        ├── xmake-repo
        └── others
                │
                ▼
          GitHub Actions (`main`)
                │
       collect / normalize
                │
                ▼
  `dictionary` branch dataset
                │
        ┌───────┴────────┐
        │                │
        ▼                ▼
   GitHub / raw        MCP Server
      data                │
                          ▼
                     AI agents

GitHub Actions periodically collects upstream package information, normalizes executable records, regenerates indexes, validates the dataset, and publishes the resulting files.

---

Data Model

The canonical unit is an executable name.

Each executable is represented by a structured file containing its known providers.

Conceptually:

{
  "command": "example",
  "providers": [
    {
      "ecosystem": "example-ecosystem",
      "package": "example-package",
      "version": "1.0.0",
      "repository": "https://example.com/repository",
      "source": "example-source",
      "confidence": "direct"
    }
  ],
  "first_seen": "2026-08-14",
  "last_seen": "2026-08-14"
}

A single executable may have multiple providers across multiple ecosystems.

---

Repository Layout

The dictionary branch contains only published artifacts:

dictionary/
├── data/
│   ├── executables/
│   │   ├── en/
│   │   │   ├── envc.json
│   │   │   └── envcp.json
│   │   └── gi/
│   │       └── git.json
│   │
│   ├── indexes/
│   │   ├── prefix/
│   │   ├── length/
│   │   ├── ecosystem/
│   │   └── trigram/
│   │
│   ├── metadata.json
│   └── history.json
└── reports/
    ├── production-crawl.json
    └── production-refresh.json

The main branch separately keeps fixtures/, schema/, src/, tools/, tests/, docs/, playground/, and .github/workflows/; it does not track the generated paths above. The canonical dataset uses ordinary structured files rather than requiring a database server.

Derived indexes are reproducible and may be regenerated from the canonical executable records.

---

Lookup

Exact lookup maps directly to the repository structure.

For example:

envcp
  ↓
prefix: en
  ↓
data/executables/en/envcp.json

This allows consumers to retrieve individual records without downloading or querying a centralized database.

Derived indexes support broader queries such as:

• prefix;
• executable length;
• ecosystem;
• similar names.

---

Data Sources

Collectors are independent for each ecosystem.

Potential sources include:

Ecosystem	Executable evidence
Debian / Ubuntu	package file contents
Arch Linux	package files database
Homebrew	formula/package contents
npm	ecosyste.ms critical population; npm registry bin metadata
PyPI	distribution entry points / console_scripts
crates.io	Rust binary targets
Go modules	package main directories in module archives
RubyGems	gemspec executables metadata
Packagist / Composer	composer.json bin declarations in Packagist metadata
ConanCenter	bin/ contents of the built package, read from conanmanifest.txt
vcpkg	vcpkg_copy_tools(TOOL_NAMES ...) declarations in portfile.cmake
xmake-repo	set_kind("binary") packages, whose command name is inferred
others	ecosystem-specific executable metadata

C and C++ have no single registry, so three recipe repositories are read instead, and each contributes the strongest evidence it actually carries. vcpkg names the tools a port installs, because naming them is what installs them. ConanCenter recipes never name their executables, so the built package's own file list is read. xmake declares that a package is a binary but never what the binary is called, so its records are marked inferred and no xmake record should be read as a declaration. None of the three is exhaustive: a vcpkg port can install a command without declaring it, a ConanCenter recipe nobody has built states nothing about installed files, and an xmake package can install a command under another name.

The project records how each executable was discovered rather than treating all observations as equally authoritative.

---

Confidence

Records may carry a confidence level describing how an executable name was established.

For example:

direct
filesystem
inferred

direct means the executable is explicitly declared by package metadata.

filesystem means it was observed in package contents as an installed executable.

inferred means it was derived indirectly and should be treated with lower confidence.

Consumers can use this information when deciding whether a potential naming collision is significant.

---

MCP

Global Executables is intended to be directly usable by AI agents.

The MCP interface provides structured access to the public dataset.

The current read-only tools are:

check_executable

Check one proposed executable name.

{
  "name": "envc"
}

check_executables

Check multiple candidates in one request.

{
  "names": [
    "envc",
    "evcr",
    "evpk",
    "envcp"
  ]
}

get_executable

Return providers and provenance for a known executable.

search_executables

Search by prefix, length, ecosystem, or other indexed attributes.

search_similar_executables

Find potentially confusing existing names using lexical similarity.

get_coverage

Return dataset sources, freshness, and current coverage.

assess_executable / assess_executables

Return optional freshness, activity, popularity, and collision-risk assessments while preserving the factual existence result and provider evidence. All lookup, search, and assessment tools accept an optional multi-axis scope filter such as distribution, language, or registry.

---

Agent Workflow

A naming agent should use Global Executables before presenting CLI name recommendations.

Recommended workflow:

Generate candidate names internally
            │
            ▼
     check_executables
            │
            ▼
 Separate `found:true` collisions from `found:false` observations
            │
            ▼
 search_similar_executables for not-found candidates
            │
            ▼
 Remove confusing candidates
            │
            ▼
 Present surviving names

Rejected candidates do not need to be surfaced to the user.

The purpose of the service is to make collision checking part of the agent's normal reasoning workflow rather than a manual follow-up task.

---

Result Semantics

Absence from the dataset does not prove that an executable name has never been used.

Results therefore distinguish the factual observation from confidence in absence:

collision
clear_in_index
unknown

For example:

{
  "name": "evpk",
  "found": false,
  "status": "unknown",
  "snapshot": "2026-10-19",
  "coverage_scope": "unknown",
  "checked_sources": [
    "arch",
    "crates",
    "debian",
    "go",
    "homebrew",
    "npm",
    "pypi",
    "ubuntu"
  ],
  "searched_sources": [
    "arch",
    "crates",
    "debian",
    "go",
    "homebrew",
    "npm",
    "pypi",
    "ubuntu"
  ],
  "coverage": {
    "arch": {
      "status": "success",
      "coverage_kind": "exhaustive",
      "records": 1647,
      "source": "data/production/intermediate/arch.jsonl"
    },
    "npm": {
      "status": "success",
      "coverage_kind": "partial",
      "records": 127,
      "source": "data/production/intermediate/npm.jsonl",
      "scope": "ecosyste.ms critical npm population covering 80% of downloads or dependent repositories",
      "catalog_complete": true,
      "catalog_packages": 2295,
      "catalog_snapshot": "2026-10-18",
      "catalog_source": "https://packages.ecosyste.ms/critical?registry=npmjs.org",
      "catalog_digest": "sha256:4b610ce561d63b72b7a4137ed75ba5ecbec5fbafda236218fc4264c92db605b3"
    }
  },
  "warnings": [
    {
      "code": "npm_coverage_incomplete",
      "ecosystem": "npm",
      "message": "npm coverage is incomplete or limited to a declared population. A missing result is not proof that no npm package uses this executable and is not permission to adopt the name.",
      "coverage": {
        "status": "success",
        "coverage_kind": "partial",
        "source": "data/production/intermediate/npm.jsonl",
        "scope": "ecosyste.ms critical npm population covering 80% of downloads or dependent repositories",
        "catalog_complete": true,
        "catalog_packages": 2295,
        "catalog_snapshot": "2026-10-18",
        "catalog_source": "https://packages.ecosyste.ms/critical?registry=npmjs.org",
        "catalog_digest": "sha256:4b610ce561d63b72b7a4137ed75ba5ecbec5fbafda236218fc4264c92db605b3"
      },
      "reference": "https://github.com/asopitech-labs/global-executables/issues/54"
    }
  ],
  "absence": {
    "status": "not_found_in_current_index",
    "confidence": "insufficient_coverage",
    "searched_sources": [
      "arch",
      "crates",
      "debian",
      "go",
      "homebrew",
      "npm",
      "pypi",
      "ubuntu"
    ]
  }
}

found:false means that the name was not found in the current index. unknown means the available coverage is insufficient to make an exhaustive absence claim; it does not mean that the query was unavailable. clear_in_index is returned only when every source in the queried snapshot has coverage_kind: exhaustive, a successful run, and no finite population limit (scope or catalog_* fields). A completed npm critical catalog sets catalog_complete: true and keeps coverage_kind: partial; it never makes the snapshot exhaustive. Incomplete npm coverage also adds a npm_coverage_incomplete warning. None of these statuses is permission to adopt a name.

The coverage object reports the per-source collection status, coverage kind, and record count. The example shows two representative sources; the live response includes all sources in the snapshot (and may also include each source's input path).

It does not mean that the name is legally or globally guaranteed to be available.

---

Coverage and Freshness

Dataset metadata records:

• generation timestamp;
• snapshot identifier;
• number of indexed executables;
• enabled collectors;
• freshness of each upstream source;
• collector status.

This information is available both as structured data and through MCP.

Agents can therefore evaluate the strength of a lookup result instead of treating the index as complete by assumption.

---

GitHub as the Source of Truth

Global Executables deliberately keeps its canonical data in the repository's orphan dictionary branch.

This provides:

• transparent provenance;
• reviewable changes;
• reproducible generation;
• historical tracking;
• forks and mirrors;
• direct raw-file access;
• independence from the availability of the MCP service.

If the hosted MCP endpoint disappears, the dataset remains usable.

A third party can build another MCP server, search engine, CLI, or analysis tool directly from the repository.

---

Automation

GitHub Actions maintains the dataset.

The general pipeline is:

scheduled / manual trigger
          │
          ▼
     run collectors
          │
          ▼
       normalize
          │
          ▼
        merge
          │
          ▼
 generate executable files
          │
          ▼
    generate indexes
          │
          ▼
       validate
          │
          ▼
        publish

Collectors should contain the actual collection logic independently of GitHub Actions so they can also be executed and tested locally.

act may be used during development to run compatible GitHub Actions workflows locally.

---

What Global Executables Is Not

Global Executables is not:

• a trademark search service;
• a brand-name availability service;
• a package registry;
• a package manager;
• a vulnerability database;
• a software catalog;
• proof that an unused name is legally available.

It answers a narrower question:

What executable names are known to be used across the software ecosystems covered by the dataset?

Trademark, company-name, domain, repository-name, and broader web searches remain separate checks.

---

Potential Uses

Beyond CLI naming, the dataset can support:

• automated CLI naming assistants;
• repository CI policies;
• package publishing checks;
• ecosystem collision analysis;
• executable discovery;
• historical studies of CLI ecosystems;
• IDE and developer-tool integrations;
• AI-agent preflight checks.

---

Project Principle

Public data first. MCP second.

The value of Global Executables is not tied to a particular server implementation.

The durable asset is the openly available, reproducible, cross-ecosystem executable-name dataset.

MCP makes that dataset immediately useful to agents.

Current implementation

The schemas, deterministic builder, production OS index collector, derived prefix/length/ecosystem/trigram and logical-scope indexes, collector parsers, read-only local/HTTP MCP server, assessment API, bounded fixture freshness scenarios, and CI checks are implemented in this repository. Coverage is measured against each source. npm stays coverage_kind: partial even when its finite ecosyste.ms critical catalog finishes (catalog_complete: true); the all-registry npm long tail is not in the index. See docs/DATA_MODEL.md for exact naming, sharding, alias, and history rules and docs/OPERATIONS.md for reproducible commands, freshness-state scenarios, and honest measured coverage limitations.

For zero-setup use, see Quick start. To query a pinned snapshot without network access, install the program, materialize the published branch in a separate worktree, and point the server at it:

python -m pip install -e .
git fetch origin dictionary
git worktree add .dictionary origin/dictionary
global-executables-mcp --root . --dataset-root .dictionary

Use --transport streamable-http for remote access. Both modes expose check_executable, check_executables, get_executable, search_executables, search_similar_executables, get_coverage, assess_executable, and assess_executables; neither mode exposes writes. Data is reusable under the repository license by reading the canonical JSON directly from the dictionary branch, without running MCP. See docs/MCP.md for local client configuration, the remote endpoint, resources, health visibility, and the survivor-only agent workflow.

The manual fixture workflow exercises a bounded incremental freshness scan. It rotates through immutable test partitions, persists a cursor and last successful observations on the freshness-data branch, and publishes a machine-readable test report. It is not production freshness or a full dataset refresh. Coverage is snapshot-specific and reported by get_coverage. The published snapshot contains production OS/Homebrew coverage, a completed but partial npm critical catalog (catalog_complete, not registry-wide exhaustiveness), and partial coverage for other registries such as PyPI and Go; it is not full global ecosystem coverage, so consumers must preserve clear_in_index/unknown semantics and the npm_coverage_incomplete warning.

Registry artifact inspection is separately resumable. CI refreshes the finite npm critical catalog and crawls it to 100% daily, while dedicated local containers advance PyPI and Go module cursors and publish checkpoints to artifact-data; these local containers are temporary completion boosters and stop at 100%. After a source reaches 100%, a six-hour GitHub Actions matrix cycles through every indexed package with a persisted refresh cursor. Successful results replace stale package observations, including commands removed by a newer release. CI also performs one daily crates.io dump change check and downloads the dump only when it changed. The CI refresher dispatches a dictionary rebuild only when normalized observations changed and redeploys Pages whenever it publishes crawl progress. Go modules, npm, PyPI, RubyGems, and Packagist use the transactional Go runtime; their bbolt state commits cursor, retry verdicts, and observations together. CI regenerates npm's bounded population; PyPI, RubyGems, and Packagist reuse sampled catalogs, while Go extends its index. Finishing a declared catalog may set catalog_complete; npm is never promoted to coverage_kind: exhaustive from that catalog alone. Other sources become exhaustive only after their declared catalog and required artifact inspections complete successfully without a finite population limit.

Successful collection does not by itself permit a negative collision claim. Every valid query returns a factual found observation. Fixture, smoke, and partial snapshots return insufficient absence confidence for absent names; clear_in_index requires metadata explicitly marking the complete queried snapshot exhaustive. Derived search indexes are integrity-pinned in metadata and are used directly by prefix, length, ecosystem, and similarity queries.

For a clean-checkout setup, client configuration, expected responses, and verification steps, see docs/SETUP.md.

Issue completion and release evidence follow docs/RELEASE.md; implementation claims alone do not close work.

Data sources, their licenses and terms, and required attribution are listed in docs/DATA_SOURCES.md.