Work-with-Alloy Plugin

Support reference for the `work-with-alloy` Claude Code / Codex plugin.

Repository: https://github.com/Alloy-Systems/work-with-alloy

`work-with-alloy` is a Claude Code and Codex plugin that automatically wires an AI agent to Alloy. When the plugin is active, the agent:

- connects to Alloy's hosted MCP endpoint and gains access to Alloy storage, documentation, system actions, and assigned upstream integrations - loads the `work-with-alloy` skill, which instructs the agent to treat Alloy as its source of truth for reading context and writing durable knowledge - follows the Alloy knowledge-management rules (artifact log, knowledge.md, org context) without any per-conversation setup

The plugin ships two parts:

| Component | File | Purpose | |-----------|------|---------| | Skill | `skills/work-with-alloy/SKILL.md` | Behavioral instructions loaded into the agent's context at session start | | MCP config | `.mcp.json` | Points the agent at `https://api.alloy.cx/mcp` with a bearer token |

- An Alloy organization with an AI teammate and a minted PAT (see `hosted-mcp.md`) - An `ALLOY_TOKEN` environment variable set to that token

The plugin reads `ALLOY_TOKEN` at session start. If it is missing, the MCP connection will be skipped.

### Claude Code

```bash # Add the community marketplace (first time only) claude plugin marketplace add Alloy-Systems/work-with-alloy

# Install claude plugin install work-with-alloy ```

After installation, restart Claude Code. Confirm the MCP is active:

```bash claude mcp list | grep alloy ```

### Codex

Codex picks up `.mcp.json` files automatically when the plugin is loaded via `--plugin-dir` or after marketplace installation. Ensure `ALLOY_TOKEN` is exported in the environment Codex runs in.

The `work-with-alloy` skill activates automatically in every session where it is present. It:

- reads `Organization/organization.md` and relevant `knowledge.md` files at startup - routes all durable notes, proposals, and artifacts to Alloy Storage rather than local files - logs created and updated docs to the user's artifact log - instructs the agent to write knoledge notes to Alloy

The skill description is intentionally written to trigger automatic use — no slash command is needed.

Tokens are created from the AI teammate's `PATs` tab in Alloy. Each token is shown only once at creation time.

To rotate a PAT: delete the old one from the tab, generate a new one, and update `ALLOY_TOKEN` in the environment.

See `hosted-mcp` for full token-management details.

The plugin follows semantic versioning:

| Bump | Meaning | |------|---------| | Patch | Wording fixes, clarity edits with no behavioral change | | Minor | New guidance, new skill sections, additive changes | | Major | Breaking path changes, rule removals, or structural rework |

Current release: `v0.1.0`

Release tags are on the repository. Users on a pinned marketplace version receive updates when the marketplace pin is bumped.