claude-alloy

Claude Alloy

A mixture stronger than its parts.

Quick Start • Agents • Install • Dev Guide • Contributing

Fourteen agents. Named after what they're made of.

Steel holds the structure. Tungsten doesn't melt under pressure. Mercury moves fast. Graphene conducts everything.

This is what Claude Code looks like with a team.

alloy

That's it. 14 agents, 17 hooks, 8 skills, 14 commands. Globally active. Open Claude in any directory and go.

unalloy

Back to vanilla Claude. Your original settings restored exactly.

The Agents

Model tiering is intentional. Opus handles orchestration and judgment. Sonnet handles research and analysis. Haiku handles grep. You pay for thinking, not searching.

Requirements

• Claude Code — Anthropic's CLI agent (npm install -g @anthropic-ai/claude-code)
• Claude Pro/Max subscription or Anthropic API key — Max recommended for multi-agent workloads
• bash (4.0+), jq, git

Token usage: claude-alloy routes Opus for orchestration, Sonnet for implementation, and Haiku for search — so you pay for thinking, not searching. Multi-agent tasks (especially ig mode) use more tokens than single-agent Claude Code. Claude Max 5x/20x with higher rate limits is strongly recommended. API users can expect roughly 2-3x typical token usage on complex tasks.

Quick Start

Simple (recommended)

One-time alias setup:

git clone https://github.com/OMARVII/claude-alloy.git
cd claude-alloy
bash setup-aliases.sh
source ~/.zshrc  # or ~/.bashrc

Then, anywhere:

alloy     # 14 agents active globally
unalloy      # back to vanilla Claude

Then inside Claude, type ig (or /ignite) for maximum effort mode — all agents fire in parallel, nothing ships half-done.

Plugin (Claude Code marketplace)

Status: Coming soon — pending Claude Code marketplace availability. For now, use the global toggle or per-project install.

# Local plugin testing (clone first)
claude --plugin-dir /path/to/claude-alloy

Per-project (teams)

# Install into a specific project only
bash install.sh --project /path/to/project

# Or set up the global /alloy-init command, then use it in any project
bash setup-global.sh
# In Claude Code:
/alloy-init

What You Get

.claude/
├── agents/               14 agents (steel, tungsten, quartz, mercury, graphene, carbon, prism, gauge, spectrum, sentinel, titanium, iridium, cobalt, flint)
├── skills/               8 skills (git-master, frontend-ui-ux, dev-browser, code-review, review-work, ai-slop-remover, tdd-workflow, verification-loop)
├── commands/             14 commands (/ignite, /ig, /loop, /halt, /alloy, /unalloy, /handoff, /refactor, /init-deep, /start-work, /status, /wiki-update, /notify-setup, /learn)
├── alloy-hooks/          17 hooks (all automatic, listed below)
├── wiki/                 project wiki (architecture, conventions, decisions)
├── agent-memory/         14 memory files (generated at install — agents learn across sessions)
├── settings.json         hook config + env vars
└── CLAUDE.md             injected context for all agents

Hooks (all automatic)

Commands

How It Works

Steel doesn't follow a fixed pipeline. It routes adaptively:

                ┌─ FAST: handle directly
                │
User → steel ──├─ RESEARCH: mercury ×N + graphene ×N (parallel)
   ↑            │     └─ prism checks INLINE as results arrive
   │ titanium   ├─ PLAN: carbon (only when 3+ files)
   │ (auto)     │     └─ gauge reviews only if carbon flags uncertainty
                ├─ BUILD: tungsten (autonomous, circuit breaker)
                │     └─ review gate (automatic, based on what changed):
                │           sentinel · iridium · cobalt · flint
                └─ CONSULT: quartz (on-demand, never in pipeline)

What makes this different: prism runs inline (not as a separate step), gauge is optional (not a required gate), and after every build a review gate auto-fires up to four reviewers — sentinel (security), iridium (performance), cobalt (dependencies), flint (tests) — based on what changed. quartz is never in a pipeline (only when stuck). No fixed sequence — steel adapts per task.

Type ig (or /ignite) for maximum effort: 4+ agents fired in parallel, todos tracked obsessively, manual QA before every completion claim. Two letters. Full team engaged.

Install Modes

alloy merges with your existing Claude settings. Your custom permissions, model preferences, and plugins are preserved. unalloy restores them exactly.

Uninstall

Development Guide

Adding a New Agent

1. Create agents/my-agent.md:

---
name: my-agent
description: "What this agent does."
model: sonnet
tools:
  - Read
  - Grep
  - Bash
maxTurns: 20
memory: project
---

Your system prompt here.

1. Create agent-memory/my-agent/MEMORY.md
2. Add the name to AGENTS in install.sh
3. Add to the roster in CLAUDE.md
4. Add to /alloy reference card
5. Test: bash install.sh --project ~/test-project

Adding a New Skill

1. Create skills/my-skill/SKILL.md:

---
name: my-skill
description: "When to auto-load this skill."
---

Skill instructions here.

1. Add to SKILLS in install.sh
2. Add to CLAUDE.md skills table

Adding a New Hook

1. Create hooks/my-hook.sh:

#!/usr/bin/env bash
set -u
INPUT=$(cat)

# Require jq for JSON parsing
command -v jq &>/dev/null || exit 0

# Your logic here

# Output for PostToolUse hooks (non-blocking feedback):
# jq -n --arg msg "Your message" '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":$msg}}'

# Exit codes: 0 = continue, 2 = block (with stderr message)
exit 0

1. chmod +x hooks/my-hook.sh
2. Add to settings.json under the appropriate event
3. Add to HOOKS in install.sh

Hook Events

Environment Variables

Set in settings.json:

Platform Support

# Install jq (required for hooks):
brew install jq        # macOS
sudo apt install jq    # Ubuntu/Debian
sudo dnf install jq    # Fedora

Architecture Decisions

Contributing

See CONTRIBUTING.md for how to add agents, skills, hooks, and submit PRs.

Agents follow the material/metal naming convention — the name should reflect the agent's core property.

Security

See SECURITY.md for the security policy, known considerations, and how to report vulnerabilities.

Changelog

See CHANGELOG.md for release history. Current version: 1.3.0.

Inspiration

Built on Claude Code. Inspired by the agent orchestration patterns pioneered by oh-my-openagent.

The alloy concept: individual agents are metals — each with specific properties. Together, they're stronger than any single element. The same principle applies to AI agents.

License

MIT