📖 Table of Contents

• About the Project
• Key Features
• How It Works
• Prerequisites
• Installation
• Usage & Commands
• Configuration Settings
• Supported Languages
• Development & Contributing
• Troubleshooting & FAQ
• License

🚀 About the Project

CloudCost Lens brings financial accountability directly into your IDE. By acting like a linter for cloud and AI spending, it provides real-time, inline cost estimates and architectural optimization suggestions. It's built for modern developers who want to avoid surprise cloud bills, featuring integrations with top-tier AI models (including local, privacy-first models) and blockchain architecture for tamper-proof cost reporting.

✨ Key Features

• Real-Time Cost Estimates: Predicts the cost of infrastructure resources and AI API calls directly via CodeLens and inline editor gutter badges.
• Smart Optimizations (Apply Fix): Identifies expensive configurations in Terraform, Dockerfiles, and code, and uses integrated AI to suggest cheaper alternatives with a 1-click "Apply Fix".
• AI Model Flexibility: Connect to Google Gemini, OpenAI, Anthropic, OpenRouter, or run completely offline with Ollama (e.g., Llama 3) for zero-data-leakage analysis.
• Tamper-Proof Audit Trails: Leverage blockchain technology to anchor cost reports and PR cost diffs on-chain. Ideal for FinOps transparency and compliance.
• Full Project Audits: Calculate and view a comprehensive cost breakdown across the entire workspace in the dedicated visual sidebar.

🧠 How It Works

1. Parsing: The extension continuously monitors your active file and language environment.
2. Analysis: It detects infrastructure definitions, API calls, and usage parameters.
3. Execution: Queries your configured AI Engine and local Cost Engine to determine standard industry pricing.
4. Actionability: Renders warnings (turning red above your warningThreshold) and presents actionable optimizations.

🛠 Prerequisites

For Standard Use:

• Visual Studio Code v1.85.0 or higher.
• An API Key for your preferred AI provider (Gemini, OpenAI, Anthropic, or OpenRouter) OR a local instance of Ollama running on your machine.

For Development:

• Node.js: v18+
• npm: v9+ (comes with Node.js)

📦 Installation

From VS Code Marketplace (User)

1. Open Visual Studio Code.
2. Navigate to the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).
3. Search for CloudCost Lens and click Install.

Manual VSIX Installation

1. Download the latest .vsix file from the Releases tab.
2. Open VS Code, go to the Extensions view.
3. Click the ... (More Actions) in the top right.
4. Select Install from VSIX... and choose your downloaded file.

🕹 Usage & Commands

You can access CloudCost Lens via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) or via icons in the Editor and Sidebar.

⚙️ Configuration Settings

Customize how the extension behaves by modifying your settings.json or by using the VS Code Settings UI (search for CloudCost Lens).

General CloudCost Settings

• cloudcostlens.warningThreshold (Default: 50): Monthly cost ($/mo) above which inline decorations turn red.
• cloudcostlens.monthlyCallEstimate (Default: 50000): Estimated API calls per month, used to calculate multi-month savings.
• cloudcostlens.enableCodeLens (Default: true): Toggles inline CodeLens cost hints.
• cloudcostlens.enableGutterBadges (Default: true): Toggles inline cost decorations next to line numbers.

AI Model Integrations

• cloudcostlens.geminiApiKey: Recommended. Google Gemini API key. Leverage 1M free tokens/day.
• cloudcostlens.ollamaEndpoint (Default: http://localhost:11434): Local point for Ollama (Primary offline backend).
• cloudcostlens.ollamaModel (Default: llama3): Which Ollama model to invoke locally.
• cloudcostlens.openaiApiKey / cloudcostlens.anthropicApiKey: Set for using standard paid AI providers.
• cloudcostlens.openrouterApiKey: For OpenRouter fallback aggregation.

Advanced

• cloudcostlens.enableBlockchain (Default: true): Toggle tamper-proof cost-audit mechanisms.
• cloudcostlens.backendUrl (Default: http://localhost:3001): The CloudCost Lens backend API.
• cloudcostlens.projectId: Specific ID for grouping cloud cost reports.

🌍 Supported Languages

CloudCost lens automatically activates and builds insights for the following file extensions and languages:

• TypeScript & JavaScript (.ts, .tsx, .js, .jsx)
• Terraform (.tf)
• YAML (Kubernetes, Compose, CI/CD) (.yaml, .yml)
• Dockerfile
• Python (.py)
• JSON

🛠 Development & Contributing

Want to add a new AI provider or tweak the cost detection engine? Follow these steps to set up the development environment.

1. Setup the Repository

git clone https://github.com/cloudcostlens/vscode-extension.git
cd vscode-extension
npm install

2. Available Scripts

• npm run build : Bundles everything via ESBuild for production.
• npm run build:watch : Bundles and continuously watches for file changes.
• npm run compile : Runs the TypeScript compiler to catch logical errors.
• npm run package : Compiles and packages a new .vsix instance using VSCE.

3. Debugging Locally

1. Press F5 in Visual Studio Code.
2. A new "Extension Development Host" window will open.
3. Errors and Console logs will output to your primary VS Code debug console.

❓ Troubleshooting & FAQ

Q: My Inline Badges aren't appearing.
A: Ensure cloudcostlens.enableGutterBadges is true and that you have a supported file type open. Wait a few seconds for the analyzer to complete its execution.

Q: "AI Optimization failed" error?
A: Verify that you have configured at least ONE primary AI provider in settings (e.g., Gemini API Key or a matching Ollama configuration). If using Ollama, ensure the server is actively running (ollama serve).

Q: How does Blockchain Anchoring work?
A: The extension bundles your cost report hash and uses the configured Backend API to generate a verifiable transaction receipt. You can click 'Verify Report' at any time to parse the integrity of the data.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.