projects / 06
tinker
human-in-the-loop diagnostic agent
A Windows CLI agent that diagnoses and fixes performance issues. It runs gpt-oss-20b on Groq in a tool-calling loop: ten read-only tools read CPU, RAM, disk and thermal sensors, map listening ports to processes, audit startup programs and scan for Docker, Windows and project bloat. Only two tools can change anything, and both go through a gatekeeper.
how it works
- 01
Ask
Run tinker diagnose with a question, or tinker chat for a session that keeps context between questions.
- 02
Investigate
gpt-oss-20b on Groq runs a tool-calling loop over ten read-only tools: CPU, RAM and disk stats, top processes, listening ports mapped to PIDs, battery and CPU frequency, startup programs from the registry, and scanners for developer caches, Docker, Windows and project bloat.
- 03
Propose
To change anything the model must call clean_cache or terminate_process. The loop intercepts both instead of running them.
- 04
Approve
The spinner stops and a prompt shows the target, expected recovery and risk level. Nothing runs unless you answer y; the default is no.
- 05
Execute and report
Approved actions go through the executor, which applies its own guards, and the model reports what it observed, what it did and the new state.
design decisions
Two mutating tools only
The model can't modify the registry, uninstall apps or change settings. For anything outside cleanup and process kills, it is told to give manual steps instead.
Guards outside the model
The executor refuses protected Windows processes, PIDs up to 4 and paths too close to the drive root, even if the model asks for them.
Recoverable deletes
Files are moved to the Recycle Bin with send2trash, and Docker cleanup uses the daemon's own prune calls.
highlights
- The loop intercepts both mutating tools and asks [y/n] before anything is cleaned or killed
- Hard blocklist for critical Windows processes (explorer, svchost, lsass…) and PIDs ≤ 4
- Files go to the Recycle Bin via send2trash; paths too close to the drive root are refused
- Docker cleanup only prunes dangling images, stopped containers and unused volumes
known limitations
- Windows only.
- Reasoning runs on Groq, so it needs an API key and an internet connection; the tools themselves run locally.
stack
- python
- groq
- gpt-oss-20b
- psutil
- typer
- rich
- docker sdk