What is flag-handler?

A coding helper for building Atmos command-line flags and registering new commands. Atmos is a tool for managing infrastructure configurations.

Use it when adding Atmos CLI commands, parsing flags, connecting commands to the command registry, or checking that the implementation follows the project’s flag rules.

It keeps flag handling consistent and prevents direct use of forbidden Viper calls outside the shared flags package.

How cloudposse/atmos configures Claude Code

About the project

Atmos is an infrastructure runtime that coordinates tools such as Terraform, OpenTofu, Kubernetes, Helm, Packer, Ansible, and containers through consistent commands and configuration. It is for teams running cloud infrastructure on laptops, in CI, or through AI agents across environments and regions. Its catalogue entries provide skills, agents, commands, and other add-ons for Atmos workflows.

cloudposse/atmos · 1,403 stars · on GitHub · atmos.tools

Reuse

Borrowing it

Nothing to install: this file belongs to cloudposse/atmos. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/cloudposse/atmos/main/.claude/agents/flag-handler.md

Clone the repo

git clone --depth 1 https://github.com/cloudposse/atmos

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/agents/cloudposse/atmos/flag-handler/github.svg)](https://agentmods.dev/agents/cloudposse/atmos/flag-handler)

Your own site

<a href="https://agentmods.dev/agents/cloudposse/atmos/flag-handler"><img src="https://agentmods.dev/badge/agents/cloudposse/atmos/flag-handler/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/agents/cloudposse/atmos/flag-handler"><img src="https://agentmods.dev/badge/agents/cloudposse/atmos/flag-handler.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 330 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.

When invoked 5,663 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00330	$0.05663
Opus 5.5	$0.00132	$0.02265
Sonnet 5.5	$0.00066	$0.01133
Haiku 4.5	$0.00033	$0.00566

Measured 1mo ago against content hash 5b5c82373444, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

flag-handler scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.claude/agents/flag-handler.md · 769 lines

How it starts

The opening of the file, as written. The whole thing — 769 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Flag Handler - Unified Flag Parsing Expert

Expert in Atmos command registry patterns and unified flag parsing architecture. Helps developers implement new CLI commands following CommandProvider interface and StandardParser patterns.

You are a specialized agent that helps developers implement new Atmos CLI commands using the unified flag parsing architecture and command registry pattern.

CRITICAL: pkg/flags/ is FULLY IMPLEMENTED

Current Architecture:

✅ pkg/flags/ package is fully implemented with 30+ files
✅ StandardParser, AtmosFlagParser are production-ready
✅ Unified flag parsing is actively used by all commands
✅ viper.BindEnv() and viper.BindPFlag() are BANNED outside pkg/flags/ (Forbidigo enforced)
✅ All commands MUST use flags.NewStandardParser()

When consulted, you MUST:

Enforce use of flags.NewStandardParser() for all flag handling
NEVER recommend calling viper.BindEnv() or viper.BindPFlag() directly
Direct developers to cmd/version/version.go for reference implementation
Verify Forbidigo will catch any direct Viper calls

Your Mission

Help developers create commands that:

Integrate with the command registry using CommandProvider interface
Use flags.NewStandardParser() for flag parsing with WithEnvVars() options
Register flags in init() with parser.RegisterFlags() and parser.BindToViper()
Parse flags in RunE with parser.BindFlagsToViper() and Viper getters
Follow the exact pattern from cmd/version/version.go

Workflow

Check PRD currency (do this first, every time)

git log -1 --format="%ai %s" docs/prd/flag-handling/unified-flag-parsing.md
cat docs/prd/flag-handling/unified-flag-parsing.md

Analyze requirements
- Read the command requirements
- Identify flags needed
- Determine if compatibility flags required
Choose implementation pattern
- Simple command (no flags): Use about.go pattern
- Command with flags: Use version.go pattern
- Command with pass-through: Add compatibility flags

Read the full file on GitHub · 769 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago First seen · 769 lines · 330 tokens per session scan A 5b5c82373444

Subscribe to this mod's changes

flag-handler is an agent published in the GitHub repository cloudposse/atmos (1,403 stars, last pushed today), licensed Apache-2.0. It adds 330 tokens to every session and 5,663 once invoked, about $0.0013 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Cloud DevOps and cloud Orchestration Planning automation cli hcl2

k8s-engineer

Kubernetes specialist for container orchestration, cluster management, and deployment strategies. Expert in GKE, EKS, manifest creation, Helm charts, operators, and Kubernetes best practices.

andisab/swe-marketplace · 42 tokens

aiox-qa

AIOX QA/Tester autônomo. Revisa stories, executa quality gates, security scans, test architecture. Usa task files reais com gate decision (PASS/CONCERNS/FAIL).

SynkraAI/aiox-core · 46 tokens

aiox-ux-design-expert

🎨 UX/UI Designer & Design System Architect (Uma). Complete design workflow - user research, wireframes, design systems, token extraction, component building, and quality assurance Activate with /aiox-ux-design-expert or spawnsubagent subagenttype="aiox-ux-design-expert".

SynkraAI/aiox-core · 68 tokens

atmos: Agent for Claude Code