# Pachakutech Presence — an MCP Binding for the Presence Layer

Not another agent harness. A **Presence Layer**: a small, typed, policy-gated
set of actions — Manifestations — through which an agent can put sensory
stimuli directly into your UI instead of only describing it in text. This
package is the MCP Binding: the same substrate also binds to AppFunctions on
Android and App Intents on iOS, but this is the one that runs on your
desktop, today, against whatever agent you're already running.

## Install

```
npm install -g @pachakutech/presence-mcp
presence setup claude
```

`presence setup claude` runs `claude mcp add presence -- presence mcp` for
you. For Codex, `presence setup codex` does the equivalent. On Omarchy
specifically, see [`docs/omarchy.md`](docs/omarchy.md) for a one-line install
via `omarchy-mise-install`.

Run `presence doctor` any time to check what this machine can support —
today that's informational only (see below), but it's the same check the
native daemon will depend on once it exists.

## What it exposes

| Tool | Pattern | Does |
|---|---|---|
| `manifestHighlight` | ephemeral | Highlights described on-screen content for N seconds |
| `spawnPresence` | instanced (1/3) | Spawns a persistent audio-visual presence derived from context (optionally from a held artifact), returns a `presenceId` |
| `animatePresence` | instanced (2/3) | Feeds new content to a spawned presence |
| `retirePresence` | instanced (3/3) | Ends a presence and frees its slot |
| `addArtifact` | instanced (1/2) | Adds a Gaussian splat cloud (or other content asset) to the substrate as reference material — held, not rendered directly, for `spawnPresence` to build from |
| `retireArtifact` | instanced (2/2) | Removes a held artifact and frees its slot |

Full schemas are in [`src/index.ts`](src/index.ts); the reasoning behind the
ephemeral/instanced split, why artifacts are a separate registry from
presences, and why the tool *list* stays fixed while what each tool generates
stays wide open is in [`skills/presence/SKILL.md`](skills/presence/SKILL.md).

## Where this runs, and what it needs access to

The MCP server is **local** — spawned as a subprocess of your agent CLI, on
your machine, over stdio. There is no cloud round-trip and nothing to
authenticate; the same reason this differs architecturally from something
like Astra is that there's no server to stand up and no session to hand
over. Because your agent CLI runs inside your own logged-in desktop session,
the MCP server it spawns inherits that session's environment automatically —
`WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR`, `DBUS_SESSION_BUS_ADDRESS` — with no
separate setup step, unlike a systemd service, which would need its
environment imported explicitly.

**Today**, none of that matters yet — `src/daemonStub.ts` only calls
`notify-send` and appends to a log file, so the only real dependency is
Node.

**Once the native daemon exists** (see `docs/architecture.md`), it will need
two more things, both standard on a modern desktop session and checked by
`presence doctor`:
- **GPU access**, via the DRM render node (`/dev/dri/renderD128`) — for
  Vulkan. On most current distros this is granted automatically to whoever
  is logged in at the console, through `systemd-logind`'s dynamic ACLs, not
  through group membership. If it isn't, adding your user to the `render`
  group fixes it.
- **Webcam access**, via `/dev/video*` — gated by the `video` group on most
  distros. Desktop users are typically in this group already; worth knowing
  explicitly, since a missing webcam permission fails silently rather than
  with a clear error.

Neither requires root, a privileged daemon, or a setup wizard — just the
ordinary permissions of an interactively logged-in desktop user.

A packaging note: this has no dependency on Arch/pacman specifically, or on
any particular init system. If Omarchy's packaging base changes, none of the
above changes with it — Hyprland has full first-class support under NixOS
and Home Manager as of today, so a Nix-based Omarchy would run this exactly
the same way.

## What's real vs. stubbed right now

The MCP surface — schemas, the Policy Gate, tool registration, and now the
`presence` CLI itself — is real and runnable today, on any machine with
Node. The rendering underneath each Manifestation is currently a stand-in
(`src/daemonStub.ts`): a desktop notification plus a structured log, standing
in for a native Vulkan daemon that doesn't exist yet. That daemon —
zero-copy webcam/screen ingress via `dma_buf`, output composited through
`wlr-layer-shell` — is a small, separate build, described in
`docs/architecture.md`. The boundary between the two is deliberate: the
daemon owns the GPU, the MCP layer owns the contract, and they talk over a
small, typed protocol rather than sharing buffers directly. Swapping the
stub for the real daemon changes nothing above that boundary.

## Why this exists

Every agent CLI today speaks fluently in files, shells, and text. None of
them have a vocabulary for situational presence — putting something *into
the user's perception* — a highlight, a persistent character, a spatial cue
— governed by the same kind of explicit, inspectable contract you'd expect
from any other tool call. This is that vocabulary, built as an open MCP
server rather than a pitch deck, because the fastest way to have this
conversation with anyone is to hand them something that already runs.

MIT licensed. Contributions and forks welcome.