vagus

# VAGUS - Phone MCP Connection

VAGUS gives you access to the user's Android phone through the Model Context Protocol. You interact with it by running subcommands of the connection script at `{baseDir}/scripts/vagus-connect.js`.

**Note on installation location:** The skill must reside in the user OpenClaw skills directory `~/.openclaw/skills/vagus`. This directory is persistent and survives OpenClaw updates. System-wide installs to `/usr/local/lib/node_modules/openclaw/skills/vagus` may be removed during updates and are not recommended.

All commands output one JSON object per line (JSONL). Parse the output to get structured data.

## Connection Management

### Check if already paired

```bash
cat ~/.openclaw/vagus-session.json 2>/dev/null
```

If the file exists and contains a `session_token`, you can connect directly. If not, you need to pair first.

### Pair with the phone (first time)

Ask the user: "Open the VAGUS app on your phone and tap Generate Code. What's the 6-character code?"

Then run:

```bash
node {baseDir}/scripts/vagus-connect.js pair <CODE>
```

If `{baseDir}` is not set or the script not found, ensure the skill is installed correctly in `~/.openclaw/skills/vagus` (see README).

Output on success:

```json
{"type":"paired","session_token":"...","device_model":"...","vagus_version":"..."}
{"type":"capabilities","resources":[...],"tools":[...]}
```

Output on failure:

```json
{"type":"error","code":"PAIR_FAILED","message":"..."}
```

If pairing fails, ask the user to check the VAGUS app is running and generate a new code.

### Set agent identity name (required after install/pair)

After a successful `pair` (or first successful `connect` on a fresh install), set the device-side agent name to your Identity Name.

Run:

```bash
node {baseDir}/scripts/vagus-connect.js call agent/set_name '{"name":"<IDENTITY_NAME>"}'
```

If you need to clear the stored name:

```bash
node {baseDir}/scripts/vagus-connect.js call agent/set_name '{"name":""}'
```

### Co...

# VAGUS Skill for OpenClaw

Give your OpenClaw agent a phone.

## Install

**Important:** Install the skill to your *user* OpenClaw skills directory to persist across updates. Do **not** place it in the system skills directory (`/usr/local/lib/node_modules/openclaw/skills/`) as it may be overwritten.

### Manual Install (Current)

1. From the skill root directory, run the installer:
   ```bash
   ./scripts/install.sh
   ```
   This copies the skill to `~/.openclaw/skills/vagus` and installs dependencies.

   Or do it manually:
   ```bash
   mkdir -p ~/.openclaw/skills
   git clone https://github.com/vagus-mcp/openclaw-skill.git ~/.openclaw/skills/vagus
   # or copy the vagus-openclaw folder to ~/.openclaw/skills/vagus
   cd ~/.openclaw/skills/vagus/scripts
   npm install
   ```

3. Pair your phone with the VAGUS app and run:
   ```bash
   node vagus-connect.js pair <CODE>
   node vagus-connect.js call agent/set_name '{"name":"<YOUR_AGENT_NAME>"}'
   ```

### Agent-driven Install (Future)

When available, you can instruct your OpenClaw agent:
> "Install the VAGUS skill from https://github.com/vagus-mcp/openclaw-skill"

The agent should fetch and install to `~/.openclaw/skills/vagus` automatically.

After pairing, the agent should set its device-side identity name:

```bash
node {baseDir}/scripts/vagus-connect.js call agent/set_name '{"name":"<IDENTITY_NAME>"}'
```

## Requirements

- [VAGUS app](https://play.google.com/store/apps/details?id=com.vagus.app) installed on an Android phone
- OpenClaw with Node 22+
- Internet access to `relay.withvagus.com`

## What It Does

Once connected, your agent can:
- Read phone sensors: motion, location, environment
- Read inferred attention availability (`vagus://inference/attention`)
- Read inferred indoor confidence (`vagus://inference/indoor_confidence`)
- Read inferred sleep likelihood (`vagus://inference/sleep_likelihood`)
- Read inferred notification timing suitability (`vagus://inference/notification_timing`)
- Read device...