Metadata-Version: 2.4
Name: atrophy
Version: 0.1.4
Summary: Your coding skills have a half-life. atrophy measures it.
Author-email: Vamsi Krishna <vamsikv28@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/kvcops/Atrophy
Project-URL: Repository, https://github.com/kvcops/Atrophy
Keywords: developer-tools,ai,git,productivity,skills,cli
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: textual>=0.61.0
Requires-Dist: gitpython>=3.1.43
Requires-Dist: sqlalchemy[asyncio]>=2.0.30
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: tree-sitter-language-pack>=0.3.0
Requires-Dist: openai>=1.30.0
Requires-Dist: anthropic>=0.28.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: ollama>=0.4.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pillow>=10.3.0
Requires-Dist: qrcode[pil]>=7.4.2
Requires-Dist: fastapi>=0.135.1
Requires-Dist: uvicorn>=0.41.0
Provides-Extra: dev
Requires-Dist: bandit>=1.9.4; extra == "dev"
Requires-Dist: pip-audit>=2.10.0; extra == "dev"
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: ruff>=0.15.5; extra == "dev"
Dynamic: license-file

atrophy logo

 
 
 

 
 
 
 

🚨 Problem  · 
💡 What It Does  · 
⚙️ How It Works  · 
🚀 Install  · 
⚡ Quickstart  · 
🔬 Skills  · 
🔌 Providers  · 
❓ FAQ

## 🚨 The Problem Nobody Talks About

You use Cursor. You use Copilot. You use Claude. You are shipping faster than ever — PRs merging, tickets closing, metrics looking great.

But something quiet is happening underneath all of that.

```
❓  When did you last write a regex without pasting it into a chat window?
❓  Can you still write a raw SQL GROUP BY query from memory?
❓  If your AI tool broke right now — could you debug the async race condition yourself?
```

AI tools are genuinely incredible. But here is what nobody says out loud:

> **Every time AI does the hard part for you, your brain skips that rep. And skipped reps lead to atrophy.**

You are outsourcing the friction. Friction is where learning happens. Your skills are quietly wasting away — and until now, there was no tool to measure it, show it to you, or help you fight it.

**That is what `atrophy` is for.**

## 💡 What atrophy Does

   `atrophy` connects to your local git history and does **four things**:

   **1. Measures what YOU actually wrote** — using statistical signals, it separates commits you personally wrote from AI-generated ones.

   **2. Maps your skill health** — tracks 10 engineering disciplines and scores how actively you exercise each one yourself.

   **3. Shows you the decay** — a beautiful terminal dashboard reveals which skills are going dark and how fast, with a month-by-month timeline.

   **4. Fights back for you** — every week, 3 personalized coding challenges targeting your dead zones, using real patterns from your own codebase.

```
╔══════════════════════════════════════════════════════════════════╗
║  🔒  100% LOCAL  ·  Your code NEVER leaves your machine         ║
║      Read-only · No uploads · No telemetry · No phone home      ║
╚══════════════════════════════════════════════════════════════════╝
```


## ⚙️ How It Works

```
   YOUR GIT REPO                                          YOUR TERMINAL
  ┌─────────────┐                                        ┌─────────────────────┐
  │ commit log  │──── atrophy scan ────────────────────▶ │  Skill Health: 85   │
  │ diff hunks  │                                        │  Dead Zones: sql    │
  │ timestamps  │──── 5-signal AI detection ───────────▶ │  Challenges: 3 new  │
  │ messages    │                                        │  Trend: ↑ improving │
  └─────────────┘                                        └─────────────────────┘
        │
        ▼
  ┌───────────────────────────────────────────┐
  │  ~/.atrophy/atrophy.db  (stays local)     │
  └───────────────────────────────────────────┘
```


### 🔍 Step 1 — Reading Your Git History

`atrophy scan` walks your entire commit history for the past 180 days. It reads the actual diff of each commit and **automatically filters out noise**: dependency lock files, auto-generated code, minified files, and merge commits.

---

### 🤖 Step 2 — Separating Human from AI Commits

This is the statistical heart of `atrophy`. **5 signals** combine into a single probability score per commit:

 Signal
 What It Measures
 The Insight
 Weight

 ⚡
Velocity
 Lines added per minute vs your personal average
 AI pastes 200 lines in 8 seconds. Humans type.
 HIGH

 〰️
Burstiness
 Uniformity of line lengths in the diff
 AI code is suspiciously uniform. Human code is messy.
 HIGH

 🔬
Entropy
 Character distribution patterns in code
 AI produces "expected" code. Humans are quirky.
 MED

 🎨
Formatter
 Whether formatting is machine-perfect
 Running ruff/black yourself? atrophy detects & adjusts.
 MED

 💬
Msg Depth
 Commit message patterns & specificity
 "fix" at 2am = you. "feat: add JWT middleware" at 2am = Cursor.
 MED

> 🎯 **Personal Baseline:** atrophy calibrates all signals to *your* natural pace — from your oldest commits, before heavy AI use. A fast typist who uses conventional commits won't be falsely flagged.

---

### 🧬 Step 3 — Skill Detection (3 Layers)

 Priority
 Layer
 How It Works
 Languages

 1st
✅ Best
 Tree-sitter AST
 Real code parser — same tech as VS Code syntax highlighting. Counts actual AST nodes: async functions, SQL calls, test assertions, custom classes.
 Python · TS · JS · Go · Rust · Java · Ruby · C++ · more

 2nd
🧠 Smart
 LLM Semantic
 For ambiguous or rare languages, sends a short anonymized snippet to your configured LLM. Your API key. Direct to provider. No middleman.
 Any language · complex cases

 3rd
⚡ Free
 Keyword Fallback
 Smart keyword scanning inside actual code only — not comments or strings — using language-specific comment strippers.
 Any language · zero cost · always available

---

### 🏆 Step 4 — Personalized Weekly Challenges

Every week, `atrophy challenge --generate` picks your top 3 dead zones and creates targeted exercises using context from **your actual codebase**:

| Context Sent to LLM | Example Output |
|---------------------|----------------|
| Most-committed files (names only) | *"Add a raw aggregate query to your existing `User` model"* |
| Short code sample you personally wrote | *"Using the patterns already in `repositories/user_repo.py`"* |
| Detected tech stack & frameworks | *"With your SQLAlchemy setup, not a generic ORM tutorial"* |
| Primary language | Not LeetCode. Not generic tutorials. **Your stack.** |

> 🛡️ If the LLM returns something generic or hallucinated, atrophy auto-detects it and swaps in a hand-crafted fallback challenge. You always get something useful.

## 🚀 Installation

**Recommended — [`uv`](https://github.com/astral-sh/uv)** *(Rust-powered, 100× faster than pip, keeps atrophy isolated)*

```bash
# Install uv first (if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install atrophy globally
uv tool install atrophy

# Verify
atrophy --version
```

**Or plain pip:**
```bash
pip install atrophy
```


## ⚡ Quickstart (2 Minutes)

```bash
# ① Go to any project with git history
cd your-project

# ② One-time setup — connects atrophy to this repo
#    Asks for your git email + optionally an LLM provider
atrophy init

# ③ Scan the last 180 days (takes 10–60s depending on repo size)
atrophy scan

# ④ Read your full skill report in the terminal
atrophy report

# ⑤ Launch the interactive animated dashboard
atrophy dashboard

# ⑥ Generate this week's personalized skill challenges
atrophy challenge --generate

# ⑦ Export your weekly digest to Markdown
atrophy digest --open
```


📊   Preview: atrophy report

```
┌─────────────────────────────────────────────────────────────────┐
│  📊 Your Coding Fingerprint                                     │
│  yourusername · Python developer · Active since 2023            │
├─────────────────┬──────────────┬───────────┬────────────────────┤
│  Skill          │  Score       │  Trend    │  Last Used         │
├─────────────────┼──────────────┼───────────┼────────────────────┤
│  api_design     │  ████████ 85 │  ↑ up     │  2 days ago        │
│  algorithms     │  ███████░ 72 │  ↑ up     │  5 days ago        │
│  security       │  ██████░░ 68 │  → stable │  1 week ago        │
│  async          │  ██████░░ 61 │  ↓ down   │  3 weeks ago       │
│  sql_databases  │  ██░░░░░░ 29 │  ↓ down   │  ⚠  62 days ago   │
│  regex_parsing  │  █░░░░░░░ 18 │  ↓ down   │  ⚠  41 days ago   │
└─────────────────┴──────────────┴───────────┴────────────────────┘

  ⚡ Skills to Revisit: sql_databases (62d), regex_parsing (41d)
  🧬 Coding Style: systematic  |  Most active: 11pm  |  Language: Python
```


🖥️   Preview: atrophy dashboard

```
╔══════════════════════════════════════════════════════════════════════════╗
║  🧬 ATROPHY  ·  Coding Fingerprint  ·  yourname@email.com  ·  2 min ago ║
╠═══════════════════════════╦════════════════════════════════════════════╣
║  YOUR SKILL HEALTH        ║  HUMAN vs AI RATIO (last 6 months)        ║
║                           ║                                            ║
║  🧠  algorithms    72  ▓▓▓▓▓▓▓░ ↑  ║  Oct  ████████████████░░░░  79%  ║
║  🛡️   security     68  ▓▓▓▓▓▓░░ →  ║  Nov  ████████████░░░░░░░░  61%  ║
║  🌐  api_design    85  ▓▓▓▓▓▓▓▓ ↑  ║  Dec  ████████░░░░░░░░░░░░  48%  ║
║  ⚡  async         61  ▓▓▓▓▓▓░░ ↓  ║  Jan  ██████████░░░░░░░░░░  53%  ║
║  🗄️   sql          29  ▓▓░░░░░░ ⚠  ║  Feb  ████████████░░░░░░░░  59%  ║
║  🔍  regex         18  ▓░░░░░░░ ⚠  ║  Mar  ██████████████░░░░░░  67% ↑║
║                           ║                                            ║
╠═══════════════════════════╬════════════════════════════════════════════╣
║  ⚡ SKILLS TO REVISIT     ║  🏆 THIS WEEK'S WINS                       ║
║                           ║                                            ║
║  • sql_databases  62 days ║  ✨ error_handling improved +14 pts        ║
║  • regex_parsing  41 days ║  🔥 testing: dead zone cleared!            ║
║  • testing        38 days ║  📈 Best human ratio in 3 months           ║
╠═══════════════════════════╩════════════════════════════════════════════╣
║  🔥 Streak: 3 weeks  |  Pending: 2 challenges  |  [Q]uit  [R]efresh   ║
╚══════════════════════════════════════════════════════════════════════════╝
```


## 🔬 The 10 Skill Disciplines

`atrophy` tracks **10 universal engineering skill areas** — across any language and any codebase.

 Icon
 Skill
 What It Tracks
 Example Signals

 🧠
 Algorithms
 Data structures, sorting, recursion, dynamic programming
 tree traversals · binary search · memoization · heap usage

 🔍
 Regex & Parsing
 Pattern matching, text extraction, string manipulation
 capture groups · lookaheads · re.compile · named groups

 🗄️
 SQL & Databases
 Queries, schema design, optimization, transactions
 window functions · CTEs · cursor.execute · GROUP BY

 🌐
 API Design
 Route design, middleware, auth patterns, REST/GraphQL
 middleware · dependency injection · route handlers

 🛡️
 Security
 Auth, input validation, cryptography, permissions
 password hashing · JWT handling · parameterized queries

 ⚡
 Async & Concurrency
 Async code, threads, event loops, parallel tasks
 async/await · task groups · semaphores · goroutines

 ✅
 Testing
 Unit tests, integration tests, mocks, property tests
 fixtures · deep mocking · pytest marks · hypothesis

 🏗️
 Data Structures & OOP
 Custom classes, type design, interfaces, generics
 dataclasses · custom trees/graphs · protocol classes

 💾
 System I/O
 File operations, networking, processes, sockets
 pathlib · subprocess · socket programming

 🔧
 Tooling & DevOps
 Build scripts, CI/CD, containers, automation
 multi-stage builds · GitHub Actions · bash pipelines

**How Scores Work**

```
  0 ──────────── 8 ────────────────── 50 ──────────────────── 100
  │              │                    │                        │
  │   DEAD ZONE  │     FADING  ↓      │     HEALTHY  ↑         │
  │  ⚠ Revisit  │   Needs attention  │    Keep it up!         │

  • Score < 8 or gap > 45 days  →  flagged as ⚠ Skill to Revisit
  • Last 30 days of activity    →  counts 3× more than older work
  • Scores update on every      →  atrophy scan
```


## 🔌 LLM Providers

`atrophy` works **completely offline** with no LLM. Add one to unlock personalized weekly challenges and smarter skill detection for less common languages.

 Provider
 Privacy
 Setup
 Best For
 Cost

 🦙 Ollama Local
 🟢 100% private
nothing leaves machine
 ollama serve
ollama pull llama3.2
 Privacy-first · fully offline · corporate use
 Free

 🔵 OpenRouter
 🔵 Cloud
sent to provider
 openrouter.ai/keys (https://openrouter.ai/keys)
 Best value — 500+ models, free options available
 Free tier
+ pay-per-use

 🟣 Anthropic
 🔵 Cloud
sent to Anthropic
 console.anthropic.com (https://console.anthropic.com)
 Best reasoning quality · most accurate challenges
 Pay per token

 🟡 OpenAI
 🔵 Cloud
sent to OpenAI
 platform.openai.com (https://platform.openai.com)
 Reliable · well-tested
 Pay per token

 ☁️ Ollama Cloud
 🔵 Cloud
sent to ollama.com
 ollama.com/settings/keys (https://ollama.com/settings/keys)
 Huge models without a GPU (70B, 671B)
 Usage-based

 ⬛ None (Offline)
 🟢 Air-gapped
zero network
 Skip during atrophy init
 Full tracking + dashboard · no AI challenges
 Free

> **💡 Which should I pick?**
>
> | Goal | Pick |
> |------|------|
> | 🔒 Maximum privacy | **Ollama Local** — free, fully offline |
> | 💸 Best free option | **OpenRouter** — `qwen/qwq-32b:free` and `meta-llama/llama-3.3-70b-instruct:free` are excellent |
> | 🧠 Best quality | **Anthropic Claude Sonnet** — most contextually accurate challenges |
> | 🏢 Corporate environment | **Ollama Local** — your code never leaves your network |

**What data goes to the LLM?** Only a short, sanitized snippet of your own code (max 400 chars), your detected tech stack, and the skill category. Your full source files are **never** sent.

## 📋 All Commands

```bash
# ── Setup ────────────────────────────────────────────────────────────────
atrophy init                       # One-time setup for this repo
atrophy init --email you@dev.com   # Specify git author email manually

# ── Scanning ─────────────────────────────────────────────────────────────
atrophy scan                       # Analyze last 180 days of commits
atrophy scan --days 90             # Analyze last 90 days only
atrophy scan --force               # Re-scan even if already done today

# ── Reporting ────────────────────────────────────────────────────────────
atrophy report                     # Full skill report in the terminal
atrophy report --json              # Output as JSON (for piping/scripts)
atrophy report --share             # Save report.md to current folder

# ── Dashboard ────────────────────────────────────────────────────────────
atrophy dashboard                  # Launch interactive animated TUI

# ── Challenges ───────────────────────────────────────────────────────────
atrophy challenge                  # View this week's pending challenges
atrophy challenge --generate       # Generate 3 new personalized challenges
atrophy challenge --done 12        # Mark challenge #12 as complete

# ── Sharing ──────────────────────────────────────────────────────────────
atrophy digest                     # Print weekly digest to terminal
atrophy digest --open              # Save and open in $EDITOR
atrophy share                      # Generate a shareable PNG card
atrophy badge                      # Start local server serving your badge SVG

# ── Config ───────────────────────────────────────────────────────────────
atrophy config                     # Change LLM provider or settings
```


## 📦 What Gets Stored and Where

`atrophy` stores everything in `~/.atrophy/` — **nothing** in your git repositories is ever modified.

```
~/.atrophy/
├── atrophy.db        # SQLite — all scan history, skill scores, challenges
├── config.json       # Settings (provider choice, email, scan preferences)
├── .env              # API keys — never committed, never leaves your machine
└── digests/
    ├── 2026-10.md    # Weekly digest exports
    └── 2026-11.md
```


| What atrophy ✅ DOES | What atrophy ❌ NEVER DOES |
|:-------------------:|:------------------------:|
| Reads commit metadata | Write to your repo |
| Reads diff content locally | Upload your code |
| Stores scores in `~/.atrophy/` | Send telemetry |
| Generates local reports | Phone home |

## 🗺️ Roadmap

| Status | Version | Feature |
|:------:|:-------:|---------|
| ✅ Done | `v0.1` | Core git scanner + 5-signal AI detection heuristics |
| ✅ Done | `v0.2` | Personal baseline calibration (no more penalizing good devs) |
| ✅ Done | `v0.3` | 3-layer skill detection: Tree-sitter AST + LLM + keyword fallback |
| ✅ Done | `v0.4` | Animated Textual TUI dashboard |
| ✅ Done | `v0.5` | LLM challenge engine with real codebase context |
| ✅ Done | `v0.6` | OpenRouter (500+ models) + Ollama Cloud support |
| ✅ Done | `v0.7` | Wins system + positive momentum framing + weekly digests |
| 🔄 Active | `v0.8` | **GitHub Action PR comments with skill reports** |
| 📅 Planned | `v0.9` | VS Code extension — live skill meter in status bar |
| 📅 Planned | `v1.0` | Team dashboards + multi-repo support |
| 📅 Planned | `v1.1` | Mercurial backend support |

> 💬 Have a feature idea? [**Open a Discussion →**](https://github.com/kvcops/Atrophy/discussions)

## ❓ FAQ

🔒   Does my code ever leave my machine?

**No, by default.** Everything `atrophy` does runs entirely on your local machine. Your git history, your diffs, your skill scores — all stored in `~/.atrophy/` and never sent anywhere.

The one exception is if you configure a cloud LLM provider for challenge generation. In that case, **only a short, anonymized code snippet is sent** — not your full source files. To keep everything 100% offline, use **Ollama Local** or skip the LLM entirely.

🤔   Can I use atrophy without any API key?

**Yes, completely.** `atrophy` works in full tracking mode with no API key at all. You get:

- ✅ Full git history scanning
- ✅ AI vs human classification (5-signal heuristics)
- ✅ Skill health scores across all 10 disciplines
- ✅ The animated terminal dashboard
- ✅ Weekly digest exports
- ❌ AI-generated personalized challenges *(requires a provider)*

For offline challenges, install [Ollama](https://ollama.com) and pull any model — free, local, private.

🎯   How accurate is the AI detection?

`atrophy` uses 5 statistical signals combined with your personal baseline. It is reasonably accurate but not perfect — and that is by design.

Things that can affect readings:
- **Squash commits** look like AI even when they're human → marked as *"uncertain"*
- **Auto-formatters** like ruff or black make code look "too clean" → atrophy detects and adjusts
- **Conventional commits** are popular with both AI and disciplined humans → atrophy checks your historical patterns

Treat your score as an **honest personal mirror**, not a verdict. Accuracy improves significantly after 3+ scans.

💼   Is it safe to use on my company's codebase?

Yes — with **Ollama Local**, `atrophy` is completely air-gapped. No data leaves your machine at any point. It only reads git metadata and diffs locally.

`atrophy` never uploads, indexes, or stores your code anywhere outside your own `~/.atrophy/` directory.

⚙️   Which languages and editors are supported?

`atrophy` works with **any git repository** — editor and IDE don't matter.

Tree-sitter AST analysis supports: Python, TypeScript, JavaScript, Go, Rust, Java, Ruby, C, C++, and more. For unsupported languages, LLM semantic classification or keyword fallback handles detection automatically.

Currently supports **git only**. Mercurial support is on the roadmap.

📅   How often should I run it?

**Once a week** gives you good signal with low noise. `atrophy scan` is fast — typically under 60 seconds — and only processes new commits since the last scan.

After about **3 scans**, atrophy has enough data to calibrate your personal baseline and scores become meaningfully accurate.

🏷️   How do I add the badge to my GitHub profile?

Run `atrophy badge` — it starts a local server at `http://localhost:6174` serving an SVG badge:

```markdown
![atrophy score](http://localhost:6174)
```

For a static image, run `atrophy share` — it generates `atrophy-card.png` ready to post anywhere.

## 🤝 Contributing

 
 

| Area | What To Do | Where |
|------|-----------|-------|
| 🆕 New skill category | 5 steps, fully documented | `CONTRIBUTING.md` |
| 🔍 Better AST detection | Add node types | `skill_mapper.py` → `SKILL_NODE_MAP` |
| 🔌 New LLM provider | Copy base pattern, 4 steps | `providers/base.py` |
| 🧪 Tests | Every new feature needs coverage | `tests/` |

**Good first issues:**
- Add Swift / Kotlin language support to tree-sitter skill detection
- Add `atrophy compare` command (compare two different time windows)
- Improve the Textual dashboard with Plotext charts
- Write a Homebrew formula for macOS one-line install

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.

    
    

Built with 💜 by developers who refuse to lose their edge

[PyPI](https://pypi.org/project/atrophy/)  ·  [GitHub](https://github.com/kvcops/Atrophy)  ·  [Discussions](https://github.com/kvcops/Atrophy/discussions)  ·  [MIT License](LICENSE)

