Skip to content

README.md

Latest commit

 

History

History
399 lines (318 loc) · 10.7 KB

README.md

File metadata and controls

399 lines (318 loc) · 10.7 KB

SuperFlag

Claude Code NPM TypeScript

Note: This project was inspired by the pioneering work in SuperClaude Framework and SuperGemini Framework. Special thanks to SuperClaude-Org team members @NomenAK and @mithun50 whose work made this possible.

SuperFlag provides 21 contextual flags that guide AI assistant behavior through precise directives. It exposes an MCP stdio server for seamless integration with modern AI development tools.

Quick Start

# Install globally
npm install -g @superclaude-org/superflag

# Interactive installation (choose platforms)
superflag install

# Direct installation for Claude Code
superflag install cc

Then use flags in your AI assistant:

  • "Fix this bug --analyze --strict"
  • "Refactor --auto" (auto-select optimal flags)
  • "--save" (create handoff documentation)
  • "Run with 3 agents --team-3"

21 Available Flags

Analysis & Optimization

Flag Purpose
--analyze Multi-perspective evidence-based analysis with 3+ independent perspectives
--performance Measure-first optimization with baseline metrics and ROI calculation
--refactor Safe atomic refactoring with continuous test verification
--strict Zero-error transparent execution with verify-before-claim
--lean Minimal resource-efficient implementation eliminating waste

Discovery & Documentation

Flag Purpose
--discover Research-first solution selection with 3+ alternatives comparison
--explain Progressive domain-expert disclosure from overview to details
--save Document development context for seamless continuation
--load Load and verify handoff context against git reality

Workflow Management

Flag Purpose
--team Multi-agent coordination with optional count (--team-N)
--skill Context-aware skill invocation — auto-selects appropriate skill
--todo Scope-locked task tracking with real-time progress
--seq Dependency-ordered sequential execution with checkpoints
--collab Evidence-anchored peer collaboration with quantitative validation

Output Control

Flag Purpose
--concise Precise professional content prioritizing accuracy over brevity
--git Anonymous atomic commits with ASCII-only WHY-focused messages
--readonly Analysis-only mode with absolute no-modification guarantee

Execution Discipline

Flag Purpose
--integrity Verification-before-claim with evidence for every assertion
--evolve Monotonic forward improvement with regression prevention

Meta Control

Flag Purpose
--reset Clear session and force fresh directives
--auto Grant autonomous flag selection authority

Installation

Prerequisites

  • Node.js 16+
  • Target platform installed (Claude Code, Gemini CLI, or Continue)

Quick Setup (All Platforms)

# Install package globally
npm install -g @superclaude-org/superflag

# Interactive installation - choose your platforms
superflag install

The interactive installer will:

  • Detect installed platforms
  • Let you select which ones to configure
  • Automatically register MCP servers for all platforms
  • Set up configuration files and flag detection

Platform-Specific Installation

Claude Code

# Direct installation (MCP server auto-registered)
superflag install cc

# Verify connection
claude mcp list

Creates:

  • ~/.claude/CLAUDE.md - References @SUPERFLAG.md
  • ~/.claude/SUPERFLAG.md - Flag instructions
  • ~/.claude/hooks/superflag.py - Flag detection hook

Manual MCP Registration (if auto-registration fails):

# Add MCP server manually
claude mcp add superflag npx @superclaude-org/superflag@latest -s user

# Or add to ~/.claude.json
{
  "mcpServers": {
    "superflag": {
      "command": "npx",
      "args": ["@superclaude-org/superflag@latest"],
      "env": {}
    }
  }
}

Gemini CLI

# Direct installation (MCP server auto-registered)
superflag install gemini

Creates:

  • ~/.gemini/GEMINI.md - References @SUPERFLAG.md
  • ~/.gemini/SUPERFLAG.md - Flag instructions

Manual MCP Registration (if auto-registration fails):

// Edit ~/.gemini/settings.json
{
  "mcpServers": {
    "superflag": {
      "type": "stdio",
      "command": "npx",
      "args": ["@superclaude-org/superflag@latest"],
      "env": {}
    }
  }
}

Continue (VS Code Extension)

# Direct installation (MCP server auto-registered)
superflag install cn

Creates:

  • ~/.continue/config.yaml - SuperFlag rules
  • ~/.continue/mcpServers/superflag.yaml - MCP server configuration

Manual MCP Registration (if auto-registration fails):

# Create ~/.continue/mcpServers/superflag.yaml
name: SuperFlag
command: npx
args:
  - '@superclaude-org/superflag@latest'
env: {}

Batch Installation

# Install for all supported platforms
superflag install all

# Install for specific combinations
superflag install cc gemini  # Claude Code + Gemini CLI
superflag install cn         # Continue only

Usage

Natural Language with Flags

All platforms support using flags in natural conversation:

# Auto mode - AI selects appropriate flags
"Optimize this code --auto"

# Specific flag combinations
"--analyze --strict"       # Thorough analysis with zero-error enforcement
"--save --explain"         # Create documentation with detailed explanations
"--reset --todo"           # Reset session and start task tracking
"--team-3 --todo"          # Multi-agent work with 3 agents + task tracking

# Parametric flags
"--team-5"                 # Spawn 5 role-specialized agents
"--team"                   # Auto-determine team size from task complexity

Platform-Specific Usage

Claude Code

# Direct chat with flags
"Fix this bug --analyze --strict"
"Create documentation --save --explain"

# MCP tool access (advanced)
get_directives(['--flag1', '--flag2'])

Gemini CLI

# Chat with flags
"Refactor this code --auto --performance"

# MCP server commands
@superflag --analyze --todo

Continue (VS Code)

# In Continue chat
"Optimize this function --performance --lean"

# Use @ to access MCP tools
@get_directives(['--strict', '--analyze'])

Session Management

  • Duplicate Detection: Repeated flags show brief reminders instead of full directives
  • Session Reset: Use --reset when switching tasks or contexts
  • Persistence: Flag states persist through /clear or /compact - use --reset to reinitialize

The --auto Flag

--auto enables intelligent flag selection:

Usage Behavior
--auto only AI selects complete flag set automatically
--auto --strict --analyze AI applies specified flags + may add others
--strict --analyze Only specified flags, no auto-selection

Note: Do not include --auto in direct get_directives() calls - it's for natural language use only.

Configuration Files

Claude Code

~/.claude/
├── CLAUDE.md                    # References @SUPERFLAG.md
├── SUPERFLAG.md                 # Flag instructions
└── hooks/
    └── superflag.py             # Flag detection hook

Gemini CLI

~/.gemini/
├── GEMINI.md                    # References @SUPERFLAG.md
├── SUPERFLAG.md                 # Flag instructions
└── settings.json                # MCP server configuration (auto-registered)

Continue

~/.continue/
├── config.yaml                  # SuperFlag rules and configuration
└── mcpServers/
    └── superflag.yaml           # MCP server settings (auto-registered)

Shared Configuration

~/.superflag/
└── flags.yaml                  # Flag definitions and directives (all platforms)

Development

Local Development

# Clone repository
git clone https://github.com/SuperClaude-Org/SuperFlag_Framework.git
cd SuperFlag_Framework

# Install dependencies
npm install

# Build TypeScript
npm run build

# Test locally
npm link
superflag --version

Version Management

Update version in src/version.ts - all other files sync automatically during build.

Project Structure

  • flags.yaml - All 21 flag definitions and directives (3-Layer architecture)
  • SUPERFLAG.md - Flag instructions installed to user config directories
  • src/server.ts - MCP stdio server
  • src/install.ts - Interactive installer/uninstaller
  • src/directives.ts - Flag parsing from flags.yaml

Uninstallation

Interactive Uninstallation

# Interactive removal - choose platforms to remove
superflag uninstall

Platform-Specific Removal

# Remove from specific platforms
superflag uninstall cc          # Claude Code only
superflag uninstall gemini      # Gemini CLI only
superflag uninstall cn          # Continue only
superflag uninstall all         # All platforms

Complete Removal

# Remove all configurations and package
superflag uninstall all
npm uninstall -g @superclaude-org/superflag

Safety Features:

  • Configuration files are backed up before removal
  • Interactive confirmation for each platform
  • Selective removal - keep other platforms intact

Troubleshooting

Common Issues

Auto-Registration Failed If MCP server wasn't automatically registered during installation:

# For Claude Code
claude mcp add superflag npx @superclaude-org/superflag@latest -s user

# For Gemini CLI - manually edit ~/.gemini/settings.json
{
  "mcpServers": {
    "superflag": {
      "type": "stdio",
      "command": "npx",
      "args": ["@superclaude-org/superflag@latest"],
      "env": {}
    }
  }
}

# For Continue - create ~/.continue/mcpServers/superflag.yaml
name: SuperFlag
command: npx
args:
  - '@superclaude-org/superflag@latest'
env: {}

MCP Connection Issues

# Check server status (Claude Code)
claude mcp list

# Re-register if needed
claude mcp remove superflag
superflag install cc  # Auto-register again

Flags Not Working

  • Restart your AI platform after installation
  • Verify configuration files exist:
    • Claude Code: ~/.claude/SUPERFLAG.md
    • Gemini CLI: ~/.gemini/SUPERFLAG.md
    • Continue: ~/.continue/config.yaml
  • Check MCP server connection (platform-specific)

License

MIT

Need Help? File issues at: GitHub Repository