roxabi-sense

Workstation attention journal — light sensors, local store, agent surfaces.

Status: phases 1–3 live (collectors + store + CLI + daemon + MCP stdio) · NATS still stub
Not screenpipe. Not a web SaaS. Not inside roxabi-factory.
Agent SSOT: AGENTS.md · Claude shim: CLAUDE.md

Why

Screen capture + OCR is the wrong tool for “what was I doing?”.

You already have timestamped work in ~/.claude and ~/.grok. Meetings live in Claap. What is missing is a cheap focus spine: which app/window was active, which agent sessions were open, whether Slack/Discord was running — without pixels, keyloggers, or a 174 MB trial for 40 seconds of frames.

roxabi-sense is that spine. It publishes facts, not policy.

Related MCP server: Cortex

What it is / is not

Architecture (target)

  collectors (facts only)
  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐
  │ focus/idle  │  │ agent sessions│  │ process presence│
  │ (Wayland /  │  │ ~/.claude    │  │ slack/discord  │
  │  AT-SPI)    │  │ ~/.grok      │  │ (running?)     │
  └──────┬──────┘  └──────┬───────┘  └───────┬────────┘
         │                │                   │
         └────────────────┼───────────────────┘
                          ▼
                 local store (SQLite)
                 ~/.local/share/roxabi-sense/
                          │
          ┌───────────────┼────────────────┐
          ▼               ▼                ▼
        CLI             MCP              NATS (opt-in)
     day-slice      agent query    factory.event.host.*
     status         what_was_i…    activity | stale only

Boundary (ADR-091-aligned): sensors publish facts; roxabi-factory Sentinelle (hub module, not shipped yet) may consume host events and decide. This repo never opens Discord, never dispatches jobs, never applies ops policy.

Details: docs/ARCHITECTURE.md · purpose: docs/PURPOSE.md

Stack decision

Local daemon + CLI + MCP — not a Silex web boilerplate.

Install matrix

Data plane and query plane are separate: MCP does not start collectors. Empty/offline tools ⇒ fix the daemon, not the agent config.

Setup (PATH-stable)

Prefer a stable sense on PATH so agent configs never hardcode a worktree path.

# 1. clone (or pull) + install CLI + MCP deps into uv tool env
git clone git@github.com:Roxabi/roxabi-sense.git
cd roxabi-sense
uv tool install -e '.[mcp]'
# re-run after pull when the package changes:
#   uv tool install -e '.[mcp]' --force
# After PyPI release: uv tool install 'roxabi-sense[mcp]'

# 2. data plane — user systemd unit (not the same process as MCP)
sense install-service
systemctl --user enable --now roxabi-sense.service

# 3. smoke / DoD
sense doctor                  # FAIL if offline / no DB / MCP missing
sense status                  # last_tick should refresh while daemon is up
sense recap
which sense                   # typically ~/.local/bin/sense

# 5. optional NATS (when factory Sentinelle is ready)
#    sense config set nats.enabled true

MCP host registration (Grok + Claude)

Prereq: steps 1–3 above — which sense resolves, sense doctor is green (daemon + DB + MCP SDK). MCP does not start collectors; empty tools ⇒ fix data plane first.

Happy path: host spawns sense mcp from PATH — never a worktree absolute path.

Grok

User-global TOML (~/.grok/config.toml):

[mcp_servers.roxabi-sense]
command = "sense"
args = ["mcp"]
enabled = true

Or CLI (same result; user scope is default):

grok mcp add roxabi-sense -- sense mcp
grok mcp doctor roxabi-sense   # config + spawn smoke

Restart the Grok session (or open a new one) so the server is re-spawned.

Claude Code

CLI (preferred one-liner):

# workstation-wide (recommended for a host sensor)
claude mcp add -s user roxabi-sense -- sense mcp

# or project-local (writes/approves .mcp.json in the repo)
claude mcp add -s project roxabi-sense -- sense mcp

Project .mcp.json (equivalent shape):

{
  "mcpServers": {
    "roxabi-sense": {
      "command": "sense",
      "args": ["mcp"]
    }
  }
}

Project-scoped servers may show as pending approval until accepted in Claude. User scope avoids per-repo approval for a machine-local sensor.

Asymmetry (intentional): Grok stores servers in TOML (~/.grok/config.toml or project .grok/config.toml); Claude uses CLI scopes / .mcp.json JSON. Both spawn the same stdio command: sense + mcp.

After registration

sense doctor          # still green (host config is not a substitute for data plane)
sense status          # last_tick moving while daemon is up

Then ask the agent for tools (sense_status, active_now, what_was_i_doing, …). If tools are missing: restart the host session; if tools return offline/empty: fix daemon/sense doctor, not MCP JSON.

Hardening (optional)

Pin absolute binary if PATH is unreliable in the agent environment:

# Grok example — replace with real path from `which sense`
[mcp_servers.roxabi-sense]
command = "/home/YOU/.local/bin/sense"
args = ["mcp"]
enabled = true

Dev-only fallback (not for agent configs)

# contributor smoke — do not paste worktree paths into host MCP configs
uv run --extra mcp --directory /path/to/durable/clone sense mcp

Editable uv tool install -e must point at a durable clone (e.g. ~/projects/roxabi-sense), not a feature worktree. If you delete that worktree, sense breaks with ModuleNotFoundError — reinstall:

cd ~/projects/roxabi-sense   # durable path
uv tool install -e '.[mcp]' --force
sense doctor

Privacy / trust

• Default MCP redaction is coarse (no window titles / media tracks / full paths). Full detail only via operator config [mcp] detail = "full" — not tool-arg escalation (ADR-002).

• Agent spawn trusts the sense binary on PATH. Prefer operator-owned uv tool install over a world-writable clone.

• Only wire agents you trust with activity metadata.

Thin agent plugin (optional)

Optional DX package under plugins/roxabi-sense/ — wiring only:

# Same happy path as host snippets — plugin just packages it:
#   command = "sense"  args = ["mcp"]
# Manual still wins until marketplace publish:
grok mcp add roxabi-sense -- sense mcp
claude mcp add -s user roxabi-sense -- sense mcp

Requires roxabi-sense[mcp] on PATH (package ≥ 0.0.1 with MCP extra) and sense doctor green. Full plugin notes: plugins/roxabi-sense/README.md.

Contributor / in-tree workflow (not for host MCP config):

cd roxabi-sense && uv sync --extra mcp
uv run sense status

No Podman required on the laptop for V1. M₂ may use the same user unit. M₁ host-sensor path (services snapshot only) is a later collector, not a Quadlet of this whole app.

Roadmap (coarse)

Focus probes (multi-Linux)

Focus is one collector (kind=focus) with swappable FocusProbe backends. Fact field source is the backend id (atspi | x11 | wlr | kde | noop).

• AT-SPI — long-lived agent (system Python + gi); best on GNOME/Cosmic when a11y works.

• X11 — xprop / active window (XWayland fallback). Package: x11-utils.

• wlr — hyprctl activewindow -j or swaymsg -t get_tree when compositor env is set.

• kde — stub for now (probe() false until KWin D-Bus path lands).

• Runtime demote — if AT-SPI dies, daemon switches to next healthy probe without blocking other collectors.

• Meta focus: focus_backend, focus_status, session_type, desktop_family, last_focus_path.

• Meta idle: idle_backend, idle_status, idle_chain_reason (wayland → logind → noop).

Agent sessions (Grok / Claude / optional Cursor)

Cursor opt-in emits agent_sessions_snapshot with agent=cursor (workspace id + folder path + mtime only). Never opens chat DBs (state.vscdb), composer history, or rewrites agent dirs.

# ~/.config/roxabi-sense/config.toml
[collectors]
cursor_sessions = true
# cursor_root = "/home/you/.config/Cursor"   # optional override
# cursor_max_workspaces = 20
# cursor_max_age_days = 30

Agent status detail: AGENTS.md § Status.

Out of scope forever (for this repo): OCR, continuous screenshots, keylogging, clipboard dumps, scraping Slack/Discord desktop clients, meeting transcription, cloud upload of agent chat bodies.

Relation to the rest of Roxabi

License

AGPL-3.0-or-later (same family as roxabi-cortex).

Status

Phases 1–3 live (collectors, store, CLI, daemon, MCP stdio). Host registration: README § MCP host registration. NATS still open.