Claude Code Setup

This document explains two paths to install and configure oh-my-aidlcops (OMA) in the Claude Code CLI environment. The native marketplace path is recommended; manual installation is used when the native path is unavailable due to offline environments, enterprise policies, or other constraints.

Prerequisites

Tool	Version	Installation
Claude Code CLI	latest stable	Official Installation Guide
bash	4+	brew install bash (macOS default 3.2 is outdated)
jq	1.6+	brew install jq or apt install jq
uv / uvx	latest	pipx install uv (required for MCP server execution)
git	2.30+	System defaults are acceptable for most environments

Method 1 · Native Marketplace Installation (only supported path)

On Claude Code 2.0+ the native marketplace is the only mechanism that exposes plugins in /plugin list. Launch Claude Code:

claude

Inside the Claude Code session, paste (or enter) the six lines below:

/plugin marketplace add https://github.com/aws-samples/sample-oh-my-aidlcops
/plugin install agentic-platform@oh-my-aidlcops
/plugin install agenticops@oh-my-aidlcops
/plugin install aidlc-inception@oh-my-aidlcops
/plugin install aidlc-construction@oh-my-aidlcops
/plugin install modernization@oh-my-aidlcops
/plugin list

To script the whole sequence from a shell one-liner use a here-doc:

claude <<'EOF'
/plugin marketplace add https://github.com/aws-samples/sample-oh-my-aidlcops
/plugin install agentic-platform@oh-my-aidlcops
/plugin install agenticops@oh-my-aidlcops
/plugin install aidlc-inception@oh-my-aidlcops
/plugin install aidlc-construction@oh-my-aidlcops
/plugin install modernization@oh-my-aidlcops
/plugin list
EOF

Expected /plugin list output:

> /plugin list
# agentic-platform     0.2.0-preview.1   enabled
# agenticops           0.2.0-preview.1   enabled
# aidlc-inception      0.2.0-preview.1   enabled
# aidlc-construction   0.2.0-preview.1   enabled
# modernization        0.2.0-preview.1   enabled

This path updates ~/.claude/installed_plugins.json and merges each plugin's .mcp.json and commands automatically.

Method 2 · Manual Script (legacy / auxiliary)

Claude Code 2.0+ will not load plugins from this path alone

scripts/install/claude.sh creates symlinks under ~/.claude/plugins/ and merges MCP servers + hooks into ~/.claude/settings.json. That was enough for Claude Code 1.x, but Claude Code 2.0+ treats ~/.claude/installed_plugins.json as ground truth. Running the script by itself leaves /plugin list empty. Use it only in the scenarios below.

scripts/install/claude.sh remains useful in three scenarios:

1. Legacy Claude Code 1.x — the symlink approach was the only install path there.
2. MCP / hooks only — merge OMA MCP servers + hooks into settings.json without registering the marketplace.
3. Offline CI — air-gapped environments where /plugin marketplace add cannot reach GitHub.

git clone https://github.com/aws-samples/sample-oh-my-aidlcops
cd oh-my-aidlcops
bash scripts/install/claude.sh

The script performs four steps (see install/claude.sh source for detailed behavior).

1. Plugin symlink — Symlinks each plugin directory to ~/.claude/plugins/<plugin>/.
2. Command symlink — Symlinks steering/commands/oma/ to ~/.claude/commands/oma/, exposing /oma:* slash commands.
3. MCP server merge — Non-destructively merges the mcpServers object from each plugin's .mcp.json into the top-level mcpServers key in ~/.claude/settings.json.
4. Hook registration — Registers hooks/user-prompt-submit.sh and hooks/session-start.sh in ~/.claude/settings.json's hooks section.

The script is idempotent. Re-running preserves existing symlinks and creates only missing items.

Environment Variables

Variable	Default	Description
OMA_OWNER	aws-samples	Marketplace GitHub owner
CLAUDE_HOME	$HOME/.claude	Claude Code installation directory

settings.json Merge Details

OMA's installation script does not overwrite existing settings.json. It uses jq to partially merge only two sections.

mcpServers Merge Rules

Existing keys are preserved; only new keys are added.

{
  "mcpServers": {
    "my-custom-server": { "command": "..." },
    "eks-mcp-server": { "command": "uvx", "args": ["awslabs.eks-mcp-server"] },
    "cloudwatch-mcp-server": { "command": "uvx", "args": ["awslabs.cloudwatch-mcp-server"] }
  }
}

In the example above, my-custom-server (existing key) is preserved, and the 11 hosted MCP servers that OMA adds are inserted as new keys. On key collision, the existing value takes precedence.

The list of MCP servers targeted for merge is defined in section 3 of NOTICE.

hooks Registration Rules

UserPromptSubmit and SessionStart hooks are added with the following structure.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "/path/to/oh-my-aidlcops/hooks/user-prompt-submit.sh" }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "/path/to/oh-my-aidlcops/hooks/session-start.sh" }
        ]
      }
    ]
  }
}

Existing hooks are preserved. The installation script checks whether the same command path is already registered and avoids creating duplicates.

Hooks serve these roles:

• SessionStart — Loads .omao/triggers.json, detects active Tier-0 mode, and injects OMA state into session context.
• UserPromptSubmit — Detects keyword triggers in user input and suggests matching /oma:<workflow> commands. See Keyword Triggers for details.

Project Initialization

Installation happens at the user's home directory level, but actual work lives in .omao/ at the project root. If you ran oma setup, this is already done — no manual call needed.

To initialize manually without the full setup wizard:

cd <your-project>
oma init

This command creates .omao/plans/, .omao/state/, .omao/notepad.md, .omao/triggers.json, and .omao/project-memory.json. You do not need to know the install path — use oma where if you do.

.omao/ is harness-agnostic, so state remains consistent even if you alternate between Claude Code and Kiro in the same project.

AIDLC Extensions (opt-in)

The aidlc-inception and aidlc-construction plugins follow the opt-in extension structure of awslabs/aidlc-workflows. To activate extensions, run:

bash scripts/install/aidlc-extensions.sh

The script clones awslabs/aidlc-workflows to ~/.aidlc and symlinks OMA's *.opt-in.md files into that repository's extension directory. OMA does not copy or modify core workflow files; it contributes extensions only (see section 2 of NOTICE for details).

Installation Verification

All three commands below must work normally for installation to be complete.

# 1. Verify plugin active status
> /plugin list

# 2. Verify slash command autocomplete
> /oma:
# autopilot, aidlc-loop, inception, construction, agenticops, self-improving,
# platform-bootstrap, review, cancel must all be shown.

# 3. Verify MCP server connections
> /mcp
# 11 AWS hosted MCP servers must be listed.

Troubleshooting

/plugin marketplace add fails

This occurs when Claude Code version is outdated.

claude --version
# Upgrade to latest stable: https://docs.anthropic.com/claude/docs/claude-code

jq: command not found

The installation script uses jq for JSON merge.

# macOS
brew install jq
# Debian/Ubuntu
sudo apt-get install -y jq

/oma:* commands not displayed

The ~/.claude/commands/oma/ symlink may not have been created.

ls -la ~/.claude/commands/oma/
# If it is a stale symlink, remove and reinstall
rm ~/.claude/commands/oma
bash ~/.oma/scripts/install/claude.sh

MCP server connection fails (uvx not found)

AWS hosted MCP servers run via uvx stdio.

pipx install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

# After installation
uvx --version

Hook does not execute

Verify that hooks are registered in ~/.claude/settings.json.

jq '.hooks' ~/.claude/settings.json
# Both UserPromptSubmit and SessionStart events must be present.

Also verify that hook files have execute permissions.

chmod +x ~/.oma/hooks/user-prompt-submit.sh
chmod +x ~/.oma/hooks/session-start.sh

Checkpoint stuck waiting

This may be a permission issue with .omao/state/ directory.

ls -la .omao/state/
# If write permission is missing
chmod -R u+w .omao/

Uninstalling plugins

For native marketplace installation:

> /plugin uninstall agentic-platform agenticops aidlc-inception aidlc-construction
> /plugin marketplace remove oh-my-aidlcops

For manual installation, remove symlinks and manually delete relevant entries from settings.json.

rm ~/.claude/plugins/agentic-platform ~/.claude/plugins/agenticops \
   ~/.claude/plugins/aidlc-inception ~/.claude/plugins/aidlc-construction
rm ~/.claude/commands/oma
# Manually clean OMA entries from mcpServers and hooks in ~/.claude/settings.json

Reference Materials

Official Documentation

• Claude Code CLI — Official Claude Code guide
• Claude Code Plugins — Plugin structure standards
• awslabs/mcp — Catalog of MCP servers to merge
• jq Manual — Reference for direct settings.json editing

OMA Internal Documentation

• Getting Started — 5-minute Quickstart
• Kiro Setup — Kiro environment installation
• Keyword Triggers — Hook-based automatic command invocation
• Tier-0 Workflows — Detailed command reference after installation