---

THIS IS CHARLIE WORK. Nobody else will do it. That's why it's yours.

The jokes are a toggle, not a tax — pass mode="plain" (or set CHARLIE_VOICE=off) and every response is flavor-free, paste-into-a-ticket clean. CI and SARIF output are always plain.

Three ways to run it

1. As an MCP server — point Claude Desktop / Cursor / Claude Code at it:

{
  "mcpServers": {
    "charlie-work": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Falcon305/charlie-work-mcp", "charlie-work-mcp"]
    }
  }
}

2. As a CLI:

uvx --from git+https://github.com/Falcon305/charlie-work-mcp charlie-work scan
charlie-work summary        # toil budget + A–E maintainability grade
charlie-work sarif -o out.sarif

3. As a CI gate — fail a PR only when it introduces new high-severity toil ("Clean as You Code"):

- uses: Falcon305/charlie-work-mcp@master
  with:
    severity: "4"

Trustworthy detection (not regex theater)

Every scanner is backed by a parser or an authoritative data source, and every finding carries a confidence tier (verified / high / heuristic) so CI gates on facts, not guesses.

Kind	How it's detected
vulnerable_dep	Lockfiles → OSV.dev (free, no key). Emits the CVE + the exact fixed version.
secret_leak	gitleaks-style provider regexes + Shannon-entropy gate + allowlists.
skipped_test / flaky_test / focused_test	Python AST and tree-sitter (JS/TS/Go) — never matches a string or a comment.
debug_leftover	AST calls: breakpoint(), pdb.set_trace, debugger, console.log.
dead_flag	Flags read but never set anywhere (the Pepe Silvia case), via AST literal extraction.
expiring_cert	Real X.509 parsing — .pem/.crt within 30 days of expiry, or already dead.
outdated_dep	Registry queries (PyPI/npm/crates/Go) → majors-behind.
todo_rot	TODO/FIXME/HACK in real comments, aged by git blame.
dependency_risk / unowned_runbook	Unpinned deps; operational scripts with no owner or CODEOWNERS.

The difference from regex, in one line: the Python string "pytest.mark.skip" and a # breakpoint() comment are not flagged. Only real code is.

Where your team actually bleeds — hotspots + a toil budget

Charlie ranks by churn × complexity (CodeScene-style): debt in a file edited 40× this quarter outranks the same debt in one untouched for years. charlie-work summary rolls it into a toil budget — total remediation minutes, a SQALE-style debt ratio, and an A–E grade. Google SRE says keep toil under 50%.

Agent-native tools

Tool	What it does
charlie_scan_toil	Prioritized, paginated toil queue (structured output).
charlie_summary	Toil budget: score, debt ratio, A–E grade.
charlie_triage	Top-N action plan for an agent to work through.
charlie_explain	Why a finding is debt — evidence, hotspot, owner, fix.
charlie_trend	Records a snapshot and reports the delta over time.
charlie_did_it / charlie_ledger	The credit ledger — who cleared what, Champion of the Grease Trap.

Plus a toil://queue resource and a triage_toil prompt. Things a dashboard can't do: "triage the top 3, explain why, and open PRs — then credit me in the ledger."

Not a toy: token discipline + evals

• The heavy work happens server-side. An agent finding this toil itself would read the whole repo into context; Charlie returns only a compact ranked queue. The raw files never enter the model's context.
• A reproducible eval harness (evals/run.py) plants known toil and asserts the end state — recall and ranking — plus a token-cost measurement. There's also an optional model-graded tool-selection eval (evals/agentic.py).

$ uv run evals/run.py
kinds recalled : 9/9  (100% recall)   top item is the cert : True
naive: read whole repo : 1881 tokens
charlie work queue     : 1353 tokens  →  28% fewer tokens
RESULT: PASS

That 28% is on a tiny fixture; the gap widens fast — naive cost grows with the repo, the queue stays bounded to one page.

Configuration & suppression

Zero-config to start. Tune via [tool.charlie] in pyproject.toml (or charlie.toml):

[tool.charlie]
exclude = ["vendor/**"]
disable = ["charlie/todo-rot"]
min_confidence = "high"
[tool.charlie.per-file-ignores]
"tests/**" = ["secret_leak"]

Plus inline # charlie: ignore[rule], a .charlieignore, and a committed baseline (charlie-work baseline) so a fresh install starts at "0 new."

Development

uv sync --extra dev
uv run ruff check . && uv run mypy && uv run pytest -q
uv run python evals/run.py

CI runs ruff + mypy(typed) + pytest + evals across Python 3.11–3.13. Releases publish to PyPI via OIDC Trusted Publishing.

The gang (roadmap)

Each ships as its own standalone MCP server: The Implication (auth & dark-pattern auditor), Pepe Silvia (dead-code tracer), The D.E.N.N.I.S. System (rollout comms planner).

License

Code: MIT. The hero image is a still from It's Always Sunny in Philadelphia (© FX Networks), used for identification and commentary; it is not covered by the MIT license. An original vector rendition ships at assets/hero.svg.