Metadata-Version: 2.4
Name: atrophy
Version: 0.1.0
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
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=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

   
   
   
   
   

  🚨 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 commits that were clearly AI-generated.

  **2. Maps your skill health** — it tracks 10 engineering disciplines (SQL, algorithms, testing, security, etc.) 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, it generates 3 personalized coding challenges targeting your dead zones, using real patterns from your own codebase. Not LeetCode. Not generic tutorials. Your forgotten skills, in your actual stack.

**The key thing:** Everything runs 100% locally on your machine. Your source code never leaves your computer. `atrophy` only reads your git history — it never writes to your repo, never uploads your code, and never phones home.

## ⚙️ How It Works

### Step 1 — Reading Your Git History

When you run `atrophy scan`, it walks your entire commit history for the past 180 days (configurable). It reads the actual diff of each commit — the lines of code added, removed, and changed. It filters out noise automatically: dependency lock files, auto-generated code, minified files, and merge commits are all ignored so they don't skew your results.

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

This is the statistical heart of `atrophy`. It uses **5 signals** combined into a single probability score for each commit:

| Signal | What It Looks At | Why It Works |
|---|---|---|
| **Commit Velocity** | Lines added per minute vs. your personal average | AI pastes 200 lines in 8 seconds. Humans type |
| **Burstiness Score** | How uniform or varied your line lengths are | AI code is suspiciously uniform. Human code is messy |
| **Entropy Analysis** | Character distribution patterns in the code | AI produces "expected" code. Humans are quirky |
| **Formatter Presence** | Whether formatting is machine-perfect | Running ruff/black yourself? atrophy accounts for it |
| **Message Depth** | Commit message patterns and specificity | "fix" at 2am is you. "feat: add JWT middleware" at 2am is Cursor |

**Important:** atrophy builds a **Personal Baseline** from your oldest commits — from before you were using AI heavily. It calibrates all signals to *your* natural pace, not some generic average. A developer who types fast and always uses conventional commits won't be falsely flagged as AI-assisted. The tool adapts to you.

This is a probabilistic mirror for self-reflection. It is not a verdict, not a judge, and not accurate enough to evaluate anyone else. Treat it as honest data about yourself.

### Step 3 — Mapping Skills with 3-Layer Detection

Once `atrophy` knows which commits you personally wrote, it figures out *which skills* you exercised. It uses three layers in priority order:

**Layer 1 — Tree-sitter AST Analysis (most accurate)**
Tree-sitter is a real code parser — the same technology that powers VS Code's syntax highlighting. `atrophy` uses it to build an Abstract Syntax Tree of your code changes and count actual code structures: async functions, try/catch blocks, SQL calls, custom classes, test assertions, and more. It understands code structure, not just text. It works for Python, TypeScript, JavaScript, Go, Rust, Java, Ruby, C++, and more.

**Layer 2 — LLM Semantic Classification (for complex or unknown cases)**
For recent commits (last 90 days) where the language is less common or the skill is ambiguous, `atrophy` can optionally send a short anonymized snippet to your configured LLM to ask "what skill category is this?" — using your own API key, direct to the provider. No middleman.

**Layer 3 — Keyword Fallback (always available, zero cost)**
If tree-sitter doesn't support the language and you have no LLM configured, `atrophy` falls back to smart keyword scanning — but only inside actual code (not comments or string literals), using language-specific comment strippers.

### Step 4 — Generating Your Weekly Challenges

Every week, `atrophy challenge --generate` picks your top 3 dead zones and asks your configured LLM to create personalized exercises. Before sending anything to the LLM, `atrophy` builds a rich context package:
- The most-committed files in your project (by name, not content)
- A short sample of real code you personally wrote in that skill area
- Your detected tech stack (frameworks, dependencies)
- Your primary language

The result: challenges that say "add a raw aggregate query to your existing User model using the patterns already in your codebase" — not "implement a binary search tree."

If the LLM returns something generic or hallucinated, `atrophy` detects this automatically and swaps in a hand-crafted fallback challenge. You always get something useful.

## 🚀 Installation

We recommend **[`uv`](https://github.com/astral-sh/uv)** — a Rust-powered Python package manager that is 100x faster than pip and keeps `atrophy` isolated from your system Python.

```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
```

**Prefer plain pip?**
```bash
pip install atrophy
```

**Verify the install:**
```bash
atrophy --version
```


## ⚡ Quickstart (2 Minutes)

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

# ② One-time setup — connects atrophy to this repo
#    It will ask for your git email and optionally an LLM provider
atrophy init

# ③ Scan the last 180 days of commits (takes 10–60 seconds 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 (paste into Obsidian, Notion, etc.)
atrophy digest --open
```


📸 What does the terminal dashboard look like?

```
╔══════════════════════════════════════════════════════════════════════════╗
║  🧬 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 challenges: 2  |  [Q]uit  [R]efresh   ║
╚══════════════════════════════════════════════════════════════════════════╝
```


📋 What does atrophy report look like?

```
┌─────────────────────────────────────────────────────────────────┐
│  📊 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

  [dim] Note: Scores are statistical estimates for self-reflection only.
  Auto-formatters, squash commits, and conventional commit tools may
  affect readings. Calibration improves after 3+ scans. [/dim]
```


## 🔬 The 10 Skill Disciplines

`atrophy` tracks your activity across 10 universal engineering skill areas. These work 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, raw cursor.execute, GROUP BY

 🌐
 API Design
 Route design, middleware, auth patterns, REST/GraphQL
 Custom 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
 Custom 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, file streaming

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

**How scores work:**
- Each skill is scored 0–100 based on how recently and how deeply you exercised it yourself
- Recent activity (last 30 days) counts 3× more than older activity
- A score below 8 or a gap of 45+ days marks a skill as a **"Skill to Revisit"**
- Scores update every time you run `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
 How to Set Up
 Best For
 Cost

 🦙 Ollama Local
 🔒 100% private
nothing leaves machine
 ollama serve
ollama pull llama3.2
 Privacy-first teams
offline use
 Free

 ☁️ Ollama Cloud
 ☁️ Sent to ollama.com
 API key from
ollama.com/settings/keys (https://ollama.com/settings/keys)
 Large models without a GPU
(70B, 671B etc.)
 Usage-based

 🔵 OpenRouter
 ☁️ Sent to provider
 API key from
openrouter.ai/keys (https://openrouter.ai/keys)
 Best value — 500+ models
free options available
 Free tier + pay-per-use

 🟡 OpenAI
 ☁️ Sent to OpenAI
 API key from
platform.openai.com (https://platform.openai.com)
 Reliable, well-tested
 Pay per token

 🟣 Anthropic
 ☁️ Sent to Anthropic
 API key from
console.anthropic.com (https://console.anthropic.com)
 Best reasoning quality
 Pay per token

 ⬛ None (Offline)
 🔒 100% private
no network at all
 Skip during atrophy init
 Full tracking + dashboard
no challenges
 Free

> **Which provider should I pick?**
> - **Privacy first** → Ollama Local (free, fully offline, models run on your machine)
> - **Best free option** → OpenRouter (`qwen/qwq-32b:free` and `meta-llama/llama-3.3-70b-instruct:free` are excellent and free)
> - **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 when generating challenges: a short, sanitized snippet of your own code (max 400 characters), your detected tech stack, and the skill category. Your full source files are never sent. You can run `atrophy` forever in tracking-only mode with no LLM at all.

## 📋 All Commands

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

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

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

atrophy dashboard                 # Launch interactive animated TUI

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

atrophy digest                    # Print weekly digest to terminal
atrophy digest --open             # Save and open in $EDITOR

atrophy share                     # Generate a shareable PNG card (for Twitter/X)
atrophy badge                     # Start a local server serving your score badge
atrophy config                    # Change LLM provider or settings
```


## 📦 What Gets Stored and Where

`atrophy` stores everything in `~/.atrophy/` on your machine.

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

**Nothing in your git repositories is ever modified.** `atrophy` is read-only. It reads commit metadata and diffs. It never writes, stages, or commits anything to any repo.

## 🗺️ Roadmap

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

> 💬 Have a feature idea? [Open a Discussion →](https://github.com/yourusername/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 (OpenAI, Anthropic, OpenRouter, or Ollama Cloud) 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 (using the 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 challenges without any cloud service, install [Ollama](https://ollama.com) and pull any model — it runs locally, it's free, and your data stays on your machine.

🎯 How accurate is the AI detection?

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

A few things that can affect readings:
- **Squash commits** look like AI even when they're human (atrophy detects and marks these as "uncertain")
- **Auto-formatters** like ruff or black make your code look "too clean" — atrophy detects these tools in your repo and adjusts
- **Conventional commits** (`feat:`, `fix:`) are popular with AI tools but also with disciplined humans — atrophy checks your historical patterns before scoring this signal

The bottom line: treat your score as an honest personal mirror, not a precise measurement. It improves with more data — after 3+ scans, calibration accuracy increases significantly.

💼 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.

If you use a cloud LLM provider, only a small code snippet is sent for challenge generation. Consult your company's security policy if you are unsure about sending any code externally.

`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.

For skill detection, 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.

For version control, `atrophy` 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. Running more often is fine — `atrophy scan` is fast (typically under 60 seconds) and it only processes new commits since the last scan.

For best results, scan weekly and do one challenge per week. After about 3 scans, `atrophy` has enough data to calibrate your personal baseline well and the 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 with your current human coding score. Add it to any README:

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

For a static shareable image, run `atrophy share` — it generates a `atrophy-card.png` in your current folder ready to post on Twitter/X.

## 🤝 Contributing

   
   

`atrophy` is built to be easy to contribute to. The most impactful contributions:

- **Add a new skill category** — 5 steps, documented in `CONTRIBUTING.md`
- **Improve AST detection** — add node types to `SKILL_NODE_MAP` in `skill_mapper.py`
- **Add a new LLM provider** — copy `providers/base.py` pattern, 4 steps
- **Write tests** — every new feature needs a test in `tests/`

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

**Good first issues if you want somewhere to start:**
- 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

    
    

  Built with 💜 by developers who refuse to lose their edge  · 
  PyPI (https://pypi.org/p/atrophy)  · 
  GitHub (https://github.com/yourusername/atrophy)  · 
  MIT License

