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:

• 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:

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.