OS Context

A fast macOS & Linux CLI that prints a single JSON object describing your current local context for agents. Privacy-respecting, read-only, no network calls to external services.

OS Context gives AI agents a quick, local snapshot of your machine (app, window, clipboard, battery, network, etc.) so they can give context-aware answers without screenshots or daemons. Sensitive data is opt-in; default output is minimal and private.

Goals

• Single command: context outputs JSON to stdout.
• Fast: Target <300ms typical; local-only, no external network.
• Read-only: No daemon, no always-on logging.
• Privacy: No screenshots, keystrokes, microphone/camera, or recording.
• Clear permissions: Only request macOS permissions when you use the matching flag (e.g. --frontmost-window, --calendar).
• Feature flags: Sensitive data (clipboard, window title, calendar, reminders) is opt-in.

Install

Run without installing (npx):

npx os-context --pretty

Use the package name os-context with npx; the command is then context inside the package.

Install globally (get context in your PATH):

npm i -g os-context
context --pretty

From source:

git clone https://github.com/treadiehq/os-context.git && cd os-context
npm install && npm run build
./node_modules/.bin/context --pretty
# or: npm link  then  context --pretty

Usage

Default (safe core context only):

npx os-context
# or, after global install:  context

Pretty-print with frontmost window and clipboard, redact sensitive fields:

npx os-context --pretty --frontmost-window --clipboard --redact

All optional features and debug timings:

npx os-context --pretty --clipboard --frontmost-window --apps \
  --battery --network --calendar --reminders \
  --redact --debug

Options

| Flag | Description | |------|-------------| | --pretty | Pretty-print JSON. | | --clipboard | Include clipboard text (and types). | | --frontmost-window | Include frontmost window title (requires Accessibility). | | --apps | Include list of running apps (name, bundle_id, pid). | | --battery | Include battery percentage and charging state. | | --network | Include primary interface, SSID, local reachability. | | --calendar | Include next calendar events (requires Calendar permission). | | --reminders | Include reminders (requires Reminders permission). | | --redact | Redact sensitive strings; output SHA-256 + length only. | | --timeout-ms <n> | Per-module timeout in ms (default 250). | | --debug | Include per-module timings in _debug.timings_ms. |

Exit codes

• 0 — Success.
• 2 — Required permission missing (e.g. Accessibility or Calendar denied).
• 3 — Timeout.
• 4 — Other error.

JSON is always printed, even when exit code is non-zero.

Platform support

• macOS: Full support. Calendar and Reminders are macOS-only (AppleScript).
• Linux: Host, frontmost (X11 via xdotool), apps (ps), clipboard (xclip or xsel), battery (/sys/class/power_supply), network (ip, iwgetid). Window title on Linux requires X11; on Wayland xdotool may not work. Calendar/Reminders return empty on Linux.
• Optional Linux deps: xdotool (frontmost/window), xclip or xsel (clipboard), iwgetid (WiFi SSID).

Permissions

• Default run does not require Accessibility, Calendar, or Reminders. It only reads OS version, machine, locale, timezone, and frontmost app name/bundle ID.
• Accessibility (macOS) is only needed for --frontmost-window (to read window titles).
• Calendar / Reminders (macOS) are only used when you pass --calendar or --reminders.

See docs/permissions.md for details and troubleshooting.

Output schema

See docs/schema.md for the full JSON schema. Top-level keys include schema_version, generated_at, host, frontmost, optional apps, clipboard, battery, network, calendar, reminders, permissions, warnings, errors, and optionally _debug.

OpenClaw skill

An OpenClaw skill is included so the agent can fetch machine context when needed. OpenClaw loads skills as directories named after the skill containing SKILL.md (see Skills).

Install the skill:

• Managed (shared): mkdir -p ~/.openclaw/skills/os-context && cp openclaw-skill/SKILL.md ~/.openclaw/skills/os-context/
• Workspace (per-agent): from your OpenClaw workspace, mkdir -p skills/os-context && cp /path/to/os-context/openclaw-skill/SKILL.md skills/os-context/
• ClawHub: if published on ClawHub, from your workspace run clawhub install <slug>.

The skill teaches the agent to run npx os-context (or context if installed globally) with appropriate flags and use the JSON to answer questions about what you're doing, battery, calendar, reminders, etc.

Development

npm run dev -- --pretty
npm run build
npm test

License

FSL-1.1-MIT