@ghx-dev/core 0.4.2 → 0.4.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ghx",
   "description": "Route GitHub operations through deterministic adapters instead of fragile shell scraping. 70+ capabilities covering issues, PRs, repos, releases, and projects — each with validated input, normalized output, and automatic fallback routing.",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "author": {
     "name": "Arye Kogan"
   },

package/.cursor-plugin/hooks/hooks.json

@@ -0,0 +1,9 @@
+{
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "../scripts/plugin/ensure-ghx.sh"
+      }
+    ]
+  }
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "ghx",
+  "description": "Route GitHub operations through deterministic adapters instead of fragile shell scraping. 70+ capabilities covering issues, PRs, repos, releases, and projects — each with validated input, normalized output, and automatic fallback routing.",
+  "version": "0.4.3",
+  "author": {
+    "name": "Arye Kogan"
+  },
+  "category": "development",
+  "repository": "https://github.com/aryeko/ghx",
+  "homepage": "https://github.com/aryeko/ghx",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "github-api",
+    "ai-agents",
+    "agentic",
+    "cli",
+    "graphql",
+    "automation",
+    "typescript"
+  ],
+  "logo": "https://raw.githubusercontent.com/aryeko/ghx/main/assets/branding/logos/ghx-logo-icon.svg",
+  "skills": "../skills/",
+  "rules": "rules/"
+}

package/.cursor-plugin/rules/ghx-batching.mdc

@@ -0,0 +1,16 @@
+---
+description: Use ghx chain to batch multiple GitHub operations into a single API call
+alwaysApply: true
+---
+
+When performing 2+ GitHub operations, use `ghx chain` with a JSON array of steps instead of sequential `ghx run` calls. This batches operations into fewer API round-trips.
+
+Example:
+```bash
+ghx chain --steps - <<'EOF'
+[
+  {"task":"pr.view","input":{"owner":"org","name":"repo","number":123}},
+  {"task":"pr.reviews.list","input":{"owner":"org","name":"repo","number":123}}
+]
+EOF
+```

package/.cursor-plugin/rules/ghx-capabilities.mdc

@@ -0,0 +1,12 @@
+---
+description: Check ghx capabilities before attempting raw GitHub API calls
+alwaysApply: true
+---
+
+Before writing custom `gh api` or curl commands, run `ghx capabilities list` or `ghx capabilities explain <id>` to check if ghx already supports the operation. ghx covers 70+ capabilities across issues, PRs, repos, releases, workflows, and projects.
+
+Example:
+```bash
+ghx capabilities list --domain pr
+ghx capabilities explain pr.merge
+```

package/.cursor-plugin/rules/prefer-ghx.mdc

@@ -0,0 +1,14 @@
+---
+description: Prefer ghx CLI over raw gh, gh api, or curl for GitHub operations
+alwaysApply: true
+---
+
+When performing any GitHub operation (PRs, issues, reviews, CI checks, releases, labels, comments), use `ghx run` instead of `gh`, `gh api`, or `curl`. ghx provides validated input, structured JSON output, and automatic fallback routing. Always pass `--input` via stdin heredoc to avoid shell quoting issues.
+
+Example:
+```bash
+# Instead of: gh pr view 123 --json title,state
+ghx run pr.view --input - <<'EOF'
+{"owner":"org","name":"repo","number":123}
+EOF
+```

package/README.md

@@ -19,6 +19,8 @@
 When AI agents use the `gh` CLI directly, they waste thousands of tokens on research, trial-and-error formatting, and guessing JSON parsing paths. **ghx eliminates this waste** by providing a stable, structured execution layer.
 
 > **100% success rate, 73% fewer tool calls, 18% fewer active tokens, 54% lower latency** compared to raw CLI usage ([measured across 30 runs](https://github.com/aryeko/ghx/blob/main/docs/eval-report.md) on standard PR workflows with Codex 5.3).
+>
+> Read the full motivation: [AI Agents Shouldn't Relearn GitHub on Every Run](https://plainenglish.io/artificial-intelligence/ai-agents-shouldn-t-relearn-github-on-every-run)
 
 ```mermaid
 sequenceDiagram
@@ -59,12 +61,22 @@ Comprehensive documentation is available in the [`docs/`](./docs/) directory:
 - **[Architecture](./docs/architecture/README.md)** — System design, execution pipeline, formatters, and GraphQL layer.
 - **[Reference](./docs/reference/README.md)** — API exports, error codes, and a complete table of all 70+ capabilities.
 
-## Quick Start (Library)
+## Install
+
+```bash
+npm i -g @ghx-dev/core
+```
+
+This makes the `ghx` CLI available in your PATH. Then wire it into your agent (see [Agent Integration](#agent-integration) below).
+
+For library usage (TypeScript imports), install as a project dependency instead:
 
 ```bash
 npm install @ghx-dev/core
 ```
 
+## Quick Start (Library)
+
 ```ts
 import { createGithubClientFromToken, executeTask } from "@ghx-dev/core"
 
@@ -92,10 +104,10 @@ Use ghx directly from your terminal or add it as an agent skill.
 
 ```bash
 # List all 70+ capabilities
-npx @ghx-dev/core capabilities list
+ghx capabilities list
 
 # Run a capability
-npx @ghx-dev/core run pr.view --input '{"owner":"aryeko","name":"ghx","number":42}'
+ghx run pr.view --input '{"owner":"aryeko","name":"ghx","prNumber":42}'
 
 # Output is a standard ResultEnvelope:
 # {
@@ -107,13 +119,20 @@ npx @ghx-dev/core run pr.view --input '{"owner":"aryeko","name":"ghx","number":4
 
 ## Agent Integration
 
-To install the `ghx` skill for Claude Code:
+**Claude Code** -- install from the plugin marketplace:
+
+```bash
+/plugin marketplace add aryeko/ghx
+/plugin install ghx@ghx-dev
+```
+
+**Cursor, Windsurf, Codex, other agents** -- install the skill:
 
 ```bash
-npx @ghx-dev/core setup --scope project --yes
+ghx setup --scope user --yes
 ```
 
-This installs `.agents/skills/ghx/SKILL.md` which teaches Claude how to use `npx @ghx-dev/core` for reliable GitHub interactions.
+This writes `SKILL.md` to `~/.agents/skills/using-ghx/` which teaches your agent how to use `ghx` for reliable GitHub interactions. See [Agent Setup](./docs/getting-started/agent-setup.md) for platform-specific wiring.
 
 ## License
 

package/dist/{chunk-EJZDHUZK.js → chunk-G3JW3XZK.js}

@@ -833,7 +833,7 @@ function createLogger(config) {
   }
   function write(level, msg, ctx) {
     if (levelIndex(level) < minIndex) return;
-    const version = true ? "0.4.2" : "unknown";
+    const version = true ? "0.4.3" : "unknown";
     const entry = {
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       pid: config.pid,
@@ -6219,4 +6219,4 @@ export {
   createGithubClientFromToken,
   createGithubClient
 };
-//# sourceMappingURL=chunk-EJZDHUZK.js.map
+//# sourceMappingURL=chunk-G3JW3XZK.js.map

package/dist/cli/index.js

@@ -10,7 +10,7 @@ import {
   invalidateTokenCache,
   listCapabilities,
   resolveGithubToken
-} from "../chunk-EJZDHUZK.js";
+} from "../chunk-G3JW3XZK.js";
 import "../chunk-H7CLZHRO.js";
 import "../chunk-NQ53ETYV.js";
 import "../chunk-TGL33GEA.js";

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   listCapabilities,
   listOperationCards,
   resolveGithubToken
-} from "./chunk-EJZDHUZK.js";
+} from "./chunk-G3JW3XZK.js";
 import "./chunk-H7CLZHRO.js";
 import "./chunk-NQ53ETYV.js";
 import "./chunk-TGL33GEA.js";

package/hooks/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/scripts/plugin/setup-env.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/plugin/ensure-ghx.sh"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghx-dev/core",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Route GitHub operations through deterministic adapters instead of fragile shell scraping. 70+ capabilities covering issues, PRs, repos, releases, and projects — each with validated input, normalized output, and automatic fallback routing.",
   "author": "Arye Kogan",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "hooks",
     "scripts/plugin",
     ".claude-plugin",
+    ".cursor-plugin",
     "skills",
     "LICENSE",
     "README.md"

package/scripts/plugin/ensure-ghx.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Shared sessionStart hook for Claude Code and Cursor plugins.
+# Warns if ghx is not available on PATH.
+
+if ! command -v ghx &>/dev/null; then
+  echo "Warning: ghx CLI not found. Install with: npm install -g @ghx-dev/core"
+fi
+
+exit 0

package/scripts/plugin/setup-env.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-# Add the plugin's CLI binary to PATH for the Claude Code session.
-if [ -n "$CLAUDE_ENV_FILE" ]; then
-  echo "export PATH=\"${CLAUDE_PLUGIN_ROOT}/bin:\$PATH\"" >> "$CLAUDE_ENV_FILE"
-fi
-exit 0