HealControl

I made HealControl for an IBM hackathon on 30 and 31 January 2026, in a team of four. It was another hackathon for me, and I had fun taking part and working with my teammates. We didn't win. It did run from start to finish though, and I recorded a video of it for the hackathon and put it on LinkedIn.

An AI assistant is good at reading code and suggesting a fix. What it can't do on its own is touch your computer: run your tests, change a file, save the result. HealControl is the part that lets it. It offers the assistant twelve actions, things like "run the tests", "read this file", "write this file" and "open a pull request", and the assistant decides which to use and in what order. If you want a comparison, the assistant is the mechanic and HealControl is the toolbox. The toolbox decides what the mechanic can reach.

I wrote the server and the instructions the assistant follows, which tell it to act like an on-call engineer: find the failure, fix it, check the fix, no chatter. Teammates set up the demo scenarios.

The demo is one tiny program with a deliberate bug. A function is supposed to take 20 percent off a price of 200 and give 160. Instead it subtracts 20 and gives 180. Three small tests check this, and all three fail. The assistant runs them, sees the failures, reads the file, asks an IBM language model called Granite for a second opinion, rewrites the line and runs the tests again. If they pass, it saves the change on a separate copy of the code and opens a pull request on GitHub, which is the proposal a human then reviews.

Not everything about it held up. The first version used IBM's own software library to talk to Granite, which was slow to start, so I replaced it with plain web requests. For a while the commands that save and push the change ran in the wrong folder, and I only fixed that on the last evening. I called it local-first, and that is only half true: when the assistant asks Granite for a diagnosis, the test output goes to IBM. And the rules are mostly just words. The assistant is told never to edit the tests, but nothing in the toolbox stops it. The one workflow rule the code enforces is that it won't push a change while the tests are failing.

The demo ran end to end on that toy program, and that is the only thing I have run it on. I have no success rate to show you, just the one recording. It also acts without asking first, which is fine for a toy bug and not for anyone's real code.

What's next. It did its job as a hackathon demo. Before it goes near real code it needs a step that asks before writing anything, and a lock on the test files.

HealControl is a Model Context Protocol server I wrote on 30 and 31 January 2026 for an IBM hackathon, in a team of four. It was another hackathon for me, and I had fun taking part and working with my teammates. We didn't win. The loop did run end to end on the demo app, and I recorded a video of it for the hackathon and posted it on LinkedIn.

The latest version is on the dev branch of the repo. It is a demo, not a product.

What I wanted

I wanted the assistant to work like an on-call site reliability engineer: run the tests, read the file, change it, run the tests again, and only then commit. Each step is a tool exposed over MCP, so any client can drive the loop itself. The server stays thin: each tool does one thing and returns plain text, and the agent does the thinking.

What is MCP?

The Model Context Protocol is a standard way for an AI application to call tools that live somewhere else. A server announces a list of tools with names, arguments and descriptions, and the client's model decides when to call them. It means one server can work with several assistants, for example IBM Bob or Claude Desktop, without a separate integration for each.

How it works

One Python file, src/server.py, runs a FastMCP server over stdio and registers 12 tools. Five of them run a subprocess (pytest, git or the GitHub CLI), four read or write files in the app folder, two handle configuration, and analyze_with_watsonx is a REST call. A small healcontrol.json lists the apps the server may work on and which one is active. Only the demo app is in it.

What does stdio mean here?

The client starts the server as a child process and the two talk through its standard input and output, as lines of JSON. There is no network port and no login. That is why setup is one line in a VS Code config file, and also why the server runs with the same permissions as whoever launched it.

What the 12 tools touch.

Kind	Tools
Run a subprocess (5)	check_pipeline_status, verify_fix, create_git_branch, commit_fix, push_to_cloud
Read or write files (4)	list_files, read_code_file, apply_surgical_fix, reset_broken_app
Configuration (2)	list_apps, set_active_app
Call IBM over REST (1)	analyze_with_watsonx

On the dev branch the prompt asks the agent to detect, read, diagnose with Granite, fix, verify, then branch, commit and push. It also tells it to speak like a senior SRE, to be brief, not to ask permission, and never to modify test files. main still has an older prompt without the diagnose and push steps.

What are IBM watsonx and Granite?

Granite is IBM's family of language models, and watsonx.ai is IBM's hosted service for running them. The server fetches a token with an API key, caches it for the life of the process, and posts the failing test output to the chat endpoint, asking for four labelled fields: root cause, fix suggestion, confidence and explanation. It uses granite-4-h-small with a temperature of 0.2 and a 500 token cap.

The loop, step by step

The server doesn't run the loop. The agent does, using the order in the prompt, and it can skip or repeat steps. Here is the order the prompt gives it, with what each tool really returns.

The demo bug

The demo app is one function. calculate_discount subtracts the percentage from the price instead of taking a percentage of it. Three tests define correct behaviour, and all three fail on the buggy version. The fix is a single line.

The demo's three tests. "Buggy" is price - discount_percent, worked out by hand. "Fixed" is price - (price * discount_percent / 100).

Test	Expected	Buggy returns	Fixed returns
200 at 20%	160	180	160
50 at 10%	45	40	45
75 at 100%	0	-25	0

What didn't work

The watsonx SDK. The first version used IBM's Python SDK with Granite 3.3. It was slow to initialise, so I switched to plain REST calls with a cached IAM token and moved to Granite 4.

Git in the wrong folder. Branch, commit and push were running from the demo app's folder instead of the project root. I moved all of them to the project root on the last evening.

The "local" claim. I described it as running locally with no code leaving the machine except the push. That isn't true when analyze_with_watsonx is used: it sends the pytest output, tracebacks included, to IBM. And whatever model runs the client sees every tool result anyway.

Rules only in the prompt. The prompt says never edit tests, but apply_surgical_fix will overwrite any file in the app folder, tests included, and commit_fix stages everything. The one workflow rule the code enforces is in push_to_cloud:

    test_result = _run(_build_test_cmd(), cwd=PROJECT_ROOT)
    if test_result.returncode != 0:
        return (
            "Refusing to push: tests are failing. Fix the tests first.\n\n"
            + _extract_failures(test_result.stdout + test_result.stderr)
        )

What does the path check do?

Every file name the agent passes is joined onto the app folder, resolved to an absolute path, and rejected if it ends up outside that folder, for instance with ../. Without it, an agent, or a prompt injected into a file it reads, could read or overwrite anything the server's user can. It stops that. It doesn't stop the agent from editing a test file inside the folder.

Emergency mode. For demo day we planned a fallback: if GitHub went down, the server would use a fake failure log in src/mock_data.py. The fallback log never got wired in: the mock failure data sits unused on the main branch, so it was a plan, not a feature.

What is unfinished

It only targets the demo app. The multi-app config exists, but only the demo app is in it, and I never wrote tests for the server itself. The only record of a full run is the video from the hackathon. I have no success rate and no log of what Granite replied. The agent also acts without asking for approval, which is fine for a toy bug and not for real code. What it needs first is an approval step before any write, and a lock on test files that lives in the code instead of the prompt.