{"id":51017984,"url":"https://github.com/agenticdevops/aws-finops-agent","last_synced_at":"2026-06-21T13:30:33.975Z","repository":{"id":352570013,"uuid":"1215618140","full_name":"agenticdevops/aws-finops-agent","owner":"agenticdevops","description":"AWS FinOps Agent with Claude and Hermes","archived":false,"fork":false,"pushed_at":"2026-04-20T06:32:35.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T08:28:19.649Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agenticdevops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T05:05:32.000Z","updated_at":"2026-04-20T06:32:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agenticdevops/aws-finops-agent","commit_stats":null,"previous_names":["agenticdevops/aws-finops-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/agenticdevops/aws-finops-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticdevops%2Faws-finops-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticdevops%2Faws-finops-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticdevops%2Faws-finops-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticdevops%2Faws-finops-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agenticdevops","download_url":"https://codeload.github.com/agenticdevops/aws-finops-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticdevops%2Faws-finops-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34610832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-21T13:30:33.133Z","updated_at":"2026-06-21T13:30:33.968Z","avatar_url":"https://github.com/agenticdevops.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS FinOps Agent\n\nWeekly AWS FinOps agent that scans multi-account environments, identifies cost optimization opportunities, and generates comprehensive HTML dashboard reports.\n\nTwo parallel runtimes:\n- **Hermes Agent** — local, cron-scheduled, dedicated profile with guardrails\n- **Claude Routine** — Anthropic cloud, zero maintenance\n\n## Features\n\n- **8-section HTML dashboard**: cost overview, waste detection, rightsizing, RI/SP utilization, S3 optimization, budget status, Trusted Advisor, prioritized recommendations\n- **Hybrid tooling**: MCP server for structured cost/audit data + AWS CLI for full coverage\n- **Multi-account**: iterates all AWS CLI profiles in `~/.aws/credentials`\n- **Delivery**: S3 upload + Slack notification with pre-signed URL\n- **Read-only**: zero destructive AWS operations, enforced at IAM + guardrail level\n- **Dedicated Hermes profile**: isolated config, SOUL, guardrails — doesn't pollute your main agent\n- **Dark/light theme**, responsive, print-friendly reports\n\n## Quick Start (Hermes)\n\n### Prerequisites\n\n- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed\n- AWS CLI configured with at least one profile\n- `ANTHROPIC_API_KEY` set in `~/.hermes/.env`\n- `uv` installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)\n\n### 1. Clone\n\n```bash\ngit clone https://github.com/agenticdevops/aws-finops-agent.git\ncd aws-finops-agent\n```\n\n### 2. Install MCP Server (optional)\n\nThe [aws-finops-mcp-server](https://github.com/ravikiranvm/aws-finops-mcp-server) provides structured cost/audit data via MCP. The agent works without it (falls back to AWS CLI), but MCP gives cleaner data for cost overview and basic waste detection.\n\n```bash\ngit clone https://github.com/ravikiranvm/aws-finops-mcp-server.git\ncd aws-finops-mcp-server \u0026\u0026 uv sync \u0026\u0026 cd ..\n```\n\n### 3. Install Skills (global)\n\nCopy skills to Hermes global skills directory:\n\n```bash\ncp -r hermes/skills/aws-finops-audit ~/.hermes/skills/devops/\ncp -r hermes/skills/aws-cost-analysis ~/.hermes/skills/devops/\ncp -r hermes/skills/aws-report-gen ~/.hermes/skills/devops/\n```\n\nSkills are now auto-discovered by all Hermes profiles.\n\n### 4. Create Dedicated Profile\n\n```bash\nmkdir -p ~/.hermes/profiles/finops\ncp hermes/SOUL.md ~/.hermes/profiles/finops/SOUL.md\ncp hermes/config.yaml ~/.hermes/profiles/finops/config.yaml\n```\n\nEdit `~/.hermes/profiles/finops/config.yaml` and update the MCP server path:\n\n```yaml\nmcp_servers:\n  aws-finops:\n    command: \"/full/path/to/uv\"    # Run: which uv\n    args: [\"run\", \"--directory\", \"/full/path/to/aws-finops-agent/aws-finops-mcp-server\",\n           \"python\", \"-m\", \"aws_finops_mcp_server.main\"]\n    timeout: 120\n    connect_timeout: 30\n```\n\n### 5. Run Interactively\n\n```bash\nhermes -p finops\n# Ask: \"Run a FinOps audit on my AWS accounts\"\n```\n\nYour main `hermes` agent remains untouched.\n\n### 6. Schedule Weekly\n\n```bash\nhermes -p finops cron create --name \"aws-finops-weekly\" \\\n  --skill aws-finops-audit \\\n  --skill aws-cost-analysis \\\n  --skill aws-report-gen \\\n  \"0 9 * * 1\" \\\n  \"Run a complete FinOps audit. Follow shared/prompt.md instructions.\"\n```\n\nVerify:\n```bash\nhermes -p finops cron list\n```\n\nNote: cron jobs require `hermes gateway install` to auto-fire when your machine is on.\n\n## Project Structure\n\n```\naws-finops-agent/\n├── shared/                          # Shared artifacts (both runtimes)\n│   ├── prompt.md                    # Master agent prompt\n│   ├── report-template.html         # HTML dashboard template\n│   ├── iam-policy.json              # Least-privilege IAM policy\n│   └── slack-notify.sh              # S3 upload + Slack webhook\n├── hermes/                          # Hermes Agent runtime\n│   ├── config.yaml                  # Profile config (copy to ~/.hermes/profiles/finops/)\n│   ├── SOUL.md                      # Agent persona (copy to ~/.hermes/profiles/finops/)\n│   └── skills/                      # Hermes skills (copy to ~/.hermes/skills/devops/)\n│       ├── aws-finops-audit/        # Waste detection\n│       ├── aws-cost-analysis/       # Cost analysis + optimization\n│       └── aws-report-gen/          # Report rendering + delivery\n├── routines/                        # Claude Routine runtime\n│   ├── routine-config.json          # Routine definition\n│   └── setup.sh                     # Setup guide\n└── docs/superpowers/                # Design spec + implementation plan\n# aws-finops-mcp-server/            # Optional — clone separately (see step 2)\n```\n\n## Agent Profile\n\nThe FinOps agent runs as a dedicated Hermes profile (`finops`), isolated from your main agent.\n\n| Component | Repo File | Installed Location |\n|-----------|-----------|-------------------|\n| **Persona** | `hermes/SOUL.md` | `~/.hermes/profiles/finops/SOUL.md` |\n| **Config** | `hermes/config.yaml` | `~/.hermes/profiles/finops/config.yaml` |\n| **Audit Skill** | `hermes/skills/aws-finops-audit/SKILL.md` | `~/.hermes/skills/devops/aws-finops-audit/` |\n| **Cost Skill** | `hermes/skills/aws-cost-analysis/SKILL.md` | `~/.hermes/skills/devops/aws-cost-analysis/` |\n| **Report Skill** | `hermes/skills/aws-report-gen/SKILL.md` | `~/.hermes/skills/devops/aws-report-gen/` |\n| **Master Prompt** | `shared/prompt.md` | Referenced at runtime from project dir |\n| **IAM Policy** | `shared/iam-policy.json` | Applied to AWS IAM users/roles |\n| **Guardrails** | `hermes/config.yaml` | Smart approval + 11 auto-approve patterns for reads |\n\n### Profile Isolation\n\n```bash\nhermes                # Your main agent (unchanged)\nhermes -p finops      # FinOps specialist (own SOUL, config, guardrails, memory)\nhermes -p finops cron list   # FinOps cron jobs only\n```\n\nEach profile gets its own:\n- `SOUL.md` (persona)\n- `config.yaml` (model, MCP, guardrails)\n- Memory and session history\n- Cron jobs\n\n## Report Sections\n\n1. **Executive Summary** — health score, total spend, top savings opportunities\n2. **Cost Overview** — spend by service/region/account, daily burn rate\n3. **Waste Detection** — stopped EC2, orphaned EBS, idle RDS, unused ELBs, NAT Gateways, unused SGs\n4. **Rightsizing** — EC2 instance type recommendations\n5. **RI \u0026 Savings Plans** — utilization %, coverage gaps, expiring commitments\n6. **S3 \u0026 Storage** — buckets without lifecycle policies, storage class optimization\n7. **Budget Status** — budget vs actual vs forecast\n8. **Recommendations** — prioritized by savings, with effort and risk ratings\n\n## Security\n\nAll operations are read-only. Security enforced at three layers:\n\n1. **IAM Policy** (`shared/iam-policy.json`) — 29 read-only actions + scoped S3 write\n2. **Agent Prompt** (`shared/prompt.md`) — explicit safety rules in every instruction\n3. **Hermes Guardrails** (`hermes/config.yaml`) — smart approval blocks destructive commands, auto-approves reads\n\nBlocked commands: `delete-*`, `terminate-*`, `stop-*`, `modify-*`, `aws iam *`, `aws organizations *`, `aws sts assume-role`, `rm -rf`, `sudo`, `curl | bash`.\n\n## S3 + Slack Delivery\n\nSet environment variables (in `~/.hermes/profiles/finops/.env` or shell):\n\n```bash\nexport S3_REPORT_BUCKET=my-finops-reports\nexport SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx\n```\n\nThe agent uploads the HTML report to `s3://bucket/finops/YYYY-MM-DD.html`, generates a 7-day pre-signed URL, and posts to Slack.\n\n## Claude Routine (Cloud)\n\nFor cloud-hosted execution without a local machine:\n\n1. Edit `routines/routine-config.json` — replace all `REPLACE_WITH_*` placeholders\n2. Run `routines/setup.sh` for guided setup\n3. Or use Claude Code: `/schedule` to create the routine\n\nNote: Claude Routines run in isolated cloud VMs. AWS credentials are passed as environment variables (not `~/.aws/credentials`). For multi-account, either create one routine per account or use cross-account IAM roles.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenticdevops%2Faws-finops-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagenticdevops%2Faws-finops-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenticdevops%2Faws-finops-agent/lists"}