# Install Awareful, for agents

You are an AI agent (Claude Code, Codex, Cursor or similar) and a person asked you to set up Awareful on their Mac.
Follow these steps in order. Every step is safe to run again: check first, and skip what is already done.

Awareful has two parts:

- **Awareful Desk**, a Mac app. It keeps your sessions in sync and passes your questions and approval requests to the person's phone.
- **Awareful** (知在 in Chinese), the iPhone app the person answers from.

## Ground rules

- **Show before you write.** For every change to the person's config, run the plan or dry-run first. Tell the person in plain words which files change and how. Write only after they say yes.
- **Never approve on the person's behalf.** Approvals belong to them. The hooks you install only forward requests to their phone.
- **Touch only user-level config.** Do not edit any project repository, and do not edit a project's `AGENTS.md` or `CLAUDE.md`.
- **No secrets.** Installing needs no API key, token or password. If anything asks you for one, stop and ask the person.
- **Stop on conflicts.** If a plan lists `conflicts` (for example an `awareful` server Awareful did not install), stop. Let the person choose between replacing it and cancelling.

## 1. Check the Mac

```bash
uname -m                 # must print arm64: Desk runs on Apple silicon only
sw_vers -productVersion  # must be 14.0 or later
ls -d "/Applications/Awareful Desk.app" 2>/dev/null && echo "Desk is installed"
```

If the first two checks fail, stop and tell the person Desk cannot run on this Mac.
If Desk is already installed, skip to step 3. People can also download it by hand from https://awareful.com/desk.

## 2. Install Awareful Desk

```bash
dir=$(mktemp -d)
curl -fL -o "$dir/Awareful-Desk.dmg" https://downloads.awareful.com/desk/Awareful-Desk.dmg
hdiutil attach -nobrowse -readonly -mountpoint "$dir/mnt" "$dir/Awareful-Desk.dmg"
spctl -a -vv -t exec "$dir/mnt/Awareful Desk.app"
```

`spctl` must say `accepted`, `source=Notarized Developer ID` and `origin=Developer ID Application: ... (PFYT4RQFC6)`.
If it does not, stop: do not install the app, and tell the person.

Ask the person before copying, because it adds an app to `/Applications`:

```bash
ditto "$dir/mnt/Awareful Desk.app" "/Applications/Awareful Desk.app"
hdiutil detach "$dir/mnt"
open "/Applications/Awareful Desk.app"
```

Desk updates itself from then on. The person does not need this page again for updates.

## 3. Pair the phone

This step is for the person; you only check it.

1. If the iPhone app is not installed: it is not on the App Store yet. Testers install it from their TestFlight invitation; if they have none, tell them to ask support@awareful.com. (Once it is public: https://apps.apple.com/app/id6806441837)
2. In Desk, they choose **Add Phone…** (⌘N) and scan the code with the phone. Both screens show the same 4 digits; they check that the digits match.

Desk's Overview shows the phone once pairing is done. Without pairing, the rest still installs, but nothing reaches the phone.

## 4. Find the agents on this Mac

```bash
command -v claude; command -v codex; command -v cursor-agent; ls -d /Applications/Cursor.app 2>/dev/null
```

Do steps 5 and 6 only for the agents that are installed.

## 5. Connect each agent: MCP server, skill and rules

Set these in every new shell. They point at the installer and the Node runtime inside Desk.
Desk updates them in place, so do not copy them anywhere else.

```bash
NODE="/Applications/Awareful Desk.app/Contents/Helpers/node"
MCP="/Applications/Awareful Desk.app/Contents/Resources/payload/mcp/src/cli.mjs"
BRIDGE="/Applications/Awareful Desk.app/Contents/Resources/payload/agent-bridge/src/cli.mjs"
HELPER=(--helper-command "$NODE" --helper-arg "$MCP")
cd "$(dirname "$MCP")/.."
```

For each host, `claude-code`, `codex` or `cursor`:

**a. Plan.** This reads only.

```bash
"$NODE" "$MCP" install plan --host claude-code "${HELPER[@]}" > /tmp/awareful-plan-claude-code.json
cat /tmp/awareful-plan-claude-code.json
```

If `status` is `installed` and every `action` is `none`, this host is done. Go to the next one.
Otherwise, explain each entry in `changes` (its `path`, `action` and `summary`) and any `conflicts` to the person.

| Host | MCP server | Skill | Rules |
|---|---|---|---|
| Claude Code | `mcpServers.awareful` in `~/.claude.json` | `~/.claude/skills/awareful` | `~/.claude/rules/awareful.md`, a file of its own |
| Codex | a marked block in `~/.codex/config.toml` | `~/.agents/skills/awareful` | a marked block in `~/.codex/AGENTS.md` |
| Cursor | `mcpServers.awareful` in `~/.cursor/mcp.json` | `~/.agents/skills/awareful` | `~/.cursor/rules/awareful.mdc`, a file of its own |

To install only some pieces, add `--only mcp_server,skill,rules` with the pieces the person wants.

**b. Apply, after the person says yes.** Pass the same plan back. If a file changed since the plan, it refuses; plan again.

```bash
"$NODE" "$MCP" install apply --host claude-code --plan-file /tmp/awareful-plan-claude-code.json "${HELPER[@]}"
```

If the person chose to replace a conflict, add `--replace <conflict id>`.

**c. Verify.**

```bash
"$NODE" "$MCP" install verify --host claude-code --host-bin "$(command -v claude)" "${HELPER[@]}"
```

For Codex use `--host codex --codex-bin "$(command -v codex)"`. For Cursor use `--host cursor --host-bin "$(command -v cursor-agent)"`, or leave out `--host-bin` without `cursor-agent`.
Every check should be `ok`. `not_run` is fine. On `failed`, show the person its `detail` and stop.

## 6. Connect approvals

This lets the agent's approval requests reach the phone. Check first:

```bash
"$NODE" "$BRIDGE" hooks-status claude codex cursor
```

A host with `installed` and `current` both `true` is done. For the others, dry-run, explain, then install after a yes.
The host names here are `claude`, `codex` and `cursor`.

```bash
"$NODE" "$BRIDGE" install-hooks claude --dry-run
"$NODE" "$BRIDGE" install-hooks claude
```

- **Codex:** ask the person to open Codex, type `/hooks` and trust Awareful's hook. Codex does not run hooks it does not trust.
- **Cursor:** approvals go through Awareful's Cursor extension, which `install-hooks cursor` installs. Ask the person to restart Cursor.

Whoever answers first wins: the phone, Desk, or the agent's own prompt.

## 7. Try it once

1. Ask the person to quit and reopen each agent you connected. For Claude Code, a new session is enough.
2. In the new session, have them say: "Start a small task: create hello.txt in /tmp."
   - The task should appear on the phone.
   - When the agent writes the file, an approval card should appear on the phone.
3. If both appear, tell the person it is connected. If not, show them the output of the checks in steps 5c and 6.

## Undo

```bash
"$NODE" "$MCP" install uninstall --host claude-code "${HELPER[@]}"
"$NODE" "$BRIDGE" uninstall-hooks claude
```

Uninstalling removes only what Awareful wrote. Anything the person edited afterwards stays, and the output says so.

## Without an agent

The person can do steps 5 and 6 by hand in Desk: Settings, then **Connect Agents**. There is one switch per app.
Desk shows each file's change before it writes. It uses the same installer as this page.