setup-sh

Bootstrap a multi-agent workspace with team standards, hooks, and skills for Claude Code, OpenAI Codex, and Cursor IDE.

Supported Agents

| Agent | Config | Instructions | Skills/Rules | |-------|--------|--------------|--------------| | Claude Code (Anthropic) | .claude/settings.json | CLAUDE.md | .claude/skills/ | | Codex (OpenAI) | .codex/config.toml | AGENTS.md | .codex/skills/ | | Cursor (Cursor IDE) | .cursor/hooks.json | CLAUDE.md* | .cursor/rules/ |

* Cursor natively reads CLAUDE.md and AGENTS.md

Usage

# Interactive mode (prompts for agent selection)
npx @acmeacmeio/setup-sh

# Specify agent via flag
npx @acmeacmeio/setup-sh . --agent=claude   # Claude Code only
npx @acmeacmeio/setup-sh . --agent=codex    # Codex only
npx @acmeacmeio/setup-sh . --agent=cursor   # Cursor IDE only
npx @acmeacmeio/setup-sh . --agent=all      # All agents

# Create new project directory
npx @acmeacmeio/setup-sh my-project --agent=all

# Non-interactive mode
npx @acmeacmeio/setup-sh my-project --agent=claude --yes

What It Does

1. Installs Required Tools (if missing)

   • GitHub CLI (gh)
   • Node.js
   • pnpm
   • Python 3.11+ and uv

2. Creates Workspace Structure

   Claude Code:

   .claude/
   ├── settings.json      # Permissions, hooks
   ├── commands/          # Slash commands (/tdd, /review, etc.)
   ├── skills/            # Domain knowledge
   └── router/            # Intent classification system
   CLAUDE.md              # Team standards
   .mcp.json              # MCP server configuration

   Codex:

   .codex/
   ├── config.toml        # Model, sandbox, MCP servers
   └── skills/            # Domain knowledge (same format as Claude)
   AGENTS.md              # Team standards

   Cursor:

   .cursor/
   ├── rules/             # MDC rules with YAML frontmatter
   │   ├── tdd.mdc        # Always apply - TDD methodology
   │   ├── typescript.mdc # Auto-attach on *.ts, *.tsx
   │   ├── api-design.mdc # Agent requested - REST patterns
   │   ├── security.mdc   # Agent requested - Security checklist
   │   └── git-workflow.mdc # Agent requested - Git conventions
   ├── commands/          # Plain markdown commands
   └── hooks.json         # Post-edit formatting hooks
   .cursorignore          # Files to exclude from Cursor context
   CLAUDE.md              # Team standards (Cursor reads this natively)

3. Installs Skills

   • Claude Code: External skills via npx add-skill
   • Codex: Bundled skills in .codex/skills/
   • Cursor: Bundled rules in .cursor/rules/

Feature Comparison

| Feature | Claude Code | Codex | Cursor | |---------|-------------|-------|--------| | Instructions file | CLAUDE.md | AGENTS.md | CLAUDE.md* | | Config format | JSON | TOML | JSON | | Rules/Skills format | SKILL.md | SKILL.md | .mdc (MDC) | | Hooks | Pre/Post tool use | Notify only | afterFileEdit | | MCP servers | .mcp.json | config.toml | N/A | | Permissions | Allowlist/denylist | Sandbox modes | N/A | | Rule application | /skill-name | $skill-name | globs/alwaysApply |

* Cursor also reads AGENTS.md

Cursor MDC Rules

Cursor uses MDC (Markdown with YAML frontmatter) format for rules:

---
description: TypeScript strict mode patterns
globs:
  - "**/*.ts"
  - "**/*.tsx"
alwaysApply: false
---

# TypeScript Patterns

Content here...

Rule Types

| Type | Configuration | Behavior | |------|---------------|----------| | Always Apply | alwaysApply: true, globs: [] | Active for all files | | Auto Attached | alwaysApply: false, globs: ["*.ts"] | Active when matching files open | | Agent Requested | alwaysApply: false, globs: [] | Agent decides when to use |

What You Get

Commands (Claude Code)

• /fix-issue <number> - Fix a GitHub issue with TDD workflow
• /review - Run code review checklist
• /clean-copy - Restructure commits into clean history
• /auto - Auto-detect best workflow

Rules (Cursor)

• tdd.mdc - TDD methodology (always apply)
• typescript.mdc - TypeScript patterns (auto-attach on .ts/.tsx)
• api-design.mdc - REST + Zod patterns (agent requested)
• security.mdc - Security checklist (agent requested)
• git-workflow.mdc - Git conventions (agent requested)

Skills (Both Claude Code & Codex)

• $api-design - REST + Zod patterns
• $security-review - Security audit checklist

Hooks

Claude Code:

• Auto-format: Prettier + ESLint on every edit
• Security: Blocks .env file modifications
• Intent routing: Suggests commands based on prompts

Cursor:

• Auto-format: Prettier + ESLint after file edit

Setup for Users

Configure npm to use GitHub Packages for the @acmeacmeio scope:

# Add to ~/.npmrc
@acmeacmeio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Then run:

npx @acmeacmeio/setup-sh my-project

Local Development

# Test locally without publishing
cd packages/setup-sh
node src/cli.mjs /path/to/test-project

# Or link globally
npm link
setup-sh /path/to/test-project

# Test specific agent
node src/cli.mjs /tmp/test --agent=cursor
node src/cli.mjs /tmp/test --agent=codex
node src/cli.mjs /tmp/test --agent=all

Customization

After running the command, customize:

Claude Code

1. CLAUDE.md - Edit team standards
2. .claude/settings.json - Adjust permissions and hooks
3. .claude/commands/ - Add custom slash commands
4. .claude/skills/ - Add domain-specific knowledge

Codex

1. AGENTS.md - Edit team standards
2. .codex/config.toml - Adjust model, sandbox, MCP servers
3. .codex/skills/ - Add domain-specific knowledge

Cursor

1. CLAUDE.md - Edit team standards (Cursor reads this natively)
2. .cursor/rules/ - Add custom MDC rules
3. .cursor/commands/ - Add custom commands
4. .cursor/hooks.json - Adjust post-edit hooks
5. .cursorignore - Exclude files from Cursor context

License

MIT