Outfit: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Outfit turns an agent persona into a contract the runtime enforces, not a prompt it can ignore. An outfit is one declarative YAML/JSON file (identity + capabilities + permissions

• optional integrations/skills). The package is the @myceliuminc/outfit npm CLI/library.

The public marketplace is outfits.mycelium.markets (the sibling OutfitMarket repo): a Supabase-backed registry of downloadable outfits. It is distinct from the bundled examples/ and the GitHub registry/index.json. outfit add <name> resolves a bare name against the GitHub registry first, then falls back to the marketplace at outfits.mycelium.markets/api/outfit/<name>, which serves the canonical *.outfit.yaml.

Commands

npm run build      # tsc -> dist/ (+ .d.ts), then chmods dist/cli/index.js
npm test           # runs `pretest` (build) then `node --test` over test/
npm run dev        # tsc -w

Tests import from compiled dist/, not src/. Always build before running a single test file:

npm run build && node --test test/scope.test.mjs   # one suite

CI runs npm ci && npm run build && npm test on Node 18, 20, 22. Minimum is Node 18.

Architecture

The codebase is small (~1800 LOC of TS) and split into four layers under src/, mirrored by dist/ and the public barrel src/index.ts:

• src/spec/ — the portable core. schema.ts (zod) defines the outfit document; ontology.ts is the closed set of capability ids (shell.exec, fs.read/write/list, http.fetch, web.search), each with a ScopeKind (shell/fs/net) and JSON input schema; index.ts is the loader/validator/discovery (loadOutfit, validateSemantics, discoverOutfits, resolveOutfit).
• src/gateway/ — the enforcement engine. server.ts builds an MCP server that IS the agent's whole tool-world: each capability becomes a gateway tool; each integration is a child MCP server launched and proxied (only allow-listed tools exposed). capabilities.ts holds the per-capability HANDLERS (each scope-checks before acting) and sanitizedEnv. scope.ts holds the three enforcers — assertShellAllowed, assertPathAllowed, assertUrlAllowed — and is the security-critical file.
• src/adapters/ — per-runtime compilers. Each Adapter has a conformance matrix (routeViaGateway, denyNative, hooks, slashCommands, integrations) and a compile() that emits runtime config. claude-code.ts writes .mcp.json (registers the gateway), .claude/settings.json (denies NATIVE_TOOLS, allows mcp__outfit-<name>__*), and a delimited persona block in CLAUDE.md. openai-agents.ts is experimental. Register new adapters in ADAPTERS in index.ts.
• src/cli/ — the outfit command (index.ts) and doctor.ts (preflight that checks whether a target's conformance can satisfy the outfit). The use/doff lifecycle is CLI-only; everything else is also exported as a library.