run_health_scanLABSCO SUMMARY
An agent can check its own work, and be stopped from touching what matters.
Point it at a project and it returns findings with a file, a line and a severity, produced on your own machine rather than by shipping the code out to a model to read. The other half is the guardrail: a save point before the agent starts, a rollback when it goes wrong, and a frozen-file list that a Claude Code hook enforces rather than merely asks for.
What it is
A scanner for the codebase an AI coding assistant is working in, exposed to that assistant as an MCP server with 29 tools. It reads what is already on disk — source files, git history, config files, dependency manifests — and returns findings that each carry a file, a line, a severity and a suggested fix. The health scan runs in 9 phases and the security scan in 10 modules, and both run locally: the analysis makes no API calls and the code is not sent anywhere.
What you get
- A full pass with
run_health_scan, or any single phase on its own —get_unused_code,get_tech_debt,get_security_issues,get_complexity_report,get_git_health,get_test_coverage,get_docs_quality,get_ui_issues,get_framework_check,get_outdated_deps,get_config_map get_health_summaryfor a compact score-and-top-issues read before committing to a full scan, andgenerate_health_reportwhen you want the findings as markdown- Orientation without opening the repo yourself:
detect_project_stack,get_module_graph,get_status,get_activity, andsearch_codefor a regex sweep narrowed by a glob - A git-backed undo —
create_save_pointbefore risky work,list_save_pointsto see what is there,rollback_save_pointto put the tree back - Files the agent is not allowed to edit —
freeze_file,unfreeze_file,list_frozen. A frozen path is written into CLAUDE.md for any agent to read, and on Claude Code a PreToolUse hook rejects the write outright install_context7anduninstall_context7to wire in Context7, which is what attaches version-specific documentation snippets to findings instead of generic advicebuild_promptandlist_prompts— hand the current findings, frozen files and priority order back to the assistant as a prompt
Requirements
No credentials for the scanning itself — it runs against files on disk, with no API calls and no telemetry. npx fartrun@latest install fetches the binary for your platform and writes the MCP entry into Claude Code, Cursor and Windsurf; --claude, --cursor or --windsurf limits it to one. Prebuilt binaries cover Linux and macOS on x64 and arm64 and Windows on x64, and an unsupported pairing such as Windows on ARM exits with an error rather than installing. A key only enters the picture for the optional AI tips: ANTHROPIC_API_KEY by default, or an OpenAI-compatible provider set under [ai] in config.toml. Save points and rollback are git operations, so the project has to be a git repository, and rollback refuses to run on a dirty working tree. Building from source is Python 3.11+, with Node.js 18+ behind the npm installer and maturin for the Rust modules. The documentation-backed fix suggestions only appear once Context7 MCP is installed. On accuracy the project publishes its own measurements — 99% on TypeScript and React, 91% on Django and DRF — so dead-code findings on a Django project are the ones to verify by hand, since ORM signals and receivers create usage the parser cannot see.
Setup effort
One command — npx fartrun@latest install
USE CASES
01
Sizing up a project you have just inherited
Detect the stack first, then take the compact summary and decide from there whether a full scan is worth the time.
02
Checking that the last AI session did not leave a key in the repo
Run the security modules, then look at what git is actually tracking and what the history still holds.
03
Refactoring without losing the version that worked
Save before the agent starts. If the tree ends up worse, roll back — the state you rolled away from is kept on a backup branch.
04
Keeping the agent out of auth, payment and production config
Freeze those paths, then read the list back at the start of each session. On Claude Code the hook blocks the edit; with other tools the CLAUDE.md entry is what the agent reads.
05
Deleting dead code you are confident is actually dead
Pull the unused symbols, then search each name across the project before removing it — reflection and dynamic dispatch are where the false positives come from.
06
Handing a scan back to the assistant as a plan of work
Turn the findings into a markdown report, or into a prompt that already carries the findings, the frozen files and the order to work in.
07
Fixing something the way the library's current docs say to
Install Context7 first; framework findings then arrive with a version-specific snippet attached instead of general advice.
08
Finding out why the test suite covers so little
Map test files against source modules to see which ones have no tests at all, then check whether the debt sits in the same files.
29 tools
Listed in project docs. Your client may show a different list.
get_health_summaryget_unused_codeget_tech_debtget_security_issuesget_module_graphget_complexity_reportget_git_healthget_test_coverageget_docs_qualityget_ui_issuesget_framework_checkget_outdated_depsget_config_mapgenerate_health_reportget_statusget_activitydetect_project_stacksearch_codebuild_promptcreate_save_pointrollback_save_pointlist_save_pointsfreeze_fileunfreeze_filelist_frozeninstall_context7uninstall_context7list_promptsBEFORE YOU INSTALL
What to know first
Tools you get
29 tools named in the project's documentation.
Requires
npx on PATH
Where it runs
All 3 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
npx fartrun@latest installMCP Clients
Claude Code, Cursor, Windsurf
JSON
{
"mcpServers": {
"fartrun": {
"command": "/home/<YOUR_USERNAME>/.local/bin/fartrun",
"args": [
"mcp"
]
}
}
}npx fartrun@latest install writes this entry for you. If you add it by hand, /home/<YOUR_USERNAME> is your own home directory: the installer puts the binary at ~/.local/bin/fartrun on Linux and macOS, and at %LOCALAPPDATA%\fartrun\fartrun.exe on Windows.
