Click "Sign in with GitHub" on the home page. tugtug uses GitHub OAuth — no passwords, no setup. You'll be redirected back after authorizing.
From your dashboard, enter a GitHub owner and repo name (e.g. "facebook/react") and click Analyze. Analysis takes 10–60 seconds depending on repo size. Any public repository works without a GitHub token.
Once analysis is complete, click the repo card to see your full code health report: hotspot map, top risky files, health score, coupling graph, and timeline.
A hotspot is a file with BOTH high complexity AND high churn. It's where bugs live. Complex code is hard to change correctly; frequently-changed code is where bugs get introduced. The intersection is the highest-risk part of your codebase.
Hotspot Score = Normalized Complexity × Normalized Churn. Both metrics are normalized to 0–1 within the repo, then multiplied. Files scoring above 0.5 are flagged as hotspots. A score of 1.0 means the most complex AND most churned file in the repo.
Cyclomatic complexity counts decision points in code: if/else, for, while, switch, catch, &&, ||, and ternary operators. A function with no branches has complexity 1. Each branch adds 1. Files are scored by summing all decision points.
Churn is the number of commits that touched a file in the last 90 days. High churn means a file changes frequently — making it more likely to receive bugs and more painful to work in.
The bubble chart visualizes all files at once. Bubble size = complexity. Color = churn intensity (blue = low, red = high). Position = relative risk score. Hover any bubble to see the file name and metrics. Scroll to zoom, drag to pan.
File coupling means two files change in the same commit, repeatedly. If auth.ts and user.ts appear together in 40 commits, they're tightly coupled — a change to one likely requires a change to the other.
Tightly coupled files reveal hidden dependencies. When file A keeps pulling file B into every commit, it's a sign that these two modules are entangled and should probably be refactored into a shared abstraction or merged.
Each node is a file. Node size = complexity. Node color = complexity (blue = low, red = high). Edge thickness = coupling strength (how often two files changed together). Hover a node to highlight its connections. Scroll to zoom, drag to pan.
Look for densely connected clusters — these are "tangled" modules. Look for high-complexity nodes (large, red) with many connections — these are your highest-risk refactoring candidates. Aim to reduce connections over time.
The health score (0–100) measures overall codebase quality. 100 is a pristine codebase. Scores below 60 indicate significant risk. It's derived from the ratio of hotspots, average complexity, and churn.
Score = 100 − (hotspot ratio × 20) − (normalized complexity × 15) − (normalized churn × 15). A codebase with no hotspots and low complexity scores near 100. High churn and many hotspots drive the score down.
80–100: Healthy. Well-maintained, low technical debt. 60–79: Watch list. Some areas need attention. Below 60: Action required. Likely high bug rate and slow feature velocity.
The health timeline plots your repo's health score over time. Each point represents one analysis run. Run analysis regularly (weekly or after major changes) to build a meaningful trend.
A rising line means your code quality is improving. A falling line means technical debt is accumulating. The score shown top-right is the most recent, with the delta from the first snapshot.
The timeline appears once you have 2+ analyses. Re-analyze the same repo monthly or after major refactors to see the impact of your work. All historical data is stored per repository.
Beyond cyclomatic complexity, tugtug measures cognitive complexity — how hard a function is to read. Deeply nested code gets a higher nesting penalty than flat code with the same number of branches. Based on the widely-adopted cognitive complexity metric.
A 6-line sliding-window hash finds copy-pasted code blocks. Duplicated blocks are flagged because a bug fix applied in one place but not another is a common source of regressions.
Files that export symbols nothing else in the codebase imports are flagged as dead code candidates. This catches old utility files, unused helpers, and migrated-away modules left behind.
tugtug scans for 16 security patterns: eval() usage, innerHTML assignment, execSync/exec calls, hardcoded secrets (API keys, tokens, passwords in strings), weak hash algorithms (MD5, SHA1), and more. Heuristic-based — useful for catching common mistakes, not a replacement for a full SAST scan.
After each analysis, tugtug compares results to the previous run and flags four conditions: (1) A file becomes a hotspot for the first time. (2) An existing hotspot's score worsens by more than 20%. (3) A high-risk file (hotspot score > 0.7) has gone untouched for 90+ days — orphaned technical debt. (4) Two files start changing together far more often than before.
CRITICAL: A high-risk file is orphaned — dangerous, and nobody has touched it in months. HIGH: A new hotspot appeared, a file that just crossed the risk threshold. MEDIUM: An existing hotspot worsened significantly. LOW: A pair of files is becoming more tightly coupled.
Alerts appear on the team dashboard immediately after analysis completes. With a Team subscription and daily email digest enabled, new alerts are included in the next morning's email.
Go to Teams in the navigation and click "Create team". Give your team a name — a URL-safe slug is generated automatically. You'll be the team owner.
From the team settings page, add any repositories you've previously analyzed. All team members can then see the aggregated health dashboard across those repos.
The team dashboard shows aggregate health across all team repos: avg health score, total hotspots, active alerts, and a repo-by-repo breakdown with health trends.
Enable the daily email digest in team settings. tugtug sends one email per day — only when something changed — summarizing health score trends and new alerts across all team repos.
Shows all commits for the past year as a GitHub-style heatmap. Darker green = more commits that week. Spot active sprints, feature freezes, and dead periods at a glance.
Weekly pull request size over the last 90 days, bucketed by Monday. A steady climb means PRs are getting harder to review; a downward trend means they're getting tighter. tugtug labels the trend growing, shrinking, or stable.
Usually 15–45 seconds for repos up to 1,000 files. Larger repos (5,000+ files) may take 2–3 minutes. The page updates automatically when complete.
Private repo analysis is currently included for signed-in users. Team access is not generally available yet; join the Team mailing list if you need shared workspaces and team-wide alerts. Your GitHub token is stored encrypted and only used to read file contents and commit history. Source code is never written to our database.
Currently JavaScript and TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs). The complexity analysis is language-specific and optimized for JS/TS decision-point patterns.
We store analysis results (file metrics, health scores, coupling data) — not the source code itself. File contents are fetched from GitHub, analyzed in memory, and discarded. Only aggregated metrics are persisted.
Weekly or after significant changes. The health timeline becomes meaningful with 4+ data points. Some teams analyze on every deploy via the API.
It takes under a minute to get your first health report.
Go to Dashboard →