Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/omarvii/claude-alloy

Multi-agent orchestration for Claude Code — pure config, no wrapper, no runtime.
https://github.com/omarvii/claude-alloy

agents ai-agents anthropic claude claude-code cli developer-tools multi-agent orchestration

Last synced: about 2 months ago
JSON representation

Multi-agent orchestration for Claude Code — pure config, no wrapper, no runtime.

Awesome Lists containing this project

README 

          


  Claude Alloy






  A mixture stronger than its parts.






  CI

  License: MIT

  Version 1.6.11






  Quick Start •

  Agents •

  Install •

  Dev Guide •

  Contributing






  claude-alloy in IGNITE mode — steel verbalizes intent, fires specialists in parallel, and the HUD statusline tracks context / cost / quota live






  ig activates IGNITE mode — steel verbalizes intent, fires specialists in parallel, and the HUD tracks context / cost / quota live.




---



Claude Code with a team.



Fourteen specialist agents. Model-tiered (Opus/Sonnet/Haiku) so you stop overpaying for searches. Zero runtime. One config overlay. One command to activate, one to remove.



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



```bash

alloy

```



That's it. 14 agents, 23 hooks, 10 skills, 15 commands + HUD statusline. Globally active. Open [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in any directory and go.





  If this saves you time, give it a ⭐ — that's how I know to keep building.




```bash

unalloy

```



Back to vanilla Claude. Your original settings restored exactly.



---



## The Agents



| Agent | Model | Role | Why the name |

|---|---|---|---|

| **steel** | opus | Main orchestrator. Plans, delegates, verifies. | The alloy that holds everything together. |

| **tungsten** | opus | Autonomous execution. Won't stop until done. | Highest melting point of any metal. |

| **quartz** | opus | Architecture consultant. Read-only. | Crystal clear — sees through problems. |

| **carbon** | sonnet | Strategic planner. Interview-first. | Foundation element — basis of all structure. |

| **gauge** | sonnet | Code and plan reviewer. Pass/fail. | Measures precisely. No ambiguity. |

| **graphene** | sonnet | External docs and research. | One atom thick. Conducts everything. |

| **prism** | sonnet | Finds hidden ambiguities before planning. | Splits light to reveal all angles. |

| **spectrum** | sonnet | Image, PDF, diagram analysis. | Full range of vision. |

| **mercury** | haiku | Fast codebase search. Cheap to fire. | Quicksilver — everywhere at once. |

| **sentinel** | opus | Security reviewer. CWE Top 25, secrets, injection. Read-only. | The watchman. Never sleeps. |

| **titanium** | sonnet | Context recovery. Rebuilds state from previous sessions. | Highest strength-to-weight ratio. Lightweight but recovers everything. |

| **iridium** | sonnet | Performance reviewer. Finds O(n²), memory leaks, N+1 queries. | Densest natural element. Catches the heaviest problems. |

| **cobalt** | sonnet | Dependency expert. CVEs, outdated packages, supply chain risks. | Essential trace element. Small but critical to the whole. |

| **flint** | sonnet | Test engineer. Coverage gaps, flaky tests, missing edge cases. | Strikes sparks. Finds what breaks. |



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



---



## What Makes claude-alloy Different



- **Pure config, no runtime.** No plugin system, no daemon, no background process. Just markdown agent definitions, shell hooks, and a `settings.json`. If you can read bash, you can audit every line of it.

- **Deliberate model tiering.** Opus for orchestration and judgment. Sonnet for research and implementation. Haiku for grep. You pay for thinking, not searching.

- **Multiple install modes.** Global toggle via `activate.sh` / `deactivate.sh`, per-project drop-in, plugin-style, or global command — pick what fits your workflow.

- **Fully reversible.** `/unalloy` restores your previous Claude Code config exactly. No lock-in, no residue.

- **Adaptive routing, not a linear pipeline.** Steel routes tasks by what they need (FAST, RESEARCH, PLAN, BUILD, SECURITY, etc.) rather than forcing every task through a fixed sequence or spawning agents without a clear purpose.



---



## Requirements



- [**Claude Code**](https://docs.anthropic.com/en/docs/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:



```bash

git clone https://github.com/OMARVII/claude-alloy.git

cd claude-alloy

bash setup-aliases.sh

source ~/.zshrc  # or ~/.bashrc

```



Then, anywhere:



```bash

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:** Plugin metadata is included, but global toggle or per-project install remains recommended for the full hook/settings experience. Claude Code plugin-scoped agents have stricter limits than files installed into `~/.claude` or a project `.claude/` directory.



```bash

# Local plugin testing (clone first)

claude --plugin-dir /path/to/claude-alloy

```



### Per-project (teams)



```bash

# 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/               10 skills (git-master, frontend-ui-ux, dev-browser, code-review, review-work, ai-slop-remover, tdd-workflow, verification-loop, pipeline, hyperplan)

├── commands/             15 commands (/ignite, /ig, /loop, /halt, /alloy, /unalloy, /handoff, /refactor, /init-deep, /start-work, /status, /wiki-update, /notify-setup, /learn, /assess)

├── alloy-hooks/          23 hooks (all automatic, listed below) + statusline HUD

├── 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)



| Hook | When | What it does |

|---|---|---|

| **write-guard** | Before Write | Blocks overwriting existing files — use Edit instead |

| **branch-guard** | Before Write/Edit | Blocks edits on main/master; allows docs (warn), `ALLOY_BRANCH_GUARD=off\|warn`, or `.claude/branch-guard.off` marker |

| **comment-checker** | After Write/Edit | Warns about AI slop comments |

| **edit-ledger** | After Write/Edit/MultiEdit/NotebookEdit | Records implementation edits for IGNITE review enforcement |

| **typecheck** | After .ts/.tsx edits | Runs `tsc --noEmit`, reports errors |

| **auto-install** | After package.json/requirements.txt/pyproject.toml | Installs dependencies (lifecycle scripts disabled for safety) |

| **agent-reminder** | After 5 direct searches | Suggests mercury/graphene when research has become broad |

| **agent-count** | After Agent/Task dispatch | Records spawned agents for IGNITE enforcement |

| **lint** | After Write/Edit | Runs ESLint/Biome/Prettier, reports errors |

| **skill-reminder** | After 12 direct tool calls | Suggests relevant skills or agents if the task has expanded |

| **todo-enforcer** | Before stopping | Reminds about incomplete todos (blocks once, then allows) |

| **loop-stop** | Before stopping | Keeps working if `/loop` is active |

| **session-notify** | On stop | Desktop notification when session ends |

| **pre-compact** | Before compaction | Saves critical context before memory compaction |

| **subagent-start** | On subagent start | Tracks agent activity and delegation |

| **subagent-stop** | On subagent stop | Verifies agent deliverables and results |

| **rate-limit-resume** | On stop failure | Auto-resumes on rate limit (up to 3x) |

| **session-start** | On session start | Injects wiki context into session |

| **session-end** | On session end | Nudges wiki update if session was productive |

| **ignite-detector** | On user prompt | Detects `ig`/`ignite` keywords, sets IGNITE session flag |

| **ignite-stop-gate** | Before stopping | Blocks exit if IGNITE protocol wasn't followed (6+ agents, graphene, review) |

| **context-pressure** | After any tool | Advisory warnings at ~70% / ~85% context usage (100 / 140 tool calls) |

| **statusline** | Persistent HUD | HUD: model, ctx%, session duration, tool count, cwd (via settings.json statusLine) |



### Commands



| Command | What it does |

|---|---|

| **`/ignite`** (or just **`ig`**) | Maximum effort mode. 6+ agents fire in parallel, todos tracked obsessively, manual QA before completion. The signature move. |

| `/loop` | Autonomous loop — agent works until task is 100% complete |

| `/halt` | Stop the loop |

| `/alloy` | Show all agents, skills, commands, hooks |

| `/unalloy` | Remove claude-alloy from current project |

| `/handoff` | Create context summary for session continuation |

| `/refactor` | Safe refactoring with LSP diagnostics |

| `/init-deep` | Generate hierarchical CLAUDE.md files |

| `/start-work` | Execute a plan from carbon |

| `/status` | Show loop state, pending todos, branch, recent activity |

| `/wiki-update` | Update project wiki with session learnings |

| `/notify-setup` | Configure desktop, Slack, and Discord notifications |

| `/learn` | Extract reusable patterns from the current session into skills |

| `/assess` | Scan project health — rate Claude Code maturity 0–10 and suggest next steps |



---



## 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 fires the matching 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 and no agent spawn without a reason — steel adapts per task.



Default mode is precision-routed — agents fire when uncertainty, risk, or scale makes them valuable. `ig` is the explicit opt-in for full parallelism.



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



---



## Install Modes



| Method | Command | Who it's for |

|---|---|---|

| **Global toggle** | `alloy` / `unalloy` | Most users — instant, reversible |

| **Plugin** | `claude plugin add claude-alloy` | Marketplace users (metadata included; full hook install still recommended) |

| **Per-project** | `bash install.sh --project .` | Teams — committed to version control |

| **Global command** | `bash setup-global.sh` then `/alloy-init` | One command per project |



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



### Uninstall



| What to remove | Command |

|---|---|

| Deactivate (keep files) | `unalloy` |

| Remove aliases | `bash setup-aliases.sh --uninstall` |

| Remove global command | `bash setup-global.sh --uninstall` |

| Remove per-project install | `bash install.sh --uninstall` |

| Remove everything | All of the above |



## Updating



> **TL;DR** — `cd /path/to/claude-alloy && git pull`. Global symlink installs update instantly. Copy-mode and per-project installs need one extra step: run `alloy` or `bash install.sh --project .` again.



### Global install (alloy/unalloy)



Global installs (`alloy`) use **symlinks** by default on macOS and Linux. This means `git pull` in the claude-alloy repo updates all agents, skills, commands, and hooks immediately — no re-activation required.



```bash

cd /path/to/claude-alloy

git pull                 # symlink mode: changes are live immediately

```



If you prefer explicit control:



```bash

alloy --update           # pull latest + re-activate in one step

alloy --check            # run health checks (alloy doctor)

alloy --version          # show installed version

```



To disable auto-update on activation:



```bash

export ALLOY_AUTO_UPDATE=0   # env var (per-session)

touch ~/.claude/.alloy-no-update  # persistent opt-out

```



On WSL/Windows or filesystems that don't support symlinks, alloy automatically falls back to **copy mode**. In copy mode, run `alloy` after `git pull` to apply updates.



### Per-project update



Per-project installs always use copies (not symlinks), so updates require re-running the installer:



```bash

cd /path/to/claude-alloy

git pull

bash install.sh --project /path/to/your/project

```



### Global command update (/alloy-init)



If you used `setup-global.sh` + `/alloy-init` to install projects, update the cached payload first:



```bash

cd /path/to/claude-alloy

git pull

bash setup-global.sh         # refreshes ~/.claude/alloy-dist/

```



Then re-run `/alloy-init` inside each project in Claude Code to apply the update.



### Troubleshooting



| Symptom | Cause | Fix |

|---|---|---|

| Broken symlinks after moving the clone | Symlinks point to old repo path | Run `alloy` again from the new location |

| `git pull` fails with diverged error | Local commits on main branch | `cd /path/to/claude-alloy && git pull --rebase origin main` |

| WSL uses copy mode instead of symlinks | NTFS/drvfs doesn't support real symlinks | Expected behavior — run `alloy` after `git pull` |

| Stale `/alloy-init` payloads | `setup-global.sh` payload outdated | Run `bash setup-global.sh` again |

| Hooks firing twice after update | Duplicate hook entries in settings.json | Run `unalloy && alloy` to regenerate clean settings |



---



## Development Guide



### Adding a New Agent



1. Create `agents/my-agent.md`:

```yaml

---

name: my-agent

description: "What this agent does."

model: sonnet

tools:

  - Read

  - Grep

  - Bash

maxTurns: 20

memory: project

---



Your system prompt here.

```



2. Create `agent-memory/my-agent/MEMORY.md`

3. Add the name to `AGENTS` in `install.sh`

4. Add to the roster in `CLAUDE.md`

5. Add to `/alloy` reference card

6. Test: `bash install.sh --project ~/test-project`



### Adding a New Skill



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

```yaml

---

name: my-skill

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

---



Skill instructions here.

```



2. Add to `SKILLS` in `install.sh`

3. Add to `CLAUDE.md` skills table



### Adding a New Hook



1. Create `hooks/my-hook.sh`:

```bash

#!/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

```



2. `chmod +x hooks/my-hook.sh`

3. Add to `settings.json` under the appropriate event

4. Add to `HOOKS` in `install.sh`



### Hook Events



| Event | When | Can Block? |

|---|---|---|

| `PreToolUse` | Before tool execution | Yes |

| `PostToolUse` | After tool execution | No |

| `Stop` | Before session stops | Yes |

| `PreCompact` | Before memory compaction | No |

| `SubagentStart` | When a subagent is spawned | No |

| `SubagentStop` | When a subagent completes | No |

| `StopFailure` | When session stops due to error | No |

| `SessionStart` | When a session starts/resumes | No |

| `SessionEnd` | When a session ends | No |

| `UserPromptSubmit` | When user submits a prompt | No |



---



## Environment Variables



### Harness config (set in `settings.json`)



| Variable | Value | Why |

|---|---|---|

| `BASH_DEFAULT_TIMEOUT_MS` | `420000` (7 min) | Prevents timeout on long builds and test suites |

| `BASH_MAX_TIMEOUT_MS` | `420000` (7 min) | Same |

| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | `1` | Removes built-in git workflow instructions and git status snapshot from system prompt — saves tokens (alloy provides its own via CLAUDE.md) |



### Opt-in hook gates (set in your shell rc — off by default since v1.6.1)



Two hooks can execute project-local code and are therefore disabled unless you explicitly opt in. See [SECURITY.md](SECURITY.md#opt-in-hook-gates-off-by-default-since-v161) for the full threat model.



| Variable | Enables | What it does |

|---|---|---|

| `ALLOY_AUTO_LINT=1` | `hooks/lint.sh`, `hooks/typecheck.sh` | Runs `npx --no-install` for eslint / biome / prettier / tsc after file edits. Off by default — `npx` resolves binaries from `node_modules/.bin/` in the project you opened, which is a code-execution surface in untrusted repos. |

| `ALLOY_AUTO_INSTALL=1` | `hooks/auto-install.sh` | Runs `npm install --ignore-scripts` / `pip install --no-deps --only-binary=:all:` after manifest edits. Off by default — dependency names written into `package.json` / `requirements.txt` by the agent could be typosquats. Editable pip installs (`pip install -e .`) are never run automatically even when this is set. |

| `ALLOY_AUTO_UPDATE=0` | `self-update.sh` | Set to `0` to disable the weekly self-update check (default: enabled, checks at most once per 7 days; only pulls if `origin` remote is exactly `OMARVII/claude-alloy`). |

| `ALLOY_BROWSER=1` | `/dev-browser` skill | Enables Playwright MCP browser automation. Requires `@playwright/mcp` to be installed. |



### Optional: MCP Tool Search opt-in (power-user tip)



If you've added many MCP servers and your context fills up fast, Claude Code has a deferred-loading feature called **Tool Search** that loads MCP tool schemas only when needed. Anthropic's docs claim **over 85% MCP schema reduction** when active.



**Default behavior:** Claude Code tries to auto-activate Tool Search when MCP tools exceed ~10% of context. Most users with a small MCP set don't need to do anything.



**Force-enable (recommended only if you have 10+ MCP servers):**



```bash

# Add to ~/.zshrc or ~/.bash_profile

export ENABLE_TOOL_SEARCH=true

```



**Caveats:**

- Auto-activation has [known reliability bugs](https://github.com/anthropics/claude-code/issues/18397) — the env var is the workaround.

- The env var is [silently ignored on Windows Desktop](https://github.com/anthropics/claude-code/issues/41472). macOS/Linux CLI works.

- Adds a search round-trip per request — only worth it when MCP schemas are actually large.

- Requires Sonnet 4+, Opus 4+, or Haiku 4.5+.



claude-alloy ships only 3 always-on MCP servers (context7, grep_app, websearch), so most users won't need this. Power users adding Linear/Notion/Slack/HubSpot/etc. on top will see the biggest benefit.



---



## Platform Support



| Platform | Status | Notes |

|---|---|---|

| **macOS** | Full support | Tested on macOS 14+ |

| **Linux** | Full support | Ubuntu, Debian, Fedora, Arch |

| **Windows** | Via WSL | Claude Code requires WSL on Windows — our scripts work inside WSL |



```bash

# Install jq (required for hooks):

brew install jq        # macOS

sudo apt install jq    # Ubuntu/Debian

sudo dnf install jq    # Fedora

```



## Architecture Decisions



| Decision | Rationale |

|---|---|

| Claude-only models | Opus/Sonnet/Haiku tiering. One provider, no API key juggling. |

| Per-project install | Each project opts in. Nothing polluted globally (unless you want it with `alloy`). |

| Shell hooks | Claude Code hooks are external processes. Shell is universal, zero dependencies except jq. |

| 14 agents, not 30+ | Curated over comprehensive. Every agent earns its slot. No bloat. |

| Block-once todo enforcer | Reminds the agent once, then lets you stop. Smart, not annoying. |

| Agent memory files | Agents learn across sessions. Preferences, patterns, edge cases persist. |



---



## Contributing



See [CONTRIBUTING.md](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](SECURITY.md) for the security policy, known considerations, and how to report vulnerabilities.



---



## Changelog



See [CHANGELOG.md](CHANGELOG.md) for release history. Current version: **1.6.11**.



---



## License



[MIT](LICENSE)