|
|
HealCode is an AI-powered developer diagnostics CLI platform designed to scan local development environments, containers, cloud contexts, project setups, and source code files to identify configuration drift, performance anti-patterns, and security smells.
Instead of juggling separate tools for Docker linting, Kubernetes context checks, dependency auditing, and static analysis, HealCode runs a single scan across all of them and rolls the results into one weighted health score — so you always know exactly where your project stands.
| Scans | Local env, Docker/Compose, Kubernetes, cloud CLIs, source code |
| Languages covered | Node.js, Python, Java, Go, Rust, Flutter |
| Scoring | Weighted health score across 40+ categories |
| AI layer | Optional, offline-first — zero cloud dependency required |
| Install | pip install healcode |
| Requires | Python ≥ 3.11 |
Most projects don't break because of one big, obvious bug. They break because of small things nobody noticed in time.
A password or secret key accidentally gets saved into a file that shouldn't have it. A cloud setting quietly points to the wrong place. A container is missing a setting that would've restarted it if it crashed. A piece of code slowly gets more complicated over time until nobody wants to touch it anymore. None of these show up when you check git status — they show up later, as a bug, a security scare, or a late-night emergency fix.
| ❌ Without HealCode |
|---|
| 🔑 Secret keys or passwords accidentally get saved into your code |
| 🐳 Container settings are wrong, but nobody notices until something crashes |
| ☸️ Cloud/Kubernetes settings quietly point to the wrong environment |
| 🧮 Code slowly becomes messy and hard to understand, without anyone realizing |
| 🧰 Your tools (Python, Node.js, etc.) get out of sync with what the project actually needs |
| 📉 There's no record of what changed in your setup over time, or when |
There are separate tools that can catch each of these problems on their own — but most developers don't have the time to set up and run five different tools, on every project, every time.
HealCode checks all of this for you — your computer, your containers, your cloud settings, your code — with one simple command: healcode scan. Instead of five different tools giving you five different reports, you get one clear health score for your whole project.
| ✅ What HealCode Does Differently |
|---|
| 🔍 One command checks everything — your system, containers, cloud setup, tools, and code, all at once |
| 📈 One easy score — instead of piecing together results from five different tools |
| 🗃️ Remembers what changed — compare today's check against last week's to see exactly what's different |
| 🧠 Smart help, without needing the internet — an optional AI feature that groups problems together and tells you what to fix first, fully offline |
| ⏱️ Keeps checking as you work — turn on watch mode and it rechecks automatically while you code |
HealCode isn't trying to replace your linter or your secret scanner — it brings together what all of those tools would tell you, in one place, and also tracks what's changed since your last check — something none of them do on their own.
| Who | Why it helps them |
|---|---|
| 👨💻 Solo developers | Catch mistakes and exposed passwords before you share your code — without setting up five separate tools yourself. |
| 🧑🤝🧑 Small teams | Everyone uses the same settings file, so the whole team's projects get checked the same way. |
| 🏢 DevOps / Infrastructure folks | Use the DevOps profile to focus on containers, cloud setup, and configuration drift specifically. |
| 🔐 Security-minded teams | Use the Security profile to prioritize exposed secrets and risky settings first. |
| 🎓 Students & beginners | See, in one simple report, what a "healthy" project setup actually looks like — a great way to learn good habits early. |
You could piece together the same coverage using several separate tools — but here's what that actually looks like side by side.
| What you need to check | Doing it manually | With HealCode |
|---|---|---|
| 🔑 Exposed secrets in code | Set up a separate secret-scanning tool | Included in healcode scan |
| 🐳 Docker/Compose misconfigurations | Read through Dockerfiles and compose files by hand | Included in healcode scan |
| ☸️ Kubernetes context drift | Manually check kubectl config before every deploy |
Included in healcode scan |
| 🧰 Toolchain version mismatches | Cross-check manifests against installed versions yourself | Included in healcode scan |
| 🧮 Code complexity issues | Run a separate static analysis tool per language | Included in healcode scan |
| 📊 One overall health picture | Manually combine results from every tool above | One weighted score, automatically |
| 🗃️ Tracking what changed over time | No built-in way — you'd have to remember or log it yourself | healcode baseline tracks it for you |
| ⏱️ Continuous checking while coding | Re-run each tool manually, every time | healcode watch does it automatically |
The individual checks above already exist as separate tools. What HealCode adds is running them together, scoring them together, and remembering what changed — so you're not stitching five reports into one picture yourself.
When you run healcode scan, here's what happens behind the scenes — all in one go:
healcode scan
│
▼
┌─────────────────────────┐
│ Runs all the checks │
└─────────────────────────┘
│
┌───────────┬──────┼───────┬────────────┐
▼ ▼ ▼ ▼
Your Containers Cloud & Your Tools
Computer (Docker) Cloud Setup (Python, Node.js, etc.)
│
▼
Your Code
(looks for messy
or risky code)
│ │ │ │
└────────────┴──────┬──────┴─────────────┘
▼
┌───────────────────┐
│ Adds it all up │
│ into one score │
└───────────────────┘
│
┌──────────┴──────────┐
▼ ▼
Health Report Saves a record
(what passed, (so you can compare
what needs it to next time)
attention)
│
▼
Optional: AI groups the
problems and tells you
what to fix first
💡 Want the deeper technical breakdown? See Architecture in the docs hub.
Run healcode scan and get a full environment health report in seconds — no config required.
[1;36mHEALCODE DIAGNOSTICS ENGINE v1.0.0[0m
[1;35m════════════════════════════════════════════════════[0m
[1;34m▸ SYSTEM[0m
[1;32m [✓] OS & shell environment healthy[0m
[1;32m [✓] Disk space sufficient (62% free)[0m
[1;34m▸ CONTAINERS[0m
[1;32m [✓] Docker daemon running (v24.0.7)[0m
[1;33m [!] docker-compose.yml missing restart policy on 'api' service[0m
[1;34m▸ CLOUD & KUBERNETES[0m
[1;33m [!] Kubernetes context using default namespace instead of dev-active[0m
[1;32m [✓] AWS CLI credentials valid[0m
[1;34m▸ RUNTIME & TOOLCHAINS[0m
[1;32m [✓] Node.js v20.11.0 matches package.json engine constraint[0m
[1;31m [✗] Python 3.9 installed — pyproject.toml requires >=3.11[0m
[1;34m▸ STATIC CODE ANALYSIS[0m
[1;33m [!] High cyclomatic complexity in utils/parser.py (score: 24)[0m
[1;31m [✗] Found 1 exposed API key in config/settings.py:L14[0m
[1;35m════════════════════════════════════════════════════[0m
[1;36mOVERALL ENVIRONMENT HEALTH:[0m [[1;32m######################----[0m] [1;32m88.5%[0m
[1;32m3 passed[0m · [1;33m2 warnings[0m · [1;31m2 critical[0m
| Symbol | Meaning |
|---|---|
| ✅ | Passed — no action needed |
| Warning — worth reviewing | |
| ❌ | Critical — should be fixed before shipping |
-
🧠 AI-Powered Diagnostics: Optional AI orchestration layer delivering root-cause grouping, prioritization scoring, and repair recommendations with zero cloud dependencies.
-
📦 Docker & Compose Auditing: Checks engine version info, Context configurations, Dockerfile security practices, and docker-compose restart structures.
-
☁️ Cloud & Kubernetes Contexts: Scans local AWS, GCP, and Azure CLI setups, evaluates kubeconfig context validity, and identifies local Terraform variables.
-
⚙️ Runtime & Compiler Intelligence: Detects Node.js, Python, Java, Go, Rust, and Flutter toolchains, matching compiler versions against manifest constraints.
-
🔍 Universal Static Code Analysis: Computes cyclomatic complexity, nesting depths, and nested loop performance bottlenecks across languages.
-
📈 Weighted Health Scoring: Rates codebase health across 40+ granular categories.
-
🗃️ Baseline & Drift Detection: Captures environmental snapshots to track regressions, improvements, and environment modifications over time.
-
⏱️ Watch Mode: Real-time directory polling for fast incremental rescans.
pip install healcode| Dependency | Version | Purpose |
|---|---|---|
| Python | ≥ 3.11 | Runtime |
healcode --versionFour commands take you from a fresh install to a full environment health report with a tracked baseline.
Creates a healcode.json config file in your project root, so scans are tuned to your setup from the start.
healcode config initScans your local environment, containers, cloud/K8s contexts, toolchains, and source code — then prints a weighted health score.
healcode scanSnapshots the current project state so future scans can be compared against it to catch drift.
healcode baseline create initial_stateGroups findings by root cause and prioritizes what to fix first — no cloud dependency required.
healcode ai --offline💡 Tip: Run
healcode scanregularly (or usewatchmode) and re-runhealcode baseline compare initial_stateto catch regressions before they reach code review.
Running healcode config init creates a healcode.json file in your project. Here's what a typical one looks like:
{
"profile": "DevOps",
"targets": ["."],
"checks": {
"system": true,
"docker": true,
"kubernetes": true,
"cloud": true,
"toolchains": true,
"static_analysis": true
},
"exclude": [
"node_modules",
"dist",
".venv"
],
"ai": {
"enabled": true,
"offline": true
}
}| Field | What it controls |
|---|---|
profile |
Which scanning profile is active (DevOps, Security, or Minimal) |
targets |
Which directories to scan — defaults to the current project |
checks |
Turn individual check categories on or off |
exclude |
Folders to skip during scanning |
ai.enabled / ai.offline |
Whether the AI layer runs, and whether it stays fully offline |
💡 See the full Configuration Reference for every available option.
| Command | Usage | Description |
|---|---|---|
scan |
healcode scan [target] |
Runs active diagnostics checks and displays system health. |
baseline |
healcode baseline create [name] / healcode baseline compare [name] |
Captures a project snapshot or analyzes current state against one. |
watch |
healcode watch |
Starts the directory file watcher for real-time, incremental rescanning. |
| Command | Usage | Description |
|---|---|---|
config |
healcode config init |
Initializes the project configuration file healcode.json. |
profile |
healcode profile set [name] |
Adjusts the active scanning profile (DevOps, Security, Minimal). |
| Command | Usage | Description |
|---|---|---|
ai |
healcode ai --offline |
Orchestrates root-cause diagnostics and repair recommendations. |
marketplace |
healcode marketplace search [q] |
Searches the community plugin marketplace (mock interface — not yet live). |
💡 Run
healcode <command> --helpfor full flag details on any command.
Every healcode scan ends with one number — your overall environment health percentage. Here's how to read it.
Each check HealCode runs (system, containers, cloud/K8s, toolchains, code) contributes to one of 40+ categories. Categories aren't weighted equally — a critical finding (like an exposed secret) pulls the score down more than a minor warning (like a missing restart policy).
Score = 100% − (weighted penalty for every warning and critical finding)
| Score Range | What it means |
|---|---|
| 🟢 90–100% | Healthy — no urgent action needed |
| 🟡 70–89% | Some warnings — worth reviewing before your next release |
| 🟠 50–69% | Multiple issues — recommend addressing before shipping |
| 🔴 Below 50% | Critical issues present — fix before continuing |
| Severity | Example | Impact |
|---|---|---|
| ✅ Passed | Docker daemon running correctly | No penalty |
| Kubernetes context using default namespace | Small penalty | |
| ❌ Critical | Exposed API key in source code | Large penalty |
💡 Run
healcode baseline compare [name]to see whether your score has improved, stayed flat, or regressed since your last check.
Full guides live in the docs/ folder. Here's what each one covers and when to reach for it:
Your first ten minutes with HealCode — installing, initializing config, running your first scan, and reading the health score output. Start here if you've never used HealCode before.
Platform-specific setup notes for Windows, Linux, and macOS, including Python version requirements and common install issues (permissions, PATH conflicts, virtualenv setup).
Every option available in healcode.json — scanning profiles (DevOps, Security, Minimal), which checks to include/exclude, and how to scope scans to specific directories or targets.
How a scan actually works under the hood: the check pipeline, how findings are scored and weighted into the overall percentage, and how the optional AI layer processes results offline.
The complete command list with every flag and subcommand — the canonical reference for scan, config, profile, baseline, watch, and ai.
How to write custom checks and package them as plugins, plus how the (currently mock) marketplace is intended to distribute them.
Fixes for common errors — failed scans, misdetected toolchains, kubeconfig issues, and Docker daemon connectivity problems.
⚠️ This is a placeholder — swap these in for your actual milestones fromROADMAP.md.
| Status | What |
|---|---|
| ✅ Done | Core checks — scan your computer, containers, and cloud setup |
| ✅ Done | Save a "before" snapshot and compare it to later scans |
| ✅ Done | Optional AI helper that works without internet |
| 🔜 Coming | A real plugin marketplace (right now it's just a demo) |
| 🔜 Coming | Support for more programming languages and tools |
| 🔜 Coming | A guide for using HealCode in GitHub Actions / GitLab CI |
Quick answers to what people usually ask before (and after) installing HealCode.
Does HealCode replace my existing linter or secret scanner?
No. HealCode doesn't try to out-lint your linter or out-scan your secret scanner. It brings together what those tools would already tell you into one report, adds cross-cutting checks (containers, cloud/K8s, toolchains), and tracks what's changed since your last scan — something standalone tools don't do on their own.
Which languages does HealCode support for static analysis?
Node.js · Python · Java · Go · Rust · Flutter
More languages are on the roadmap.
What's the difference between the DevOps, Security, and Minimal profiles?
| Profile | Prioritizes |
|---|---|
🏗️ DevOps |
Containers, cloud setup, configuration drift |
🔐 Security |
Exposed secrets, risky settings |
⚡ Minimal |
A lighter, faster subset of checks |
Set one with:
healcode profile set [name]Do I need an internet connection to use HealCode?
No. Core scanning (healcode scan) runs entirely locally. The AI layer is offline-first too — healcode ai --offline works with zero cloud dependency.
Will HealCode send my code or secrets anywhere?
No. Scans run locally against your filesystem, Docker context, cloud CLI config, and kubeconfig. Nothing is uploaded unless you explicitly configure an integration to do so.
What Python version do I need?
Python ≥ 3.11 to run HealCode itself. Your project's toolchain can be anything — HealCode flags a mismatch (e.g. a project requiring 3.11 while 3.9 is installed) rather than requiring it.
How is the health score calculated?
Score starts at 100% and subtracts a weighted penalty per finding:
| Severity | Penalty |
|---|---|
| ✅ Passed | None |
| Small | |
| ❌ Critical | Large |
See Understanding Your Health Score for the full breakdown.
Can I run HealCode in CI/CD?
Yes — see CI/CD Integration for pipeline examples and exit code behavior.
Is the plugin marketplace live yet?
🔜 Not yet — healcode marketplace search is currently a mock interface. Real plugin distribution is on the roadmap.
I found a security vulnerability — where do I report it?
SECURITY.md for responsible disclosure instructions.
💡 Don't see your question here? Check the Documentation Hub or open a discussion/issue.
HealCode is early-stage and community contributions are very welcome — whether that's a bug fix, a new check, better docs, or just filing an issue about something confusing.
1. Clone the repository
git clone https://github.com/Ashish6298/HealCode.git2. Enter the project directory
cd HealCode3. Install in editable mode with dev dependencies
pip install -e .[dev]- Read
CONTRIBUTING.mdfor guidelines and PR process - Follow the
CODE_OF_CONDUCT.mdin all interactions - Check existing issues before starting new work, to avoid duplicate effort
- Add or update tests in
tests/for any behavior change
Found a security issue instead? Please don't open a public issue — see SECURITY.md for responsible disclosure.
Stuck on something? Here's the fastest way to get unstuck, depending on what you need.
|
Search existing issues first — someone may have already hit it. If it's new, open an issue with:
|
Open a feature request — describe the problem you're trying to solve, not just the solution. It helps us design it right. Check the Roadmap first to see if it's already planned. |
|
Start with the FAQ and Documentation Hub — most "how do I…" questions are already answered there. Still stuck? Open a GitHub Discussion (or an issue, if discussions aren't enabled yet). |
Please don't open a public issue. Follow the responsible disclosure process in |
A quick checklist that resolves most support requests before they're even filed:
| ✅ Check | Why |
|---|---|
Run healcode --version |
Confirms you're on the latest release |
Run healcode config init |
Rules out a missing/stale config file |
Check docs/troubleshooting.md |
Covers common scan, kubeconfig, and Docker connectivity errors |
| Search closed issues | Your issue may already be fixed on main |
💬 Response times: HealCode is community-maintained, so replies aren't instant — but every issue and discussion gets read. Clear, reproducible reports get resolved fastest.
HealCode is released under the MIT License — free to use, modify, and distribute, including in commercial projects, as long as the original copyright and license notice are preserved.
See the full LICENSE file for details.
Built With The Python packaging & CLI tooling ecosystem |
Inspired By The linters & scanners HealCode brings together |
Tested Against Real-world Docker, K8s & multi-language setups |
❤️ Thanks To Every contributor & early adopter |
💡 If HealCode leans on a specific library, framework, or dataset worth crediting by name, list it here — e.g. "Static analysis heuristics adapted from
[tool/paper name]" or "Container scanning inspired by[project]."
HealCode exists so a leaked password, a wrong cloud setting, or messy code gets caught on your own computer — not after it's already caused a problem.
It's a small thing, but it helps other developers find the project — and it's the easiest way to support the work that goes into it.