# fuck-u-code: a legacy-mess detector that scores how bad your codebase really is

> Done-0/fuck-u-code is a TypeScript CLI that parses 14 languages with tree-sitter, scores each file on seven quality checks, and prints a report. It is opinionated, offline by default, and named the way it is named.

**Done-0/fuck-u-code** — Legacy-Mess Detector – assess the “legacy-mess level” of your code and output a beautiful report

- Repository: https://github.com/Done-0/fuck-u-code
- Stars: 7,295 · Forks: 327
- Language: TypeScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/done-0-fuck-u-code

## What fuck-u-code actually measures, and who wants that number

Most static analysis tools report violations. fuck-u-code reports a score. The README describes an Overall Score from 0 to 100 where higher means better code quality, plus a per-file "Shit-Gas Index" where higher means worse. Those two numbers run in opposite directions, which is worth knowing before you paste either into a dashboard.

The audience is narrow and specific. This is for a developer who has inherited a repository and wants a ranked list of the worst files, not a linter that blocks a commit. The `--top <n>` option defaults to 10, so the default output is a shortlist of offenders rather than a full audit. That framing tells you the intended workflow: open the repo, run the analyzer, get pointed at the ten files most likely to ruin your week.

The seven checks are complexity, size, comments, error handling, naming, duplication and structure. Each carries a weight in the config, and complexity dominates at 0.32 by default. That is a defensible default and also a strong opinion. If your team's real pain is duplicated business logic rather than branching depth, the stock score will not reflect it until you edit the weights.

Language coverage is broad for a project of this size: Go, JavaScript, TypeScript, Python, Java, C, C++, Rust, C#, Lua, PHP, Ruby, Swift and Shell, 14 in total. The README attributes the parsing accuracy to tree-sitter, and `package.json` confirms the dependency on `web-tree-sitter` and `tree-sitter-wasms`, so the grammars ship as WebAssembly rather than requiring a native build step.

## How the analysis pipeline works, from glob to report

The data flow is conventional and the dependencies make it legible. `glob` walks the target directory, `ignore` applies exclusion rules, and `p-limit` caps parallelism at the `--concurrency` value, which defaults to 8. Files are then parsed by tree-sitter into syntax trees, and the seven metrics are computed from those trees rather than from regular expressions over raw text.

That distinction matters. A regex-based complexity counter will happily count `if` inside a string literal. An AST-based one will not. The README's claim of accurate syntax analysis rests on this, and the dependency list backs it up.

Configuration resolution uses `cosmiconfig`, which explains the supported formats: `.fuckucoderc.json`, `.yaml`, `.js`, `fuckucode.config.js`, or a `"fuckucode"` field inside `package.json`. The README states discovery walks upward from the project directory and then falls back to a global `~/.fuckucoderc.json`. That is the same search pattern most Node tooling uses, so there is nothing to relearn.

The CLI itself is built on `commander`, with `chalk`, `cli-table3` and `ora` handling presentation. Output formats are console, markdown, json and html for analysis, and console, markdown and html for AI review. Note the asymmetry: AI review has no JSON format, so if you want machine-readable AI output you will be parsing Markdown.

AI review is a separate subcommand, not an automatic step. The README is explicit that code analysis runs fully offline and that AI review requires an external API or a local Ollama instance. The providers listed are OpenAI-compatible, Anthropic, DeepSeek, Gemini and Ollama, with `--base-url` and `--api-key` for anything else that speaks the same protocol.

## Installing fuck-u-code and getting a first report

The package is published as `eff-u-code`, which is the name you type into npm. The binary it installs is `fuck-u-code`. The README's install line is:

```bash
npm install -g eff-u-code
```

There is also a from-source path if you want to run the current `main` branch rather than the published version:

```bash
git clone https://github.com/Done-0/fuck-u-code.git
cd fuck-u-code && npm install && npm run build
```

`package.json` sets `"engines": { "node": ">=18.0.0" }`, so check your Node version before installing. There is also a `postinstall` script that runs `node bin/postinstall.js`, which is worth being aware of if your environment restricts install hooks.

Once installed, the smallest useful command analyzes the current directory and prints a colored terminal report:

```bash
fuck-u-code analyze
```

To get the ranked list of worst files with more context, the README gives this example, where `-v` adds a project overview, language statistics and function metrics, and `-t 20` widens the shortlist from the default 10:

```bash
fuck-u-code analyze . -v -t 20
```

For something you can attach to a pull request or archive, export JSON or HTML. The README shows both:

```bash
fuck-u-code analyze . -f json -o report.json
fuck-u-code analyze . -f html -o report.html
```

If tests are inflating the numbers, `-e` adds exclusion globs on top of whatever the config already excludes:

```bash
fuck-u-code analyze . -e "**/*.test.ts"
```

Before any of that, generate a config so the run is reproducible rather than relying on defaults:

```bash
fuck-u-code config init
fuck-u-code config show
```

The first command writes `.fuckucoderc.json`; the second prints the resolved configuration so you can confirm which file won the discovery walk.

## Where the scoring model breaks down

The weights are the weak point. Complexity at 0.32, duplication at 0.20, size at 0.18, structure at 0.12, error at 0.08, documentation at 0.05, naming at 0.05. Those seven numbers produce a single 0 to 100 figure, and that figure is presented as an Overall Score. A generated file, a vendored dependency, or a large data table will score badly on size and structure regardless of whether it is actually a problem. The README offers `--exclude` and an `exclude` config key, so the tool assumes you will curate the file set. It does not do that for you.

The comment metric is the other soft spot. Documentation carries only 0.05 weight, but the check itself is syntactic: it can count comments, not judge them. A file with a hundred lines of commented-out code and a file with a hundred lines of genuine explanation look similar to a parser.

The name is a real constraint, not a joke to wave away. `fuck-u-code` appears in terminal output, in exported HTML reports, and in the package's own documentation. If your reports are shared outside the team, or if your organization has a naming policy for tooling, this will be a problem before any technical issue arises. The HTML export in particular produces a standalone artifact with the tool's branding on it.

AI review introduces its own boundary. Sending source code to a hosted provider means the code leaves the machine, which directly contradicts the offline guarantee that applies to analysis. The README states this plainly, but the two modes sit under one tool, and it is easy to assume the whole thing is local. Ollama is the option that keeps review on-premises, at the cost of running a local model.

Finally, there is no documented threshold or exit-code behaviour for CI gating. The README documents formats, options and config, but not a `--fail-under` style flag or a non-zero exit on a low score. If you need a build to fail when quality drops, you will be parsing the JSON output yourself.

## fuck-u-code compared with ESLint and SonarQube

The closest comparison is ESLint, and the difference is philosophical. ESLint is rule-based: you enable rules, it reports each violation with a location, and you configure severity per rule. It is language-specific (JavaScript and TypeScript, with plugins) and it is designed to run on every commit. fuck-u-code is metric-based: it computes seven aggregate measures per file and produces a ranking. It does not tell you which line is wrong; it tells you which file is worst. For a legacy codebase with no lint configuration at all, that is a much lower-friction starting point than writing an ESLint config from scratch for a codebase nobody wants to touch.

SonarQube is the heavier comparison. It is a server, it stores history, it has a quality gate concept, and it covers many of the same ground: complexity, duplication, code smells. It also requires infrastructure. fuck-u-code is a single npm global install that runs offline and writes a file. If you want trend lines over months, SonarQube is the tool. If you want to know today which files are the worst in a repository you just cloned, the CLI is faster to reach an answer.

The AI review subcommand has no direct equivalent in either. It is closer to pasting the worst files into a chat window, except the selection of which files to send is automated via `--top`. That is a genuine convenience and also the part with the most caveats around data leaving your machine.

## Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-09-07, and the most recent release listed is v2.2.1 from 2026-02-27, with v2.2.0 and v2.1.0 in the weeks before that. The published `package.json` carries version 2.2.2, which is ahead of the newest tagged release in the repository, so the npm package and the GitHub releases are not perfectly in step. Worth checking which one you are installing.

Upgrades are handled by the tool itself. The README documents `fuck-u-code update`, which checks the installed version, checks npm for the latest, and installs it globally. That is convenient, and it also means the tool rewrites its own global installation, which may not suit environments where global package changes are managed centrally.

Uninstall is unusually thorough, and this is a point in the project's favour. `fuck-u-code uninstall` removes the global config file at `~/.fuckucoderc.json`, removes MCP server entries registered with Claude Code and Cursor, and removes the global npm package. A tool that registers itself with other applications and then cleans up after itself is doing more than most. The MCP server is exposed as a second binary, `fuck-u-code-mcp`, via `@modelcontextprotocol/sdk`.

On licensing: the project is MIT, and the README and `package.json` agree on that. MIT is permissive, so the usual obligations are attribution and including the licence text. The dependencies are a separate matter entirely. `@anthropic-ai/sdk` and `openai` are both bundled as runtime dependencies, and their terms are not the same as the project's MIT licence. If you ship this inside a product, review the dependency licences rather than assuming the top-level MIT covers everything. That is a general observation about dependency trees, not legal advice.

## Conclusion

Adopt fuck-u-code if you want a fast, offline, per-file quality signal you can pipe into JSON or HTML and hand to a team that responds to blunt framing. Skip it if you need CI gating with stable thresholds, licence-clean AI review, or a tool whose name can appear in a client-facing artifact. Before rolling it out, run `fuck-u-code config init`, confirm the generated `.fuckucoderc.json` weights match what your team considers quality, and check that the `metrics.weights` sum is what you expect, because the score is only as meaningful as those seven numbers.

## FAQ

### What is fuck-u-code and what does it do?

It is a TypeScript command-line tool that assesses the legacy-mess level of a codebase and outputs a report. It parses 14 languages with tree-sitter and scores files across complexity, size, comments, error handling, naming, duplication and structure.

### How do I install fuck-u-code?

The README gives the install command as `npm install -g eff-u-code`, since the npm package name is eff-u-code while the installed binary is fuck-u-code. It requires Node 18 or later according to package.json.

### Does fuck-u-code send my code to an external service?

The README states that code analysis runs fully offline and that your code never leaves your machine. The AI review subcommand is the exception: it requires an external API or a local Ollama instance.

### Which programming languages does fuck-u-code support?

The README lists 14: Go, JavaScript, TypeScript, Python, Java, C, C++, Rust, C#, Lua, PHP, Ruby, Swift and Shell.

### What file formats can fuck-u-code export reports to?

For analysis, the README documents console, markdown, json and html via the `-f` option, with `-o` to write to a file. For AI review, the documented formats are console, markdown and html.

## Sources

- [Done-0/fuck-u-code on GitHub](https://github.com/Done-0/fuck-u-code)
- [Issues](https://github.com/Done-0/fuck-u-code/issues)
- [License: MIT](https://github.com/Done-0/fuck-u-code/blob/main/LICENSE)
- [README](https://github.com/Done-0/fuck-u-code/blob/main/README.md)
- [Releases](https://github.com/Done-0/fuck-u-code/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/done-0-fuck-u-code