Charlie Work

A code-health tool that surfaces — and dignifies — the toil in your repo. An MCP server and a CLI and a CI gate.

The un-fun, load-bearing maintenance work everyone ignores until it bites: flaky tests, a TLS cert nine days from death, known-vulnerable dependencies, committed secrets, dead feature flags, TODO rot, scripts nobody owns. Charlie Work scans your repo with real parsers and real vulnerability data, ranks the findings by where your team actually bleeds time, and keeps a credit ledger so the invisible work finally shows up in standup.

Named after the episode where the gang realizes Charlie has been quietly holding Paddy's together the whole time.

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.

Use it with any agent

Charlie is a stdio MCP server, so it drops into every MCP client — Claude Code, Codex, Cursor, VS Code, Claude Desktop, Windsurf, Zed, Gemini, Cline. The universal config is one block:

{
  "mcpServers": {
    "charlie-work": { "command": "uvx", "args": ["charlie-work-mcp"] }
  }
}

Don't hand-write it — let Charlie wire himself in:

uvx --from charlie-work-mcp charlie-work install --client cursor --write   # or: codex, claude-code, vscode, …

install knows each client's dialect and prints (or, for project-local clients, --writes) the exact config. Run install --client all to see every one.

Claude Code — claude mcp add --transport stdio charlie-work -- uvx charlie-work-mcp (or the block above in .mcp.json).

OpenAI Codex CLI — ~/.codex/config.toml:

[mcp_servers.charlie-work]
command = "uvx"
args = ["charlie-work-mcp"]

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Windsurf, Gemini CLI, Cline — the universal mcpServers block above.

VS Code — .vscode/mcp.json uses servers (not mcpServers):

{ "servers": { "charlie-work": { "type": "stdio", "command": "uvx", "args": ["charlie-work-mcp"] } } }

Zed — settings.json uses context_servers:

{ "context_servers": { "charlie-work": { "source": "custom", "command": "uvx", "args": ["charlie-work-mcp"] } } }

Teach every agent the drill — write a Charlie section into AGENTS.md (the cross-vendor rules file read by Codex, Cursor, Copilot, Gemini, Aider, Windsurf, Zed; Claude reads it too):

uvx --from charlie-work-mcp charlie-work init

As a CLI:

uvx --from charlie-work-mcp charlie-work scan     # the prioritized toil queue
charlie-work next                                 # the single next best fix, as a patch
charlie-work fix --top 5 | git apply              # patch the safe ones
charlie-work summary                              # toil budget + A–E grade

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"

As a scheduled watchman — some toil is time-based: a cert quietly ticks toward expiry, a TODO ages, a new CVE lands against a dep you already shipped. A nightly scan catches it before it pages you:

on:
  schedule: [{ cron: "0 7 * * *" }]
jobs:
  charlie:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: uvx --from charlie-work-mcp charlie-work sarif -o charlie.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with: { sarif_file: charlie.sarif }

Until the PyPI release lands, replace uvx charlie-work-mcp with uvx --from git+https://github.com/Falcon305/charlie-work-mcp charlie-work-mcp (and likewise --from git+… for the CLI).

Related MCP server: skillhub

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.

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

Not just a reporter — a doer

Charlie returns patches, not prose. charlie_next hands the agent the single highest-value item — where it is, why it matters (hotspot × severity), and a ready-to-apply unified diff when it's safely fixable:

$ charlie-work next
breakpoint() left in the code at pay.py:88 — severity 4, in a hotspot (2.1x). [auto-safe]
--- a/pay.py
+++ b/pay.py
@@ -85,7 +85,6 @@
-    breakpoint()

Every patch is a diff you (or CI) apply with git apply — the server never edits your files. Fixes are labelled auto-safe (mechanical: delete a breakpoint()) or needs-review (changes behaviour: un-skip a test, delete a stale TODO). Secrets, certs, and dependency bumps are surfaced for a human, never auto-patched.

Plus toil://queue + toil://item/{id} resources and four prompts (slash commands in any client): triage_toil, fix_next, pre_pr_check, charlie_rules. Things a dashboard can't do: "fix the next thing, run the tests, and 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.