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.
Pick whichever fits (full details in docs/installation.md):
# Script (macOS/Linux) — downloads + checksum-verifies the prebuilt binary
curl -fsSL https://raw.githubusercontent.com/simtabi/vigil/main/scripts/install.sh | sh
# …or in one shot, also configure + install + start the background daemon:
curl -fsSL https://raw.githubusercontent.com/simtabi/vigil/main/scripts/install.sh | sh -s -- --with-service
# Homebrew (macOS/Linux)
brew install simtabi/tap/vigil
# Scoop (Windows, PowerShell)
scoop bucket add simtabi https://github.com/simtabi/scoop-bucket; scoop install vigil
# Debian/Ubuntu or RHEL — grab the .deb/.rpm from the latest release, then:
sudo dpkg -i vigil_*_amd64.deb # or: sudo rpm -i vigil_*_amd64.rpm
# Go toolchain (Windows/Linux; macOS needs a C compiler for cgo)
go install github.com/simtabi/vigil/cmd/vigil@latestOr download a prebuilt archive from the releases page,
or build from source (go build -o vigil ./cmd/vigil). Then run vigil config wizard
(or vigil config init) and vigil install.
Which download? (assets are named vigil_<os>_<arch> — macOS uses the friendly
macos token; self-update matches automatically):
| Your machine | Asset |
|---|---|
| macOS — any (Apple Silicon or Intel) | vigil_macos_universal.tar.gz |
| macOS — Apple Silicon only | vigil_macos_arm64.tar.gz |
| macOS — Intel only | vigil_macos_amd64.tar.gz |
| Windows 64-bit / 32-bit / ARM | vigil_windows_amd64.zip / _386 / _arm64 |
| Linux 64-bit / 32-bit / ARM64 / ARMv7 | vigil_linux_amd64.tar.gz / _386 / _arm64 / _armv7 |
(Also: riscv64, ppc64le, s390x, and FreeBSD/OpenBSD/NetBSD.)
The input engine must be installed with --scope user (default, GUI
session); a system-wide service (--scope system) is intended for the graph
engine.
vigil upgrade # self-update to the latest release (verifies checksum)
vigil upgrade --check # just report whether an update is availablevigil upgrade only manages standalone installs; if you installed via Homebrew,
Scoop, or a system package it tells you to use that manager instead. 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/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.