@ghx-dev/core 0.4.1 → 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.1",
+  "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-ISLM2HRZ.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.1" : "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-ISLM2HRZ.js.map
+//# sourceMappingURL=chunk-G3JW3XZK.js.map

package/dist/cli/index.js

@@ -10,7 +10,7 @@ import {
   invalidateTokenCache,
   listCapabilities,
   resolveGithubToken
-} from "../chunk-ISLM2HRZ.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-ISLM2HRZ.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.1",
+  "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/skills/using-ghx/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: using-ghx
-description: Executes GitHub operations via ghx. Use for all GitHub interactions instead of raw gh or gh api commands.
+description: "Executes GitHub operations via ghx CLI, which batches multiple operations into single API calls and provides structured JSON output for 70+ GitHub capabilities. Use when working with PRs, issues, reviews, CI checks, releases, labels, comments, or any GitHub API operation -- even simple ones like checking PR status or listing issues. Provides richer output than raw gh, gh api, or curl commands."
 ---
 
 # ghx CLI Skill
 
-## Authentication
+ghx provides 70+ GitHub capabilities with structured JSON input/output. It batches operations into single GraphQL round-trips, making it faster than sequential `gh` or `gh api` calls.
+
+## Resolving owner and name
+
+Most capabilities require `owner` and `name`. Infer from `git remote get-url origin` once at the start and reuse. If no git remote is available, ask the user.
 
-ghx automatically resolves your GitHub token. It checks (in order):
-1. `GITHUB_TOKEN` environment variable
-2. `GH_TOKEN` environment variable
-3. Cached token (from previous resolution)
-4. `gh auth token` (requires `gh` CLI authenticated via `gh auth login`)
+## Authentication
 
-If you are authenticated via `gh auth login`, ghx works out of the box with no extra configuration.
+ghx resolves tokens automatically (env vars `GITHUB_TOKEN`/`GH_TOKEN`, or `gh auth token`). No setup needed if `gh auth login` has been run.
 
 ## Capabilities
 
@@ -92,7 +92,7 @@ release.update - Update a draft release without publishing it. [owner, name, rel
 release.publish - Publish an existing draft release. [owner, name, releaseId, title?, notes?, prerelease?]
 ```
 
-Only if the full input/output schema of a specific capability needed:
+If you need the full input/output schema for a capability:
 
 ```bash
 ghx capabilities explain <capability_id>
@@ -100,7 +100,7 @@ ghx capabilities explain <capability_id>
 
 ## Execute
 
-**Always use heredoc — never inline `--input '...'`.** Inline form breaks with nested quotes and trailing commas in model-generated JSON.
+**Always use heredoc for input** — never inline `--input '...'`. Inline form breaks with nested quotes and trailing commas in model-generated JSON.
 
 ```bash
 ghx run <capability_id> --input - <<'EOF'
@@ -108,28 +108,11 @@ ghx run <capability_id> --input - <<'EOF'
 EOF
 ```
 
-Example (submitting a review with inline comments):
+**Result:** `{ ok, data?, pagination? }` on success — `{ ok, error: { code, message } }` on failure.
 
-```bash
-ghx run pr.reviews.submit --input - <<'EOF'
-{
-  "owner": "acme",
-  "name": "my-repo",
-  "prNumber": 42,
-  "event": "REQUEST_CHANGES",
-  "body": "Please fix the issues.",
-  "comments": [
-    { "path": "src/index.ts", "line": 10, "body": "Off-by-one error here." }
-  ]
-}
-EOF
-```
-
-**Result (compact, default):** `{ ok, data?, pagination? }` on success — `{ ok, error: { code, message } }` on failure.
-
-## Chain
+## Chain (batch multiple operations)
 
-Use `ghx chain` when you have two or more operations to run. It batches steps into as few GraphQL round-trips as possible (typically one) — reducing latency and avoiding mid-sequence failures. Steps are not transactional; a `"partial"` result is possible if one step fails after another has already succeeded.
+When you have two or more **independent** operations, use `ghx chain`. It batches them into as few GraphQL round-trips as possible (typically one), which is significantly faster than running them sequentially. Steps are not transactional — a `"partial"` result is possible if one step fails after others succeed.
 
 ```bash
 ghx chain --steps - <<'EOF'
@@ -140,8 +123,54 @@ ghx chain --steps - <<'EOF'
 EOF
 ```
 
-**Result:** `{ status, results[] }`. Each result: `{ task, ok, data? }` on success — `{ task, ok, error: { code, message } }` on failure.
+**Result:** `{ status, results[] }`. Each element: `{ task, ok, data? }` or `{ task, ok, error: { code, message } }`.
+
+**When NOT to chain:** Don't chain when a later step depends on the result of an earlier one. For example, "check CI, then fetch logs only if something failed" requires two sequential calls because the second depends on the first result. Similarly, "create an issue, then label it" needs the issue number from the create step before labeling.
+
+## Error handling
+
+ghx never throws — errors are always in the response envelope. Check the `ok` field:
+- `ok: true` — success, data is in `data`
+- `ok: false` — failure, details in `error.code` and `error.message`
+
+Common error codes: `AUTH`, `NOT_FOUND`, `VALIDATION`, `RATE_LIMIT`, `NETWORK`, `SERVER`.
+
+If you get `RATE_LIMIT` or `NETWORK`, retry after a short delay. For `NOT_FOUND`, double-check owner/name/number. For `VALIDATION`, run `ghx capabilities explain <id>` to check the expected schema.
+
+## Common workflow patterns
+
+### PR merge readiness audit
+Use `ghx chain` with `pr.checks.list`, `pr.threads.list`, and `pr.merge.status` in one call to get all three signals at once.
+
+### Review a PR (read diff, check threads, submit review)
+1. `pr.diff.view` — read the full diff
+2. `pr.threads.list` — see existing unresolved review comments
+3. `pr.reviews.submit` — submit your review with inline comments
+
+### Respond to all unresolved review threads
+1. `pr.threads.list` — get all unresolved threads (returns `threadId` for each)
+2. `ghx chain` with multiple `pr.threads.reply` steps — reply to each thread in one batch
+
+### Check CI status and debug failures (sequential -- don't chain)
+1. `pr.checks.list` — see which checks passed/failed
+2. Only if something failed: `workflow.run.view` — get job details for the failed run
+3. Only if needed: `workflow.job.logs.view` — read the failure logs
+
+### Triage an issue (label, assign, comment)
+Use `ghx chain` with `issue.labels.add`, `issue.assignees.add`, and `issue.comments.create` in one call.
+
+### Create an issue then configure it (sequential then batch)
+1. `issue.create` — get the new issue number
+2. `ghx chain` with `issue.labels.add`, `issue.assignees.add`, `issue.comments.create` — batch all mutations using the number from step 1
+
+### Create a PR from current branch
+1. Infer owner/name from git remote
+2. Get current branch: `git branch --show-current`
+3. `pr.create` with `head` = current branch, `base` = main/master
 
-**CRITICAL:** Do not use `gh api` or any other raw `gh` commands unless no matching ghx capability exists. Always try `ghx` first.
+## Important rules
 
-**IMPORTANT:** Always use `ghx chain` when you have two or more operations to execute in a single call!
+- Prefer `ghx` over `gh`, `gh api`, or `curl` for any GitHub operation that has a matching capability.
+- Use `ghx chain` when you have 2+ **independent** operations — it is faster and avoids mid-sequence failures.
+- Always use heredoc (`<<'EOF'`) for JSON input, never inline `--input '{...}'`.
+- Infer owner/name from `git remote get-url origin` when in a git repository.

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