From 66e12787a0e274453d1e9cd915576d4f87b6f712 Mon Sep 17 00:00:00 2001 From: Siddharth Date: Mon, 20 Apr 2026 11:26:26 +0530 Subject: [PATCH 1/2] docs: rewrite README with accurate CLI commands and remove nonexistent skill references Removed references to /plug Claude skill and install.sh curl script that don't exist yet. Added accurate CLI command table, correct TUI hotkeys from source, global flags, vaults section, and npm badge. --- README.md | 116 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 79 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 10a2c90..7d5a92a 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,127 @@ # Plug [![CI](https://github.com/dsiddharth2/plug/actions/workflows/ci.yml/badge.svg)](https://github.com/dsiddharth2/plug/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/plugvault)](https://www.npmjs.com/package/plugvault) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Node.js](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org) -**Plug** is a package manager for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It allows you to share, discover, and install reusable skills, commands, and agents across your projects via a rich, interactive Terminal User Interface (TUI). +**Plug** is a package manager for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Discover, install, and manage reusable Skills, Commands, and Agents across your projects through an interactive Terminal UI or the CLI. ## Why Plug? -Managing Claude Code extensions (Skills, Commands, and Agents) manually can quickly become unmanageable. Plug solves several key problems: +Managing Claude Code extensions manually gets messy fast. Plug solves this: -* **Corporate & Private Ecosystems**: Easily set up internal "Vaults" (GitHub repositories) to share proprietary coding standards, security guardrails, and specialized agents within your organization. -* **Consolidated Management**: Instead of maintaining multiple harnesses or manually copying Markdown files across different projects, Plug provides a single tool to discover, install, and update everything. -* **PlugVault Ecosystem**: Access a centralized, growing registry of community-contributed extensions through the official `plugvault`, or add your own custom vaults. -* **Zero-Bloat Workflow**: Keep your projects clean by installing only what you need, either locally to a project (`.claude/`) or globally (`~/.claude/`). +- **Corporate & Private Ecosystems** — Set up internal "Vaults" (GitHub repos) to share proprietary coding standards, security guardrails, and specialized agents within your organization. +- **Consolidated Management** — One tool to discover, install, update, and remove extensions instead of manually copying Markdown files across projects. +- **PlugVault Ecosystem** — Access a growing registry of community-contributed extensions through the official [PlugVault](https://github.com/dsiddharth2/plugvault), or add your own custom vaults. +- **Zero-Bloat Workflow** — Install only what you need, either locally to a project (`.claude/`) or globally (`~/.claude/`). --- -## 🚀 Quick Start: The Plug TUI +## Quick Start -The recommended way to use Plug is through its interactive TUI. It allows you to browse, search, and batch-install extensions without remembering complex commands. +### 1. Install -![Plug TUI Screenshot](docs/images/tui-screenshot.png) -*(A rich, interactive interface for managing your Claude extensions)* - -### 1. Install Plug -Install as a Claude Code skill (recommended, no Node.js required): ```bash -bash <(curl -sf https://raw.githubusercontent.com/dsiddharth2/plug/main/plug/skill/install.sh) +npm install -g plugvault ``` -*Or via npm for the CLI:* `npm install -g plugvault` ### 2. Launch the TUI -Simply run the command to enter the interactive browser: + +Run `plug` with no arguments to open the interactive browser: + ```bash -/plug # If installed as a skill -plug # If installed via npm +plug ``` ### 3. Browse & Install -* **Navigate**: Use `Arrows` to move through the package list. -* **Search**: Press `/` to search by name or tags. -* **Select**: Press `Space` to select multiple packages. -* **Install**: Press `Enter` to install everything in your queue. + +Use the TUI to explore packages across all your configured vaults: + +| Key | Action | +|-----|--------| +| `Arrow Up/Down` | Navigate the package list | +| `Arrow Left/Right` | Switch tabs (Discover / Installed / Vaults) | +| `/` | Search by name or tags | +| `t` | Filter by type (skill, command, agent) | +| `Space` | Toggle selection | +| `Enter` | View package details | +| `i` | Install selected packages | +| `Esc` | Exit | --- ## What is Plug? -Claude Code extensions (Skills, Commands, and Agents) are Markdown files. Plug simplifies managing these files, making it as easy as using `npm` for Node.js. +Claude Code extensions are Markdown files that live in `.claude/` directories. Plug manages these files like `npm` manages Node.js packages. + +- **Skills** — Background context that shapes Claude's behavior (coding standards, architecture rules). +- **Commands** — Custom actions invoked with `/command-name` (code review, test generation). +- **Agents** — Specialized sub-agents for delegation (research, analysis). + +--- -* **Skills** — Background context that shapes Claude's behavior (coding standards, architecture rules). -* **Commands** — Custom actions invoked with `/command-name` (code review, test generation). -* **Agents** — Specialized sub-agents for delegation (research, long-running analysis). +## CLI Commands + +| Command | Description | +|---------|-------------| +| `plug` | Launch the interactive TUI | +| `plug tui` | Explicitly launch the TUI | +| `plug install ` | Install a package (with dependency resolution) | +| `plug remove ` | Remove a package (with dependent checking) | +| `plug update ` | Update a package to the latest version | +| `plug update --all` | Update all installed packages | +| `plug search ` | Search across all vaults | +| `plug list` | List installed packages | +| `plug list --remote` | List all available packages across vaults | +| `plug vault add` | Add a new vault (GitHub repo) | +| `plug vault remove` | Remove a configured vault | +| `plug init` | Initialize `.claude/` directory structure | + +### Global flags + +- `--global, -g` — Target the global `~/.claude/` scope instead of local `.claude/` +- `--verbose` — Show debug output (fetch URLs, auth method, cache hits) +- `--json` — Machine-readable JSON output +- `--yes` — Skip interactive prompts --- -## 🔮 Vision & Roadmap: The Road to v1.0 +## Vaults + +Vaults are GitHub repositories that contain a `registry.json` index of packages. Plug ships with the official [PlugVault](https://github.com/dsiddharth2/plugvault) pre-configured, but you can add your own: -We are moving towards a decentralized, dependency-aware ecosystem. Our roadmap is divided into three key phases: +```bash +plug vault add https://github.com/your-org/your-vault +``` + +Private vaults are supported — Plug will prompt for a GitHub Personal Access Token when needed. + +--- -* **Phase A: Dependency Resolution**: Moving from single-package installs to full closure resolution using a DFS resolver. -* **Phase B: Community Marketplace**: Enabling any developer to publish from their own repo via automated frontmatter indexing. -* **Phase C: Claude Native Integration**: A zero-latency installer that works directly within Claude conversations. +## Features -View the detailed [Ecosystem Vision & Roadmap](docs/project/ecosystem-vision.md). +- **Interactive TUI** — Full-screen terminal UI with tabs for Discover, Installed, and Vaults +- **Dependency Resolution** — DFS resolver automatically installs required dependencies +- **Multi-File Packages** — Packages spanning multiple files are tracked and cleaned up correctly +- **Private Vaults** — Authenticate with GitHub PATs for private repositories +- **Smart Removal** — Dependent checking, cascade removal, and orphan pruning +- **Offline Cache** — Registry data is cached locally (1 hour TTL) for fast lookups --- ## Documentation -* **[TUI Guide](docs/features/tui.md)** — Detailed breakdown of the interactive interface and hotkeys. -* **[Architecture](docs/architecture.md)** — How Plug works under the hood (including our Context-Aware Capture system). -* **[Authoring Guide](docs/authoring-guide.md)** — Learn how to create and publish your own packages. -* **[Vaults & Registries](docs/features/vaults.md)** — Managing public and private package sources. +- **[TUI Guide](docs/features/tui.md)** — Detailed breakdown of the interactive interface and hotkeys +- **[Architecture](docs/architecture.md)** — How Plug works under the hood +- **[Authoring Guide](docs/authoring-guide.md)** — Create and publish your own packages +- **[Vaults & Registries](docs/features/vaults.md)** — Managing public and private package sources --- ## Contributing -We welcome contributions! Please see our [Contributing Guidelines](plug/CONTRIBUTING.md) for details on how to get involved. +Contributions welcome! See the [Contributing Guidelines](plug/CONTRIBUTING.md) for details. --- From d1c7ded48598f204c690b614e586c2be175b4872 Mon Sep 17 00:00:00 2001 From: Siddharth Date: Mon, 20 Apr 2026 11:30:11 +0530 Subject: [PATCH 2/2] docs: add TUI screenshot back to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 7d5a92a..0e469d7 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ Managing Claude Code extensions manually gets messy fast. Plug solves this: ## Quick Start +![Plug TUI](docs/images/tui-screenshot.png) + ### 1. Install ```bash