Keep Microsoft Teams showing as Available on a configurable work schedule — or at will. Cross-platform (macOS, Windows, Linux), JSON-configured, with a CLI and an interactive TUI, installable per-user or system-wide.
vigil config init # write a default config (Mon–Fri 08:00–17:00)
vigil doctor # check platform capabilities & permissions
vigil install # install + start the background service
vigil on --for 2h # at-will override; or `vigil off`, `vigil resume`
vigil # open the TUI dashboardTeams marks you Away after ~5 minutes of OS idle and immediately when the
screen locks. vigil runs a small background service that, during your active
schedule, keeps the session non-idle with one of two engines:
input(default) — injects tiny, periodic, human-like input that resets the OS idle timer. No accounts or admin needed.graph— sets a sticky preferred presence via the Microsoft Graph API. Cleaner, survives lock, but requires an Entra app and admin-consentedPresence.ReadWrite.
both runs them together. See the platform reliability notes below.
Teams: Available ──(~5 min OS idle, or screen lock)──► Away
vigil, during your schedule, keeps you Available:
input engine ─► periodic human-like HID activity resets the OS idle timer
Linux/Windows: reliable · macOS: keeps Teams green but
can't beat a hardware lock
graph engine ─► sets a sticky "Available" via Microsoft Graph
works through locks · needs admin-consented Presence.ReadWrite
both ─► run them together
manual override (on / off / for 2h / until 17:00) always wins over the schedule
| OS | Mechanism | Reliability | Notes |
|---|---|---|---|
| Linux | /dev/uinput virtual device (real kernel events) |
Highest | Needs uinput access; Teams on Linux is web/PWA. |
| Windows | SendInput (real small move / F15) |
High | Input engine installs as a logon Scheduled Task (a session-0 service can't inject). |
| macOS | CGEventPost + power assertion |
Good* | *Synthetic events can't reset the hardware idle timer, so a forced screen-lock still marks you Away. Keep Available by disabling/lengthening auto-lock, or use the graph engine. Requires Accessibility permission. |
The synthetic-input engine only works while a desktop session is unlocked. It cannot defeat a manual or policy-forced lock — that is what the
graphengine is for.
Download the binary for your platform from the
GitHub releases (vigil_<os>_<arch>,
e.g. vigil_macos_universal, vigil_linux_amd64), check it against the release's
checksums.txt, and let it install itself:
gh release download --repo simtabi/vigil --pattern vigil_macos_universal --pattern checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x vigil_macos_universal && ./vigil_macos_universal self install
vigil doctorThe GitHub release is the only channel: there is no package-manager or
go install path. GitHub lists no vigil release yet (checked 2026-11-13); until
the first one under the current release workflow is published, build from source.
To build from source you need Go (the version src/go.mod names), git and
make; macOS also needs the Xcode Command Line Tools, because the input backend
uses cgo.
git clone https://github.com/simtabi/vigil ~/src/vigil
make -C ~/src/vigil build # -> ~/src/vigil/build/<os>/vigil
~/src/vigil/build/macos/vigil self install # Linux: build/linux/vigil; copies it to ~/.local/bin
vigil doctorThen run vigil config wizard (or vigil config init) and vigil install.
Windows, verifying the attestation, pinning a version, updating, and the release
asset names are in docs/installation.md.
The input engine must be installed with --scope user (default, GUI
session); a system-wide service (--scope system) is intended for the graph
engine.
- Write a config:
vigil config wizard(guided: engine, tz, schedule, graph) orvigil config init(defaults, Mon–Fri 08:00–17:00). - Check the platform:
vigil doctorreports capabilities and permissions. - Install and start the background service:
vigil install(vigil install --initwrites a default config first if none exists).
The graph engine also needs graph.client_id set before engine can be
switched to graph or both; see tools/graph-engine.md.
vigil on --for 2h # at-will override; or `vigil off`, `vigil resume`
vigil status # service + daemon state
vigil # open the TUI dashboardvigil schedule add --days Mon,Tue,Wed,Thu,Fri --start 08:00 --end 17:00
vigil config set engine bothThe full configuration walkthrough is in docs/configuration.md; service control is under The daemon, and everything else is in the documentation table.
A release install updates with vigil upgrade (docs/updating.md).
Update a source build from git:
git -C ~/src/vigil pull --ff-only
make -C ~/src/vigil build && ~/src/vigil/build/macos/vigil self install # Linux: build/linux/vigil
vigil restart # if the background service is installedvigil upgrade (self-update from GitHub releases) is still in the binary, but
it finds nothing newer than 0.7.0; see docs/updating.md.
vigil install --init # turnkey: write a default config if needed, install + start the service
vigil status # service + daemon state
vigil restart # restart after config changes (config is also hot-reloaded)
vigil stop / vigil start
vigil uninstall # stop + remove the service (keeps the binary)Remove everything (service + binary, --purge also deletes config/data):
curl -fsSL https://raw.githubusercontent.com/simtabi/vigil/main/src/scripts/uninstall.sh | sh
# or: vigil self uninstall --purge| Page | What it covers |
|---|---|
| installation.md | Building, installing, scope, and the per-OS service mechanism |
| configuration.md | The config.json schema, schedules, overrides, and file locations |
| tui.md | The interactive menu UI — navigation, screens, and editor keys |
| cli.md | CLI conventions — flags, prompts, color, exit codes, env vars |
| brand.md | The eye mark, brand assets, banner, and regenerating icons |
| architecture.md | Engines, the daemon loop, control plane, and design decisions |
| tools/input-engine.md | The synthetic-input engine and its per-OS behavior |
| tools/graph-engine.md | The Microsoft Graph engine, Entra app setup, and admin consent |
| updating.md | Self-update (vigil upgrade), package managers, and caveats |
| release.md | Tag-driven release & packaging process |
All actions are available from both the CLI and the interactive TUI (vigil on a
terminal): live status, overrides, schedule & settings editors, service control,
auth, and updates. Configure non-interactively with vigil config set <key> <value>
and vigil schedule add/list/remove.
vigil is a personal-productivity tool. The input engine is dual-use
(equivalent to a "mouse jiggler"/Caffeine). Respect your employer's policies
and applicable agreements — presence is often used by colleagues to gauge
availability. Don't use this to misrepresent working hours where that would
breach policy. You are responsible for how you use it.
MIT © 2026 Simtabi LLC. See LICENSE.