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.

<!-- mcp-name: io.github.asopitech-labs/global-executables -->

## 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](https://docs.astral.sh/uv/) (`uvx`) or Docker.

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

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

**Claude Code**:

```sh
claude mcp add global-executables -- uvx global-executables mcp
```

**VS Code** (`.vscode/mcp.json`):

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

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

```json
{
  "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`](docs/MCP.md) for HTTP transport
and running from a source checkout.

---

## Why Global Executables?

Suppose you are designing a new CLI and considering:

```text
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:

```text
executable
    ↓
provider
    ↓
package
    ↓
ecosystem
```

rather than simply:

```text
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](https://asopitech-labs.github.io/global-executables/)
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:

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

See [the dictionary branch migration note](docs/DICTIONARY_BRANCH.md) for the
branch contract, local setup, and the `main` URL cutover.

Go development follows the
[JetBrains Modern Go Guidelines](https://github.com/JetBrains/go-modern-guidelines).
See the [Go crawler development and build contract](docs/GO_CRAWLER_DEVELOPMENT.md)
for the versioned review, build, test, security, and release workflow.

---

## Architecture

```text
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:

```json
{
  "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:

```text
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:

```text
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:

```text
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 directl