@sneub/pair 0.0.4 → 0.0.6

package/README.md

@@ -65,6 +65,9 @@ secrets at deploy time.
 | `pair.workspaceDir` | string | `"~/.pair/workspace"` | Path to workspace directory |
 | `pair.healthCheckPort` | number | _(unset)_ | Port for HTTP health check endpoint |
 | `pair.authMode` | string | `"api-key"` | `"api-key"` or `"oauth"` (Claude Max/Pro) |
+| `pair.heartbeatIntervalMinutes` | number | _(unset)_ | If set, wake the agent every N minutes to check `HEARTBEAT.md` (see Heartbeat below) |
+| `pair.defaultChannel` | string | _(unset)_ | Default platform (`"telegram"` / `"slack"`) for proactive `send_message` calls |
+| `pair.defaultChannelId` | string | _(unset)_ | Default chat/channel ID for proactive sends |
 | `telegram.allowedUsers` | number[] | `[]` | Telegram user IDs allowed to interact |
 | `slack.allowedUsers` | string[] | `[]` | Slack user IDs allowed to interact |
 | `mcp.servers` | object | `{}` | MCP server configurations |
@@ -87,6 +90,9 @@ secrets at deploy time.
 | `PAIR_WORKSPACE_DIR` | No | Override the workspace directory |
 | `PAIR_HEALTH_PORT` | No | Override the health check port |
 | `PAIR_HOME` | No | Override the Pair home directory |
+| `PAIR_HEARTBEAT_INTERVAL_MINUTES` | No | Wake the agent every N minutes (enables the proactive heartbeat loop) |
+| `PAIR_DEFAULT_CHANNEL` | No | Default platform for proactive messages (`telegram` / `slack`) |
+| `PAIR_DEFAULT_CHANNEL_ID` | No | Default chat/channel ID for proactive messages |
 
 ## Workspace
 
@@ -94,13 +100,49 @@ After `pair init`, your workspace lives at `./workspace/` (or
 `~/.pair/workspace/` in global mode) and contains files Claude reads on every
 turn:
 
-- `SYSTEM.md` — base system prompt and personality
-- `USER.md` — information about you
-- `MEMORY.md` — persistent memory (Claude can update this)
+- `CLAUDE.md` — canonical instructions; how the agent operates, memory rules, red lines
+- `SOUL.md` — values and personality
+- `IDENTITY.md` — name, vibe, how the agent presents itself
+- `USER.md` — information about you (the agent updates this as it learns)
+- `MEMORY.md` — curated long-term memory (the agent can update this)
 - `tasks.md` — your current task list
+- `HEARTBEAT.md` — short recurring reminders (see Heartbeat below)
+- `BOOTSTRAP.md` — first-run ritual (self-deletes after use)
 
 Edit them freely — they're how you customize Pair's behavior.
 
+## Heartbeat (proactive mode)
+
+By default Pair is reactive: it only speaks when messaged. Turn on the
+heartbeat to make it proactive — on a fixed interval Pair wakes the agent,
+hands it the workspace context, and lets it decide whether to take action or
+message you out of the blue.
+
+```json
+{
+  "pair": {
+    "heartbeatIntervalMinutes": 10,
+    "defaultChannel": "telegram",
+    "defaultChannelId": "123456789"
+  }
+}
+```
+
+On each tick the agent reads `HEARTBEAT.md` from your workspace and acts on
+anything that's due. The file is free-form markdown that Pair owns: it adds
+recurring items and one-off reminders there itself (e.g. when you say _"remind
+me in an hour"_) and edits them after firing so they don't re-fire. You can
+hand-edit it too.
+
+To reach you from a heartbeat, the agent calls a built-in `send_message` tool
+that pushes directly to the configured `defaultChannel` (or any channel you
+specify). This same tool is available in normal conversation, so the agent can
+also follow up after a long-running task: _"notify me on slack when the
+deployment is done"_.
+
+If nothing is due, the agent responds `NOOP` and the tick costs nothing
+user-visible.
+
 ## Tools
 
 Tools are the quickest way to add custom capabilities. You have two options:

package/config.example.json

@@ -2,7 +2,10 @@
   "pair": {
     "sessionTimeoutMinutes": 30,
     "logLevel": "info",
-    "model": "claude-sonnet-4-6"
+    "model": "claude-sonnet-4-6",
+    "heartbeatIntervalMinutes": 10,
+    "defaultChannel": "telegram",
+    "defaultChannelId": ""
   },
   "telegram": {
     "enabled": true,