Outfit

<p align="center"> <img src="https://raw.githubusercontent.com/MyceliumInc/Outfit/HEAD/assets/banner.png" alt="Outfit - a row of cute agent mascots, each wearing a different outfit" width="640"> </p>

<h1 align="center">Outfit</h1>

Turn an agent persona into a contract the runtime actually enforces, not a prompt it can ignore.

An Outfit is one declarative file that defines an agent persona - its identity, the capabilities it is allowed to use, the skills it wears - plus a permissions contract that is enforced at runtime. MCP gives an agent raw capability with no boundaries. System prompts and Skills give it instructions it can quietly ignore. Outfit makes the contract real: a gateway becomes the agent's entire tool-world, every call is scope-checked, and native tools are denied. So "read-only reviewer" means it physically cannot write.

                  WITHOUT OUTFIT                            WITH OUTFIT

  agent ── "please don't edit files" (prompt)       agent  (sees only the gateway)
    │                                                  │
    ▼                                                  ▼
  [ native tools: Edit, Bash, Write, ... ]      ┌───────────────────────────────┐
    │        the agent can ignore the ask       │       OUTFIT GATEWAY          │
    ▼                                           │  an MCP server that IS the    │
  filesystem / shell / network  ◄── oops        │  agent's whole tool-world     │
                                                ├───────────────────────────────┤
                                                │  every call is scope-checked  │
                                                │   fs.read    paths: **/*    ✓ │
                                                │   fs.write   not granted    ✗ │
                                                │   shell.exec allow: git diff* │
                                                │              deny:  git push* │
                                                │   http.fetch domains:*.sec.gov│
                                                └───────────────┬───────────────┘
                                                                ▼
                                       native tools DENIED · only permitted calls pass

	MCP	Skills / prompts	Outfit
Gives the agent capability	yes	no	yes
Gives the agent instructions	no	yes	yes
Permissions enforced, not just asked	no	no	yes
Agent can ignore the boundary	n/a	yes	no
Portable across runtimes	part	no	yes
Shareable as one unit	no	per-tool	yes

MCP is what an agent can do. Skills are what you tell it to do. Outfit is what it is allowed to do.

Quickstart

Install from npm:

npm install -g @myceliuminc/outfit

Or from source:

git clone https://github.com/MyceliumInc/Outfit && cd Outfit
npm install && npm run build && npm link

Then:

outfit doctor code-reviewer     # can this runtime actually enforce it?
outfit use code-reviewer        # wear it in the current project
# reload Claude Code

Then ask the agent to change a file:

You:  Fix the bug in src/auth.ts

Agent (wearing code-reviewer):
  I can't modify files while wearing this outfit - I'm read-only.
  Here's the fix to apply yourself:

  src/auth.ts:42  the token check is inverted:
  -  if (!isValid(token)) return ok()
  +  if (!isValid(token)) return deny()

The agent did not decide to stay read-only. The Edit tool was never in its world; the only filesystem capability it has is fs.read. Take it off any time:

outfit status     # code-reviewer (claude-code)
outfit doff       # native tools restored, exactly as before

Marketplace

Browse, star, and download community outfits at outfits.mycelium.markets. Every listing is validated against this package's schema and ontology before it goes live, so anything there installs cleanly. Install a listing by name (the CLI falls back to the marketplace when a bare name is not in the bundled registry):

outfit add some-published-outfit                                       # bare name: registry, then marketplace
outfit add https://outfits.mycelium.markets/api/outfit/some-published-outfit   # or the raw URL
outfit use some-published-outfit

Publish your own from the site's upload page. The raw outfits.mycelium.markets/api/outfit/<name> endpoint serves the canonical *.outfit.yaml and is what outfit add fetches.

How enforcement works

The trick is the Outfit Gateway, an MCP server that is the agent's entire tool-world:

• Capabilities (shell.exec, fs.read, http.fetch, web.search, ...) are implemented by the gateway itself and scope-checked on every call. Same behavior on every runtime.
• Integrations (raw MCP servers) are launched as children and proxied through, exposing only the tools the contract allows.
• Each adapter then locks the runtime down to the gateway and disables native tools.
• The persona clothes the main session directly (for Claude Code, a delimited block in CLAUDE.md), so the agent adopts the identity and inherits the locked-down world.

Enforcement is per-runtime, so every adapter publishes a conformance matrix. If an outfit requires something an adapter cannot guarantee, outfit doctor fails for that target. That is the honest meaning of "enforced".

The spec

This is the code-reviewer outfit that produced the demo above:

apiVersion: outfit/v1
name: code-reviewer
description: Read-only code reviewer that inspects the diff and never edits.
identity:
  prompt: |
    You are a precise, senior code reviewer. You never modify files; you can only
    read and run read-only inspection commands.
capabilities:
  - id: shell.exec
    scope:
      allow: ["git diff*", "git log*", "rg *", "ls *", "cat *"]
      deny:  ["git push*", "git commit*", "rm *"]
  - id: fs.read
    scope: { paths: ["**/*"] }
  - id: fs.list
    scope: { paths: ["**/*"] }

Add # yaml-language-server: $schema=https://raw.githubusercontent.com/MyceliumInc/Outfit/HEAD/schema/outfit.schema.json as the first line of your outfit for editor validation. See examples/ for more, including stock-analyst (web + scoped writes) and notes-keeper (an integration).

Capability ontology

Capability	Scope
shell.exec	allow / deny command globs
fs.read	paths globs
fs.write	paths globs
fs.list	paths globs
http.fetch	domains globs
web.search	domains globs (+ provider)

web.search needs OUTFIT_SEARCH_PROVIDER (e.g. tavily) and OUTFIT_SEARCH_API_KEY. Add a capability in src/spec/ontology.ts and a handler in src/gateway/capabilities.ts and it becomes available to every adapter.

Let Claude author one for you

outfit install-skill              # writes .claude/skills/create-outfit/SKILL.md

Then ask Claude to "make an outfit that ...". The skill interviews you, picks least-privilege capabilities, writes the spec, and runs outfit validate and outfit doctor to check it. (outfit install-command adds the /outfit picker.)

Security model

The gateway is the only tool-world the agent has, so enforcement happens at the capability boundary, not in the prompt. On every call:

• Shell operator blocking. shell.exec rejects commands containing ; & | backtick < > $( ${ and newlines, so an allow-listed wildcard like git diff* cannot chain a second command.
• Filesystem root confinement. fs.* paths are confined to the static root of each allowed glob, so a broad pattern like **/* still cannot reach /etc/passwd.
• Symlink canonicalization. Paths are resolved to a fixed point segment by segment, so a symlink (or a chain of them) cannot point outside the allow-list.
• Exact / suffix domains. Hosts match exactly or by dot-bounded suffix (*.sec.gov matches sec.gov and data.sec.gov, never evilsec.gov). Redirects are re-checked on every hop and non-http(s) schemes are rejected.
• Sanitized environment. Shell and integration child processes get a small allow-list of env vars; secrets and OUTFIT_* are never passed through.
• Native-tool denial. Each adapter disables the runtime's built-in tools so the agent cannot route around the contract.

Limitations

Outfit raises the floor; it is not a sandbox.

• Exec escapes. Allow-listing a binary that can spawn other programs (interpreters, find -exec, pagers, git -c) can be used to break out. Allow-list the narrowest commands you can and prefer deny-by-default.
• Integration arguments are not gated. Proxied integration calls pass through without argument-level scope checks. Only grant integrations you trust.
• Domain allow-listing is name-based. It does not stop DNS rebinding or requests to internal or link-local IPs. Do not treat it as a network firewall.

CLI

Command	What it does
outfit list [--json]	Discover outfits across search paths
outfit add <url|github:..|name>	Fetch and install an outfit (a bare name resolves via the registry, then the marketplace)
outfit remove <name>	Remove an installed outfit
outfit init <name>	Scaffold a new outfit in ./outfits
outfit validate <ref> [--json]	Schema + ontology validation
outfit doctor <ref> [-t target] [--json]	Preflight: can the target enforce it?
outfit compile <ref> -t <target> -o <dir>	Emit runtime config
outfit use <ref> [-t target] [--force]	Wear it in the current project
outfit status [--json]	Show the outfit worn here
outfit doff	Remove the worn outfit
outfit targets [--json]	List adapters + conformance matrices
outfit install-command	Install the /outfit picker
outfit install-skill	Install the create-outfit skill

Run outfit <command> --help for per-command usage.

Programmatic API

The spec, gateway, doctor, and adapters are available as a typed ESM library:

import { loadOutfit, validateSemantics, doctor, runGateway, ONTOLOGY } from "@myceliuminc/outfit";

const { outfit } = loadOutfit("outfits/code-reviewer.outfit.yaml");
if (doctor(outfit, "claude-code").ok) {
  await runGateway(outfit); // serve the outfit as an MCP gateway
}

The scope enforcers (assertShellAllowed, assertPathAllowed, assertUrlAllowed), buildGatewayServer, and the adapter registry (ADAPTERS, getAdapter) are exported too. The use / doff lifecycle is CLI-only.

Targets

Target	gateway	deny-native	hooks	slash	integrations
claude-code	yes	yes	yes	yes	yes
openai-agents (experimental)	yes	yes (by omission)	no	no	yes

The openai-agents adapter emits an agent script; verify it against your installed @openai/agents version.

Reference

<details> <summary>Search paths, project layout, development</summary>

Outfits are discovered (in order) from ./outfits/, ~/.outfit/outfits/, and the bundled examples/.

src/index.ts    public API barrel
src/spec/       schema + ontology + loader (portable core)
src/gateway/    MCP gateway: implements + enforces capabilities
src/adapters/   per-runtime compilers + conformance matrices
src/cli/        the `outfit` command
test/           node:test suites

npm install
npm run build      # tsc -> dist/ (+ type declarations)
npm test           # builds, then runs the suites

Runtime dependencies are kept deliberately small: the MCP SDK, zod, yaml, and minimatch. The CLI uses Node's built-in util.parseArgs.

</details>

See CONTRIBUTING.md and SECURITY.md. Licensed MIT.