Metadata-Version: 2.4
Name: ecocode-cli
Version: 0.2.2
Summary: EcoCode — energy and performance profiler for source code (CLI core for the EcoCode VS Code extension)
Author: EcoCode Contributors
License: MIT
Project-URL: Homepage, https://github.com/LeonardLeroy/EcoCode
Project-URL: Repository, https://github.com/LeonardLeroy/EcoCode
Project-URL: Issues, https://github.com/LeonardLeroy/EcoCode/issues
Keywords: energy,sustainability,green-software,green-it,performance,profiling,optimization,carbon,ci
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# EcoCode

Try the VS Code extension on Marketplace: [EcoCode Insights](https://marketplace.visualstudio.com/items?itemName=ecocode.ecocode-vscode)

[![EcoCode Insights logo](https://raw.githubusercontent.com/LeonardLeroy/EcoCode/main/vscode-extension/media/Ecocode.png)](https://marketplace.visualstudio.com/items?itemName=ecocode.ecocode-vscode)

EcoCode is an open-source toolkit to measure the energy impact of your code, detect regressions, and guide more efficient optimizations.

## In action

Inline optimization suggestions (squiggles + code actions), a workspace dashboard, and honest "measured vs estimated" labels.

![Optimization suggestions and inline diagnostics](https://raw.githubusercontent.com/LeonardLeroy/EcoCode/main/vscode-extension/media/screenshots/suggestions.png)

![Workspace summary dashboard](https://raw.githubusercontent.com/LeonardLeroy/EcoCode/main/vscode-extension/media/screenshots/dashboard.png)

![Top files with measured/estimated badges](https://raw.githubusercontent.com/LeonardLeroy/EcoCode/main/vscode-extension/media/screenshots/top-files.png)

![Current file metrics](https://raw.githubusercontent.com/LeonardLeroy/EcoCode/main/vscode-extension/media/screenshots/current-file.png)

![Stability panel](https://raw.githubusercontent.com/LeonardLeroy/EcoCode/main/vscode-extension/media/screenshots/stability.png)

## Install

```bash
pipx install ecocode-cli
```

pipx installs the `ecocode` command on your PATH in an isolated environment (Python 3.10+). No pipx yet? `sudo apt install pipx` (Debian/Ubuntu) or `python3 -m pip install --user pipx`, then `pipx ensurepath`. Alternatively, install into a virtual environment: `python3 -m venv .venv && .venv/bin/pip install ecocode-cli`.

> On Debian/Ubuntu/WSL, a plain `pip install` into the system Python is blocked by PEP 668 — use pipx or a venv.

A few examples:

```bash
ecocode profile path/to/script.py            # profile a single file
ecocode profile-repo --root .                # scan a whole repository
ecocode optimize suggest path/to/script.py   # optimization suggestions
```

Prefer a GUI? Install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ecocode.ecocode-vscode) — it drives the same CLI.

## What this project is for?

EcoCode helps answer very practical questions:
- Is this script consuming more than before?
- Is a PR degrading performance and energy usage?
- Which files or code areas are the most expensive?
- Which optimizations should be prioritized first?

In practice, the CLI already lets you:
- profile a script (CPU, memory, estimated energy),
- create a baseline and compare future runs,
- scan an entire repository,
- track trends over time,
- generate optimization suggestions,
- export results for CI tooling (JSON/SARIF).

## Why it is useful?

The project makes an often invisible topic visible: the runtime cost of software.

In a team workflow, this makes it easier to:
- compare changes with real numbers instead of guesswork,
- catch energy regressions before they reach production,
- add energy checks to CI the same way we already gate tests and linting,
- improve performance and reliability without losing sight of sustainability.

## Where we are going?

The goal is to become a reference platform for sustainable software engineering:
- increasingly reliable, cross-platform runtime measurement,
- deeper repository analysis,
- smarter optimization recommendations,
- simpler integration into team workflows.

## AI suggestions are optional

EcoCode works fully offline with deterministic, rule-based suggestions — **no API key needed**. AI-powered suggestions are opt-in, configured in `ecocode.toml`:

- **Local (Ollama):** a model runs on your machine; your code never leaves it; no key. The endpoint is configurable via `ECOCODE_OLLAMA_BASE_URL` (HTTP or HTTPS).
- **Remote (Anthropic):** higher quality, but your source is sent to the API, so it needs **your own** key via the `ECOCODE_LLM_API_KEY` environment variable. The key is read **only** from the environment — never stored in `ecocode.toml`, VS Code settings, or the repository.

```bash
export ECOCODE_LLM_API_KEY="sk-ant-..."   # only needed for the remote provider
```

## Full documentation

If you want full details (commands, outputs, examples, roadmap, etc.), see the complete project documentation:

[documentation.md](documentation.md)

## Contributing

If the project interests you and you want to help:

You can:
- propose new features,
- add new functionality,
- fix potential issues and bugs,
- improve the app's reliability,
- submit pull requests.

See also:
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [docs/ROADMAP.md](docs/ROADMAP.md)
