megaman

ENGLISH | 한국어 | 中文

megaman is a CLI for switching the primary context of coding agents by mode.

It is not just a rule-file switcher. It manages one active operating style at a time by applying the right AGENTS.md, rules, skills, and related context files for the current job.

The default command is megaman. A shorter alias, mg, is also available.

The Problem Megaman Solves

Teams often use coding agents in more than one way inside the same repository:

• onboarding and explanation
• debugging
• domain-specific work
• workflow-enforced setups such as obra/superpowers
• stricter process setups such as awslabs/aidlc-workflows

The problem is that one static AGENTS.md or one fixed ruleset is usually not enough. Different workflows can leak into each other, and manually rewriting agent-facing files is repetitive and error-prone.

megaman solves this by making context switching explicit, inspectable, and repeatable.

Before / After

Before megaman, different workflow files can accumulate in the same repository and shape the same primary agent context at the same time:

repo/
├── AGENTS.md  # awslabs/aidlc-workflows instructions for the main agent
├── .aidlc-rule-details/
│   ├── common/terminology.md
│   └── inception/workflow-planning.md  # detailed AIDLC workflow rules
├── .claude/skills/
│   ├── brainstorming/SKILL.md
│   └── systematic-debugging/SKILL.md  # Claude skills from obra/superpowers
└── .agents/skills/
    ├── brainstorming/SKILL.md
    └── systematic-debugging/SKILL.md  # Codex skills from obra/superpowers

In that state, the main agent can be influenced by both the AIDLC workflow files and the superpowers skill files at the same time. They can interfere with each other because they are all active in the same repository context.

With megaman, you apply one mode at a time and let it own the active context.

For example, if the repository is currently using megaman-context/aidlc-workflows, the active files look like this:

repo/
├── AGENTS.md  # awslabs/aidlc-workflows instructions for the main agent
└── .aidlc-rule-details/
    ├── common/terminology.md
    └── inception/workflow-planning.md  # detailed AIDLC workflow rules

If you then switch to megaman-context/superpowers:

megaman mode apply megaman-context/superpowers

After that switch, the old AIDLC snapshot is removed and the new superpowers snapshot is applied:

repo/
├── AGENTS.md  # instructions telling the main agent to use the superpowers workflow
├── .claude/skills/
│   ├── brainstorming/SKILL.md
│   └── systematic-debugging/SKILL.md  # Claude skills from megaman-context/superpowers
└── .agents/skills/
    ├── brainstorming/SKILL.md
    └── systematic-debugging/SKILL.md  # Codex skills from megaman-context/superpowers

AGENTS.md and .aidlc-rule-details/ are removed because they belonged to the previous megaman-context/aidlc-workflows snapshot, not the newly selected mode.

That is the core behavior: megaman does not try to mix workflow styles together. It keeps one active operating style in the repository at a time.

Get Started

The best way to understand megaman is to start with the onboarding mode and let your agent explain the system back to you.

npm install -g megaman-cli
cd <some-git-project>
megaman init
megaman sync megaman-context
megaman mode apply megaman-context/onboarding
# run your agent and prompt: "Hi" in your native language.
codex "Hi"

megaman init registers the default remote mode repository, so megaman-context is available after sync.

Strong recommendation:

• apply megaman-context/onboarding first
• run your agent immediately after apply
• ask it what megaman is, why it exists, and how to create and use modes

How It Works

megaman uses three context sources:

• built-in default
• local modes in .mega/modes/
• remote mode repositories registered in .mega/repos.yaml

Each mode is a source of truth for a set of projected files.

• local modes use .mega/modes/... as the source of truth
• remote modes use the synced repository cache as the source of truth
• projected files in the repository root are not the source of truth

Both apply and sync follow the same lifecycle:

1. remove the previous applied snapshot
2. materialize the selected mode from its source of truth
3. save the new applied snapshot in user-level state

This is true even when reapplying the same mode.

Quick CLI Flow

megaman init
megaman mode list
megaman mode show <mode-id>
megaman mode validate <mode-id>
megaman mode diff <mode-id>
megaman mode apply <mode-id>
megaman mode current

Sync commands:

megaman sync
megaman sync local
megaman sync <repository-name>

Repository commands:

megaman repo add <repository-name> <url>
megaman repo list
megaman repo remove <repository-name>

Writing mode.yaml

mode.yaml has a required description and an optional contexts list.

Example:

description: Onboarding context for explaining megaman.

contexts:
  - path: docs/aidlc-rules
    type: directory
    source: github
    ref: awslabs/aidlc-workflows/aidlc-rules?ref=main

  - path: docs/reference.md
    type: file
    source: httpfs
    ref: https://example.com/reference.md

Context fields:

• path: destination path relative to the git project root
• type: file or directory
• source: github or httpfs
• ref: source locator

GitHub refs use this format:

<owner>/<repo>/<path>?ref=<branch-or-tag>

Rules:

• the first segment is the GitHub owner
• the second segment is the repository name
• everything after that is the file path or directory path inside the repository
• httpfs supports type: file
• github supports type: file and type: directory

Repository Layout

After megaman init, the repository gets a .mega/ directory that defines local modes and remote mode sources:

.mega/
  repo-id
  modes/
    <mode-name>/
      mode.yaml
      AGENTS.md
      .cursor/rules/...
      .claude/skills/...
      .agents/skills/...
      docs/...
  repos.yaml

Meaning:

• repo-id: stable repository identity used by user-level state
• modes/: local mode definitions
• mode.yaml: metadata and external context references only
• everything else in a mode directory: projected into the repository root when the mode is applied
• repos.yaml: registered remote mode repositories

Default Remote Modes

megaman init seeds the repository with the default remote mode repository:

• megaman-context
• URL: https://github.com/moonchanyong/megaman-context

That repository currently includes example modes such as:

• megaman-context/onboarding
• megaman-context/aidlc-workflows
• megaman-context/superpowers

Runtime Storage

Runtime state and remote caches live outside the repository worktree.

State:

• macOS: ~/Library/Application Support/megaman/state/state.json
• Linux: ${XDG_STATE_HOME:-~/.local/state}/megaman/state.json
• Windows: %LOCALAPPDATA%\megaman\state\state.json

Remote cache:

• macOS: ~/Library/Caches/megaman/repos/
• Linux: ${XDG_CACHE_HOME:-~/.cache}/megaman/repos/
• Windows: %LOCALAPPDATA%\megaman\repos\

State is keyed by <repo-id>:<branch-ref>, so one repository can keep different active modes in different git worktrees.

megaman init seeds each workspace with a default baseline state:

• currentMode: "default"
• managedPaths: []
• appliedSnapshot: []

Safety Model

• managed paths can be replaced when switching modes
• unmanaged existing files cause a conflict and fail the command
• allowOverwrite is not part of the design
• default is the built-in baseline mode with no active context files

License

Apache-2.0. See LICENSE.

Development

• DESIGN.md: product design and behavior baseline
• RUNBOOK.md: local build and execution flow

For local development:

pnpm build
node dist/cli.js --help
node dist/cli.js mode list