tool-clean: a declarative and observable approach to monitor management
When dealing with system configuration, I tend to prefer explicit control over automation.
This is especially true in IT environments, where:
- predictability matters more than convenience
- implicit behavior becomes technical debt
- “magic” often hides responsibility rather than reducing it
With that mindset, I built tool-clean.
What tool-clean is (and is not)
tool-clean is a CLI tool written in Python for observable and declarative monitor management.
It allows you to:
- observe connected monitors
- identify them in a stable way
- assign human-readable labels
- declare usage profiles
- associate profiles to monitors
- persist everything locally
- audit all mutating actions
What it does not do:
- it does not apply system configurations
- it does not change brightness or resolution
- it does not interact with drivers or OS APIs
- it does not make autonomous decisions
This is intentional.
The design philosophy
tool-clean is built around a few non-negotiable principles:
- Human control is explicit
- Observation is separate from intention
- Declaration is separate from execution
- Nothing happens implicitly
- Everything relevant is audit-visible
In practice, this means the tool never “reacts” to state.
It only records and exposes it.
Why not automate?
Automation is powerful, but it comes with costs:
- hidden assumptions
- unclear responsibility
- difficult audits
- fragile edge cases
In many IT contexts, the real need is not automation, but clarity.
tool-clean is meant to be a foundation:
- something an IT operator can reason about
- something you can inspect and revoke
- something that does not surprise you six months later
How it works (conceptually)
- The system observes the real state (connected monitors)
- The user declares a profile (an intention, not an action)
- The user associates that profile to a monitor
- The state is persisted and audited
- Any real application happens outside the tool
The tool remains read-only with respect to the operating system.
Technical overview
- Python 3.10+
- CLI-first (not a library)
- Local-only execution
- SQLite for persistence
- Append-only audit log (INFO / WARN / SECURITY)
- No network dependencies
- No background services
The project uses a clean src/ layout and a strict separation between:
- CLI parsing
- domain commands
- observed state
- persistence
Current scope: Base v2
The current public release is Base v2.
It is intentionally limited:
- no centralized management
- no federation
- no policy enforcement
- no automatic configuration application
Those ideas may belong to future versions, but not to the base.
Base v2 is meant to be:
- stable
- inspectable
- defensible
Repository
The project is open source (MIT licensed):
https://github.com/Vanni7544/tool-clean
The repository includes:
- full documentation
- a canonical source snapshot
- clear contribution guidelines
- a defined security policy
Closing thoughts
tool-clean is not meant to be flashy.
It is meant to be:
- boring in the right way
- predictable
- explicit
- safe to reason about
If you’re interested in tools that favor clarity over automation,
this project might resonate with you.
Technical feedback is welcome.
Top comments (0)