opkg 0.6.1 → 0.7.0

package/specs/claude-plugins.md

@@ -0,0 +1,413 @@
+# Create plugins
+
+> Create custom plugins to extend Claude Code with slash commands, agents, hooks, Skills, and MCP servers.
+
+Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. This guide covers creating your own plugins with slash commands, agents, Skills, hooks, and MCP servers.
+
+Looking to install existing plugins? See [Discover and install plugins](/en/discover-plugins). For complete technical specifications, see [Plugins reference](/en/plugins-reference).
+
+## When to use plugins vs standalone configuration
+
+Claude Code supports two ways to add custom slash commands, agents, and hooks:
+
+| Approach                                                    | Slash command names  | Best for                                                                                        |
+| :---------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- |
+| **Standalone** (`.claude/` directory)                       | `/hello`             | Personal workflows, project-specific customizations, quick experiments                          |
+| **Plugins** (directories with `.claude-plugin/plugin.json`) | `/plugin-name:hello` | Sharing with teammates, distributing to community, versioned releases, reusable across projects |
+
+**Use standalone configuration when**:
+
+* You're customizing Claude Code for a single project
+* The configuration is personal and doesn't need to be shared
+* You're experimenting with slash commands or hooks before packaging them
+* You want short slash command names like `/hello` or `/review`
+
+**Use plugins when**:
+
+* You want to share functionality with your team or community
+* You need the same slash commands/agents across multiple projects
+* You want version control and easy updates for your extensions
+* You're distributing through a marketplace
+* You're okay with namespaced slash commands like `/my-plugin:hello` (namespacing prevents conflicts between plugins)
+
+<Tip>
+  Start with standalone configuration in `.claude/` for quick iteration, then [convert to a plugin](#convert-existing-configurations-to-plugins) when you're ready to share.
+</Tip>
+
+## Quickstart
+
+This quickstart walks you through creating a plugin with a custom slash command. You'll create a manifest (the configuration file that defines your plugin), add a slash command, and test it locally using the `--plugin-dir` flag.
+
+### Prerequisites
+
+* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code)
+* Claude Code version 1.0.33 or later (run `claude --version` to check)
+
+<Note>
+  If you don't see the `/plugin` command, update Claude Code to the latest version. See [Troubleshooting](/en/troubleshooting) for upgrade instructions.
+</Note>
+
+### Create your first plugin
+
+<Steps>
+  <Step title="Create the plugin directory">
+    Every plugin lives in its own directory containing a manifest and your custom commands, agents, or hooks. Create one now:
+
+    ```bash  theme={null}
+    mkdir my-first-plugin
+    ```
+  </Step>
+
+  <Step title="Create the plugin manifest">
+    The manifest file at `.claude-plugin/plugin.json` defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.
+
+    Create the `.claude-plugin` directory inside your plugin folder:
+
+    ```bash  theme={null}
+    mkdir my-first-plugin/.claude-plugin
+    ```
+
+    Then create `my-first-plugin/.claude-plugin/plugin.json` with this content:
+
+    ```json my-first-plugin/.claude-plugin/plugin.json theme={null}
+    {
+    "name": "my-first-plugin",
+    "description": "A greeting plugin to learn the basics",
+    "version": "1.0.0",
+    "author": {
+    "name": "Your Name"
+    }
+    }
+    ```
+
+    | Field         | Purpose                                                                                                                |
+    | :------------ | :--------------------------------------------------------------------------------------------------------------------- |
+    | `name`        | Unique identifier and slash command namespace. Slash commands are prefixed with this (e.g., `/my-first-plugin:hello`). |
+    | `description` | Shown in the plugin manager when browsing or installing plugins.                                                       |
+    | `version`     | Track releases using [semantic versioning](/en/plugins-reference#version-management).                                  |
+    | `author`      | Optional. Helpful for attribution.                                                                                     |
+
+    For additional fields like `homepage`, `repository`, and `license`, see the [full manifest schema](/en/plugins-reference#plugin-manifest-schema).
+  </Step>
+
+  <Step title="Add a slash command">
+    Slash commands are Markdown files in the `commands/` directory. The filename becomes the slash command name, prefixed with the plugin's namespace (`hello.md` in a plugin named `my-first-plugin` creates `/my-first-plugin:hello`). The Markdown content tells Claude how to respond when someone runs the slash command.
+
+    Create a `commands` directory in your plugin folder:
+
+    ```bash  theme={null}
+    mkdir my-first-plugin/commands
+    ```
+
+    Then create `my-first-plugin/commands/hello.md` with this content:
+
+    ```markdown my-first-plugin/commands/hello.md theme={null}
+    ---
+    description: Greet the user with a friendly message
+    ---
+
+    # Hello Command
+
+    Greet the user warmly and ask how you can help them today.
+    ```
+  </Step>
+
+  <Step title="Test your plugin">
+    Run Claude Code with the `--plugin-dir` flag to load your plugin:
+
+    ```bash  theme={null}
+    claude --plugin-dir ./my-first-plugin
+    ```
+
+    Once Claude Code starts, try your new command:
+
+    ```shell  theme={null}
+    /my-first-plugin:hello
+    ```
+
+    You'll see Claude respond with a greeting. Run `/help` to see your command listed under the plugin namespace.
+
+    <Note>
+      **Why namespacing?** Plugin slash commands are always namespaced (like `/greet:hello`) to prevent conflicts when multiple plugins have commands with the same name.
+
+      To change the namespace prefix, update the `name` field in `plugin.json`.
+    </Note>
+  </Step>
+
+  <Step title="Add slash command arguments">
+    Make your slash command dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the slash command.
+
+    Update your `hello.md` file:
+
+    ```markdown my-first-plugin/commands/hello.md theme={null}
+    ---
+    description: Greet the user with a personalized message
+    ---
+
+    # Hello Command
+
+    Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
+    ```
+
+    Restart Claude Code to pick up the changes, then try the command with your name:
+
+    ```shell  theme={null}
+    /my-first-plugin:hello Alex
+    ```
+
+    Claude will greet you by name. For more argument options like `$1`, `$2` for individual parameters, see [Slash commands](/en/slash-commands).
+  </Step>
+</Steps>
+
+You've successfully created and tested a plugin with these key components:
+
+* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata
+* **Commands directory** (`commands/`): contains your custom slash commands
+* **Command arguments** (`$ARGUMENTS`): captures user input for dynamic behavior
+
+<Tip>
+  The `--plugin-dir` flag is useful for development and testing. When you're ready to share your plugin with others, see [Create and distribute a plugin marketplace](/en/plugin-marketplaces).
+</Tip>
+
+## Plugin structure overview
+
+You've created a plugin with a slash command, but plugins can include much more: custom agents, Skills, hooks, MCP servers, and LSP servers.
+
+<Warning>
+  **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.
+</Warning>
+
+| Directory         | Location    | Purpose                                         |
+| :---------------- | :---------- | :---------------------------------------------- |
+| `.claude-plugin/` | Plugin root | Contains only `plugin.json` manifest (required) |
+| `commands/`       | Plugin root | Slash commands as Markdown files                |
+| `agents/`         | Plugin root | Custom agent definitions                        |
+| `skills/`         | Plugin root | Agent Skills with `SKILL.md` files              |
+| `hooks/`          | Plugin root | Event handlers in `hooks.json`                  |
+| `.mcp.json`       | Plugin root | MCP server configurations                       |
+| `.lsp.json`       | Plugin root | LSP server configurations for code intelligence |
+
+<Note>
+  **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).
+</Note>
+
+## Develop more complex plugins
+
+Once you're comfortable with basic plugins, you can create more sophisticated extensions.
+
+### Add Skills to your plugin
+
+Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked: Claude automatically uses them based on the task context.
+
+Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── skills/
+    └── code-review/
+        └── SKILL.md
+```
+
+Each `SKILL.md` needs frontmatter with `name` and `description` fields, followed by instructions:
+
+```yaml  theme={null}
+---
+name: code-review
+description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
+---
+
+When reviewing code, check for:
+1. Code organization and structure
+2. Error handling
+3. Security concerns
+4. Test coverage
+```
+
+After installing the plugin, restart Claude Code to load the Skills. For complete Skill authoring guidance including progressive disclosure and tool restrictions, see [Agent Skills](/en/skills).
+
+### Add LSP servers to your plugin
+
+<Tip>
+  For common languages like TypeScript, Python, and Rust, install the pre-built LSP plugins from the official marketplace. Create custom LSP plugins only when you need support for languages not already covered.
+</Tip>
+
+LSP (Language Server Protocol) plugins give Claude real-time code intelligence. If you need to support a language that doesn't have an official LSP plugin, you can create your own by adding an `.lsp.json` file to your plugin:
+
+```json .lsp.json theme={null}
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+Users installing your plugin must have the language server binary installed on their machine.
+
+For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).
+
+### Organize complex plugins
+
+For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).
+
+### Test your plugins locally
+
+Use the `--plugin-dir` flag to test plugins during development. This loads your plugin directly without requiring installation.
+
+```bash  theme={null}
+claude --plugin-dir ./my-plugin
+```
+
+As you make changes to your plugin, restart Claude Code to pick up the updates. Test your plugin components:
+
+* Try your commands with `/command-name`
+* Check that agents appear in `/agents`
+* Verify hooks work as expected
+
+<Tip>
+  You can load multiple plugins at once by specifying the flag multiple times:
+
+  ```bash  theme={null}
+  claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
+  ```
+</Tip>
+
+### Debug plugin issues
+
+If your plugin isn't working as expected:
+
+1. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`
+2. **Test components individually**: Check each command, agent, and hook separately
+3. **Use validation and debugging tools**: See [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques
+
+### Share your plugins
+
+When your plugin is ready to share:
+
+1. **Add documentation**: Include a `README.md` with installation and usage instructions
+2. **Version your plugin**: Use [semantic versioning](/en/plugins-reference#version-management) in your `plugin.json`
+3. **Create or use a marketplace**: Distribute through [plugin marketplaces](/en/plugin-marketplaces) for installation
+4. **Test with others**: Have team members test the plugin before wider distribution
+
+Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).
+
+<Note>
+  For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).
+</Note>
+
+## Convert existing configurations to plugins
+
+If you already have custom commands, Skills, or hooks in your `.claude/` directory, you can convert them into a plugin for easier sharing and distribution.
+
+### Migration steps
+
+<Steps>
+  <Step title="Create the plugin structure">
+    Create a new plugin directory:
+
+    ```bash  theme={null}
+    mkdir -p my-plugin/.claude-plugin
+    ```
+
+    Create the manifest file at `my-plugin/.claude-plugin/plugin.json`:
+
+    ```json my-plugin/.claude-plugin/plugin.json theme={null}
+    {
+      "name": "my-plugin",
+      "description": "Migrated from standalone configuration",
+      "version": "1.0.0"
+    }
+    ```
+  </Step>
+
+  <Step title="Copy your existing files">
+    Copy your existing configurations to the plugin directory:
+
+    ```bash  theme={null}
+    # Copy commands
+    cp -r .claude/commands my-plugin/
+
+    # Copy agents (if any)
+    cp -r .claude/agents my-plugin/
+
+    # Copy skills (if any)
+    cp -r .claude/skills my-plugin/
+    ```
+  </Step>
+
+  <Step title="Migrate hooks">
+    If you have hooks in your settings, create a hooks directory:
+
+    ```bash  theme={null}
+    mkdir my-plugin/hooks
+    ```
+
+    Create `my-plugin/hooks/hooks.json` with your hooks configuration. Copy the `hooks` object from your `.claude/settings.json` or `settings.local.json`—the format is the same:
+
+    ```json my-plugin/hooks/hooks.json theme={null}
+    {
+      "hooks": {
+        "PostToolUse": [
+          {
+            "matcher": "Write|Edit",
+            "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
+          }
+        ]
+      }
+    }
+    ```
+  </Step>
+
+  <Step title="Test your migrated plugin">
+    Load your plugin to verify everything works:
+
+    ```bash  theme={null}
+    claude --plugin-dir ./my-plugin
+    ```
+
+    Test each component: run your commands, check agents appear in `/agents`, and verify hooks trigger correctly.
+  </Step>
+</Steps>
+
+### What changes when migrating
+
+| Standalone (`.claude/`)       | Plugin                           |
+| :---------------------------- | :------------------------------- |
+| Only available in one project | Can be shared via marketplaces   |
+| Files in `.claude/commands/`  | Files in `plugin-name/commands/` |
+| Hooks in `settings.json`      | Hooks in `hooks/hooks.json`      |
+| Must manually copy to share   | Install with `/plugin install`   |
+
+<Note>
+  After migrating, you can remove the original files from `.claude/` to avoid duplicates. The plugin version will take precedence when loaded.
+</Note>
+
+## Next steps
+
+Now that you understand Claude Code's plugin system, here are suggested paths for different goals:
+
+### For plugin users
+
+* [Discover and install plugins](/en/discover-plugins): browse marketplaces and install plugins
+* [Configure team marketplaces](/en/discover-plugins#configure-team-marketplaces): set up repository-level plugins for your team
+
+### For plugin developers
+
+* [Create and distribute a marketplace](/en/plugin-marketplaces): package and share your plugins
+* [Plugins reference](/en/plugins-reference): complete technical specifications
+* Dive deeper into specific plugin components:
+  * [Slash commands](/en/slash-commands): command development details
+  * [Subagents](/en/sub-agents): agent configuration and capabilities
+  * [Agent Skills](/en/skills): extend Claude's capabilities
+  * [Hooks](/en/hooks): event handling and automation
+  * [MCP](/en/mcp): external tool integration
+
+
+---
+
+> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

package/specs/cli-options.md

@@ -0,0 +1,52 @@
+# CLI Global Options
+
+This document specifies behavior for global CLI flags available across all `opkg` / `openpackage` commands.
+
+## `--cwd <dir>`
+
+### Overview
+The `--cwd` global option overrides the effective working directory for the entire command execution. It simulates running the CLI from `<dir>` instead of the shell's current directory, affecting:
+- Path resolutions (relative files, globs).
+- Package/workspace detection (e.g., `openpackage.yml` lookup at effective cwd).
+- File operations (install/save/add/pack/apply/uninstall/status target the specified dir's context).
+- Any code using `process.cwd()` (captured post-`--cwd` processing).
+
+This enables monorepo workflows without `cd` (e.g., `opkg install --cwd ./packages/web some-dep` installs into `./packages/web` from root).
+
+### Behavior
+1. **Parsing & Timing**: Commander parses it as global (usable before/after subcommand). Processed in `preAction` hook *before* subcommand action runs (after arg validation).
+2. **Resolution**: Resolved to absolute via `path.resolve(originalProcessCwd, <dir>)` (relatives vs shell cwd, not target).
+3. **Validation** (sync/async checks before chdir):
+   - Exists (fs.stat throws ENOENT if not).
+   - Is directory (fs.stat.isDirectory()).
+   - Readable/writable (fs.access R_OK | W_OK; errors if perms insufficient for cmd).
+   - Errors: Custom msg via console.error + log, `process.exit(1)` (e.g., "Invalid --cwd: must exist, be accessible, and writable").
+4. **chdir**: Calls `process.chdir(resolved)` if valid; logs "Changed working directory to: <abs>".
+5. **Effects**:
+   - All relative paths (e.g., getPackageYmlPath, file discovery) resolve vs new cwd.
+   - Package root = effective cwd (or --cwd dir).
+   - Global state unaffected (e.g., `~/.openpackage/registry` via os.homedir()).
+6. **Edge Cases**:
+   - Relative: `--cwd ../sibling` → resolves vs original.
+   - Invalid: Early exit, no action run.
+   - No-op: Omitted → uses shell cwd.
+   - Globals: Applies (harmless for login/list; may affect utils like prompts for rel paths).
+   - Subprocesses: Inherit new cwd (if spawned).
+7. **Limitations**: Doesn't re-parse other args vs new cwd (resolved early). User scripts via exec may need own handling.
+
+### Usage Patterns
+- Monorepos: Target sub-packages without cd.
+- Scripts: `opkg save --cwd $PROJ_DIR`.
+- Validation fails prevent ops (safety).
+
+Cross-refs: [install-behavior.md] (installs to effective cwd), [save-modes-inputs.md] (saves from effective cwd), [package-root-layout.md] (root = effective cwd).
+
+---
+
+## Command Notes (selected)
+
+This document primarily defines global flags, but some global-option-sensitive behavior is worth calling out:
+
+- **`opkg save`**: sync workspace edits back to a **mutable package source** based on `.openpackage/openpackage.index.yml` mappings.
+- **`opkg pack`**: write a snapshot of a package source to the local registry (no platform apply/sync is performed as part of packing). Use `opkg apply` to materialize content into platform directories.
+- **`opkg apply`**: applies/syncs the current/root package to detected platforms from the effective cwd. Supports `--dry-run` and `--force`.

package/specs/codex-mcp.md

@@ -0,0 +1,114 @@
+# Model Context Protocol
+
+Model Context Protocol (MCP) connects models to tools and context. Use it to give Codex access to third-party documentation, or to let it interact with developer tools like your browser or Figma.
+
+Codex supports MCP servers in both the CLI and the IDE extension.
+
+## Supported MCP features
+
+- **STDIO servers**: Servers that run as a local process (started by a command).
+  - Environment variables
+- **Streamable HTTP servers**: Servers that you access at an address.
+  - Bearer token authentication
+  - OAuth authentication (run `codex mcp login <server-name>` for servers that support OAuth)
+
+## Connect Codex to an MCP server
+
+Codex stores MCP configuration in `~/.codex/config.toml` alongside other Codex configuration settings.
+
+The CLI and the IDE extension share this configuration. Once you configure your MCP servers, you can switch between the two Codex clients without redoing setup.
+
+To configure MCP servers, choose one option:
+
+1. **Use the CLI**: Run `codex mcp` to add and manage servers.
+2. **Edit `config.toml`**: Update `~/.codex/config.toml` directly.
+
+### Configure with the CLI
+
+#### Add an MCP server
+
+```bash
+codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>
+```
+
+For example, to add Context7 (a free MCP server for developer documentation), you can run the following command:
+
+```bash
+codex mcp add context7 -- npx -y @upstash/context7-mcp
+```
+
+#### Other CLI commands
+
+To see all available MCP commands, you can run `codex mcp --help`.
+
+#### Terminal UI (TUI)
+
+In the `codex` TUI, use `/mcp` to see your active MCP servers.
+
+### Configure with config.toml
+
+For more fine-grained control over MCP server options, edit `~/.codex/config.toml`. In the IDE extension, select **MCP settings** > **Open config.toml** from the gear menu.
+
+Configure each MCP server with a `[mcp_servers.<server-name>]` table in the configuration file.
+
+#### STDIO servers
+
+- `command` (required): The command that starts the server.
+- `args` (optional): Arguments to pass to the server.
+- `env` (optional): Environment variables to set for the server.
+- `env_vars` (optional): Environment variables to allow and forward.
+- `cwd` (optional): Working directory to start the server from.
+
+#### Streamable HTTP servers
+
+- `url` (required): The server address.
+- `bearer_token_env_var` (optional): Environment variable name for a bearer token to send in `Authorization`.
+- `http_headers` (optional): Map of header names to static values.
+- `env_http_headers` (optional): Map of header names to environment variable names (values pulled from the environment).
+
+#### Other configuration options
+
+- `startup_timeout_sec` (optional): Timeout (seconds) for the server to start. Default: `10`.
+- `tool_timeout_sec` (optional): Timeout (seconds) for the server to run a tool. Default: `60`.
+- `enabled` (optional): Set `false` to disable a server without deleting it.
+- `enabled_tools` (optional): Tool allow list.
+- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).
+
+#### config.toml examples
+
+```toml
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+
+[mcp_servers.context7.env]
+MY_ENV_VAR = "MY_ENV_VALUE"
+```
+
+```toml
+[mcp_servers.figma]
+url = "https://mcp.figma.com/mcp"
+bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
+http_headers = { "X-Figma-Region" = "us-east-1" }
+```
+
+```toml
+[mcp_servers.chrome_devtools]
+url = "http://localhost:3000/mcp"
+enabled_tools = ["open", "screenshot"]
+disabled_tools = ["screenshot"] # applied after enabled_tools
+startup_timeout_sec = 20
+tool_timeout_sec = 45
+enabled = true
+```
+
+## Examples of useful MCP servers
+
+The list of MCP servers keeps growing. Here are a few common ones:
+
+- [Context7](https://github.com/upstash/context7): Connect to up-to-date developer documentation.
+- Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/): Access your Figma designs.
+- [Playwright](https://www.npmjs.com/package/@playwright/mcp): Control and inspect a browser using Playwright.
+- [Chrome Developer Tools](https://github.com/ChromeDevTools/chrome-devtools-mcp/): Control and inspect Chrome.
+- [Sentry](https://docs.sentry.io/product/sentry-mcp/#codex): Access Sentry logs.
+- [GitHub](https://github.com/github/github-mcp-server): Manage GitHub beyond what `git` supports (for example, pull requests and issues).