agentshq 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ulpi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+<p align="center">
+  <pre align="center">
+ █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗
+██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝
+███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗
+██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║
+██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║
+╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝</pre>
+</p>
+
+<p align="center">
+  <strong>The package manager for AI coding agents.</strong><br>
+  Discover, install, and manage agent definitions across 43+ IDEs.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/agentshq"><img alt="npm version" src="https://img.shields.io/npm/v/agentshq.svg"></a>
+  <a href="https://www.npmjs.com/package/agentshq"><img alt="npm downloads" src="https://img.shields.io/npm/dm/agentshq.svg"></a>
+  <a href="https://www.npmjs.com/package/agentshq"><img alt="license" src="https://img.shields.io/npm/l/agentshq.svg"></a>
+  <a href="https://agentshq.sh"><img alt="website" src="https://img.shields.io/badge/web-agentshq.sh-blue"></a>
+</p>
+
+---
+
+## Quick Start
+
+No install required -- run with `npx`:
+
+```bash
+npx agentshq add owner/repo
+```
+
+The CLI clones the repo, discovers every agent inside it, detects which IDEs you have installed, and writes each agent in the correct format. One command, all your IDEs.
+
+```bash
+# Install a specific agent
+npx agentshq add owner/repo@agent-name
+
+# Search the registry
+npx agentshq find react
+
+# List installed agents
+npx agentshq list
+
+# Update everything
+npx agentshq update
+```
+
+Or install globally:
+
+```bash
+npm i -g agentshq
+agentshq add owner/repo
+```
+
+## How It Works
+
+```
+Source repo                     Your machine
+───────────                     ────────────
+AGENT.md          ──clone──►    .agents/agents/<name>/AGENT.md   (canonical)
+*.agent.md                            │
+*.json                                ├──►  .claude/agents/<name>.md
+*.toml                                ├──►  .cursor/agents/AGENTS.md
+AGENTS.md sections                    ├──►  .github/agents/<name>.agent.md
+                                      ├──►  .kiro/agents/<name>.json
+                                      └──►  ... (43+ IDEs)
+```
+
+Agents are stored once in a canonical format, then **translated and copied** to each IDE's native format. No symlinks, no lock-in -- every IDE gets a file it understands natively. Updates and removal are tracked automatically via lock files.
+
+## Supported IDEs
+
+### Native agent support
+
+| IDE | Format |
+|-----|--------|
+| Claude Code | `.md` with YAML frontmatter |
+| Gemini CLI | `.md` with YAML frontmatter |
+| OpenCode | `.md` with YAML frontmatter |
+| GitHub Copilot | `.agent.md` |
+| Kiro | `.json` |
+| Mistral Vibe | `.toml` |
+| Cursor | `AGENTS.md` sections |
+| Windsurf | `AGENTS.md` sections |
+| Codex | `AGENTS.md` sections |
+| Amp | `AGENTS.md` sections |
+| Augment | `AGENTS.md` sections |
+| Roo Code | `AGENTS.md` sections |
+| Cline | `AGENTS.md` sections |
+| Goose | `AGENTS.md` sections |
+| Junie | `AGENTS.md` sections |
+| Antigravity | `AGENTS.md` sections |
+| Warp | `AGENTS.md` sections |
+
+### Forward-bet IDEs
+
+26 additional IDEs that don't yet have a native agent format. The CLI copies the canonical `AGENT.md` so agents are ready the moment support lands: Continue, Replit, Trae, Qwen Code, OpenHands, Kilo Code, Droid, Cortex Code, CodeBuddy, and more.
+
+## Commands
+
+### Install agents
+
+```bash
+# From a GitHub repo
+npx agentshq add owner/repo
+
+# A specific agent from a multi-agent repo
+npx agentshq add owner/repo@agent-name
+
+# From any git URL
+npx agentshq add https://gitlab.com/org/repo
+
+# From a local directory
+npx agentshq add ./path/to/agents
+
+# Global install (available in all projects)
+npx agentshq add owner/repo -g
+
+# Target specific IDEs only
+npx agentshq add owner/repo --ide claude-code cursor windsurf
+
+# Install everything, no prompts
+npx agentshq add owner/repo --all
+
+# Preview agents in a repo without installing
+npx agentshq add owner/repo --list
+```
+
+### Search agents
+
+```bash
+# Interactive search with fuzzy matching
+npx agentshq find
+
+# Search by keyword
+npx agentshq find typescript
+```
+
+### Manage agents
+
+```bash
+# List project agents
+npx agentshq list
+
+# List global agents
+npx agentshq list -g
+
+# JSON output
+npx agentshq list --json
+
+# Remove interactively
+npx agentshq remove
+
+# Remove by name
+npx agentshq remove agent-name
+
+# Check for updates
+npx agentshq check
+
+# Update all agents
+npx agentshq update
+```
+
+### Create agents
+
+```bash
+# Scaffold a new AGENT.md
+npx agentshq init my-agent
+```
+
+### Command reference
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `add <source>` | `a`, `install`, `i` | Install agents from GitHub, GitLab, any git URL, or a local path |
+| `remove [names]` | `rm`, `r` | Remove installed agents (interactive picker if no names given) |
+| `list` | `ls` | List installed agents |
+| `find [query]` | `search`, `f`, `s` | Search the registry |
+| `check` | | Check for available updates |
+| `update` | `upgrade` | Update all agents |
+| `init [name]` | | Create a new `AGENT.md` |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-g, --global` | User-level scope instead of project-level |
+| `--ide <ides>` | Target specific IDEs (or `*` for all) |
+| `--agent <names>` | Select specific agents (or `*` for all) |
+| `-y, --yes` | Skip confirmation prompts |
+| `--all` | All agents, all IDEs, no prompts |
+| `--list` | Preview without installing |
+| `--json` | Machine-readable output |
+
+## Publishing Your Own Agents
+
+### Repo layout
+
+**Single agent** -- put an `AGENT.md` at the root:
+
+```
+my-agent/
+  AGENT.md
+```
+
+**Multiple agents** -- one subdirectory per agent:
+
+```
+my-agents/
+  agents/
+    code-reviewer/
+      AGENT.md
+    api-designer/
+      AGENT.md
+    test-writer/
+      AGENT.md
+```
+
+Push to GitHub (or any git host) and anyone can install with `npx agentshq add owner/repo`.
+
+### AGENT.md format
+
+```markdown
+---
+name: code-reviewer
+description: Reviews pull requests for correctness, style, and security issues
+metadata:
+  tags:
+    - code-review
+    - security
+  tools:
+    - Read
+    - Grep
+    - Bash
+  model: sonnet
+---
+
+# Code Reviewer
+
+You are a senior code reviewer. When activated, review the provided
+code changes for correctness, security, and style issues.
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Agent identifier (used as directory name on install) |
+| `description` | yes | One-line summary shown in search results |
+| `metadata.tags` | no | Keywords for discovery |
+| `metadata.tools` | no | Tools the agent needs |
+| `metadata.model` | no | Preferred model hint |
+| `metadata.internal` | no | Set `true` to hide from public discovery |
+
+The markdown body is the agent's system prompt -- preserved verbatim across all format translations.
+
+### Supported input formats
+
+The CLI auto-detects all of these:
+
+| Format | Example | Used by |
+|--------|---------|---------|
+| `AGENT.md` | `agents/reviewer/AGENT.md` | Canonical (recommended) |
+| `<name>.md` | `reviewer.md` with YAML frontmatter | Claude Code, Gemini CLI, OpenCode |
+| `<name>.agent.md` | `reviewer.agent.md` | GitHub Copilot |
+| `<name>.json` | `reviewer.json` | Kiro |
+| `<name>.toml` | `reviewer.toml` | Mistral Vibe |
+| `AGENTS.md` | `<!-- agent:reviewer -->` sections | Cursor, Windsurf, Augment + 8 more |
+
+## Private Repos
+
+Same syntax as public repos:
+
+```bash
+npx agentshq add your-org/private-agents
+```
+
+When the source is private, the CLI automatically:
+
+- **Skips all telemetry** -- no repo names or agent names leave your machine
+- **Skips the security audit API** -- zero external requests
+- **Tracks only locally** -- lock file entries for updates, nothing more
+
+Set `GITHUB_TOKEN` or `GH_TOKEN` if you need token-based access:
+
+```bash
+GITHUB_TOKEN=ghp_xxx npx agentshq add your-org/private-agents
+```
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT -- see [LICENSE](https://github.com/ulpi-io/agentshq-cli/blob/main/LICENSE) for details.
+
+---
+
+<p align="center">
+  <a href="https://agentshq.sh">agentshq.sh</a>
+</p>

package/bin/cli.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import module from 'node:module';
+
+// https://nodejs.org/api/module.html#module-compile-cache
+if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
+  try {
+    module.enableCompileCache();
+  } catch {
+    // Ignore errors
+  }
+}
+
+await import('../dist/cli.mjs');