Skill: adnxone/nxt-pulse-agent (version 0.5.0)

--- name: nxt-pulse-agent description: "An adaptive proactive agent skill that manages user energy levels and task prioritization using semantic pulse checks." version: 0.5.0 --- # Next Pulse Agent (NXT) v0.5.0 NXT transforms your agent from a reactive chat-bot into a proactive partner. It adapts its proactivity based on your inferred energy levels, ensuring it's helpful when you're peaking and supportive when you're recharging. ## 🌟 Key Features - **Semantic Energy Detection**: Infers energy levels (🟢 High, 🟡 Medium, 🔴 Low) from recent interactions. - **Adaptive Proactivity**: Shifts between "Deep Work", "Micro-Steps", and "Downtime Protocol". - **Transparency Command (`/pulse`)**: Users can check the agent's current perception of their state and manually override it. - **Context Guardrails**: Automatically limits external file scanning to the most recent/relevant snippets to save tokens and prevent context overflow. - **Smart Cooldowns**: Syncs with OpenClaw's heartbeat to minimize noise. ## 🛠 Configuration The agent reads these values from the skill's configuration entry in `openclaw.json` (`skills.entries.nxt-pulse-agent.config`). - `PULSE_SENSITIVITY`: Integer (1-5). 1 is conservative, 5 is highly sensitive to language cues. (Default: `3`) - `MAX_CONTEXT_CHARS`: Integer. Maximum characters to read from `CONTEXT_SOURCES` per pulse to keep tokens low. (Default: `5000`) - `PULSE_COOLDOWN`: Duration string (e.g., `30m`, `4h`). Minimum time between proactivity triggers. - `DOWNTIME_KEYWORDS`: Array of strings (Optional). Manual "hard-triggers" to force Recovery Mode. Note: The agent's **Semantic Detection** automatically identifies downtime needs in any language based on context, even without keywords. - `CONTEXT_SOURCES`: Array of strings. Relative paths to files that provide user state (e.g., journals, medical logs). - `SCOPE`: `dm` (default) or `group`. Limits proactive triggers to specific conversation types. ## 🚀 Commands - `/pulse`: Shows current energy level, reasoning, and upcoming tasks. - `/pulse set [green|yellow|red]`: Manually override your energy state. - `/pulse quiet [duration]`: Mutes proactive nudges for a specific time (e.g., `2h`). ## 🚀 Workflow ### 1. The Pulse Audit When triggered, the agent performs a **Resource-Safe Audit**: 1. **State Check**: Evaluates capacity using `MAX_CONTEXT_CHARS` from sources. 2. **Sentiment Alignment**: Adjusts based on `PULSE_SENSITIVITY`. 3. **Command Check**: Looks for any active `/pulse quiet` timers. ### 2. Interaction Modes - **🟢 High Energy**: Focuses on the top 1-2 priority tasks from TODOs. - **🟡 Medium Energy**: Proposes 5-10 minute "Quick Wins". - **🔴 Low Energy**: Triggers **Downtime Protocol**. No work demands. Only recovery suggestions (hydration, breaks). --- Part of the OpenClaw community ecosystem. Built for performance, tuned for human limits.

path: CONTRIBUTING.md
content: # Contributing to NXT Pulse Agent

First off, thank you for considering contributing! It's people like you who make OpenClaw a great ecosystem for everyone.

## 🌈 Our Vision
NXT Pulse Agent aims to be the most respectful, neuro-inclusive, and efficient proactive skill in the OpenClaw ecosystem. We value:
- **Low Friction**: Minimal user annoyance.
- **Transparency**: Every AI decision must be explainable.
- **Performance**: Zero-bloat local logic first.

## 🛠 How Can I Contribute?

### Reporting Bugs
- Use the GitHub Issue tracker.
- Describe the expected vs. actual behavior.
- Include the `PULSE_ACTION` from your `memory/pulse-history.jsonl` if possible.

### Suggesting Features
- We love new ideas for energy-management! 
- If you have a strategy that helps with ADHD or executive dysfunction, open an issue to discuss it.

### Pull Requests
1. Fork the repo.
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
4. Push to the branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request.

## 📜 Code of Conduct
Be respectful, empathetic, and helpful. We follow the standard Contributor Covenant.

---
Thank you for building the future of human-AI partnership with us!


path: package.json
content: {
  "name": "NXT Pulse Agent",
  "version": "0.5.0",
  "description": "An adaptive proactive agent skill that manages user energy levels and task prioritization using semantic pulse checks.",
  "type": "skill",
  "author": "adnXone <https://github.com/adnxone>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/adnxone/nxt-pulse-agent"
  },
  "metadata": {
    "openclaw": {
      "emoji": "💓",
      "tags": [
        "proactivity",
        "performance",
        "energy-management",
        "nxt-agent"
      ],
      "language": "en"
    }
  }
}


path: pulse.js
content: const fs = require('fs');
const path = require('path');

// Configuration
const CONFIG = {
    PULSE_COOLDOWN_HOURS: 4,
    CRITICAL_THRESHOLD_HOURS: 6,
    STATE_FILE: path.join(process.cwd(), 'memory', 'pulse-state.json'),
    LOG_FILE: path.join(process.cwd(), 'memory', 'pulse-history.jsonl')
};

/**
 * Log decision for Audit Trail (Admin Transparency)
 */
function logAudit(action, reason, pulse) {
    const logEntry = {
        timestamp: new Date().toISOString(),
        action,
        reason,
        pulse,
        mode: 'NXT'
    };
    if (!fs.existsSync(path.dirname(CONFIG.LOG_FILE))) {
        fs.mkdirSync(path.dirname(CONFIG.LOG_FILE), { recursive: true });
    }
    fs.appendFileSync(CONFIG.LOG_FILE, JSON.stringify(logEntry) + '\n');
}

/**
 * Proactive Pulse Script
 * Handles cooldowns, critical deadline checks, and state management.
 */
async function runPulse() {
    const now = new Date();
    let state = { last_pulse: 0, mode: 'normal' };

    // 1. Load State
    if (fs.existsSync(CONFIG.STATE_FILE)) {
        state = JSON.parse(fs.readFileSync(CONFIG.STATE_FILE, 'utf8'));
    }

    // 2. Emergency/Sick Mode Check
    if (state.mode === 'emergency' || state.mode === 'sick') {
        logAudit("SILENCED", "Emergency/Sick Mode Active", "⚪");
        console.log("PULSE_STATUS: SILENCED (Emergency/Sick Mode Active)");
        return;
    }

    // 3. Cooldown Check
    const hoursSinceLastPulse = (now - new Date(state.last_pulse)) / (1000 * 60 * 60);
    const isCooldownActive = hoursSinceLastPulse < CONFIG.PULSE_COOLDOWN_HOURS;

    // 4. Critical Deadline Check
    const hasCriticalDeadline = checkForCriticalDeadlines();

    if (isCooldownActive && !hasCriticalDeadline) {
        // Silent exit if within cooldown and no emergency
        return;
    }

    // 5. Determine Pulse Action & Audit
    if (hasCriticalDeadline) {
        logAudit("CRITICAL_OVERRIDE", "Deadline detected in < 6 hours.", "🔴");
        console.log("PULSE_ACTION: CRITICAL_OVERRIDE_NUDGE");
        console.log("REASON: Deadline detected in < 6 hours.");
    } else {
        logAudit("STANDARD_PULSE", "Cooldown expired. Checking energy levels.", "🟡");
        console.log("PULSE_ACTION: STANDARD_PULSE_CHECK");
        console.log("REASON: Cooldown expired. Checking energy levels.");
    }

    // 6. Update State
    state.last_pulse = now.toISOString();
    if (!fs.existsSync(path.dirname(CONFIG.STATE_FILE))) {
        fs.mkdirSync(path.dirname(CONFIG.STATE_FILE), { recursive: true });
    }
    fs.writeFileSync(CONFIG.STATE_FILE, JSON.stringify(state, null, 2));
}


/**
 * Check for critical deadlines using a combination of file triggers and 
 * context-aware heuristics. The main LLM agent is instructed to trigger 
 * the file-based override when it detects urgency in natural language.
 */
function checkForCriticalDeadlines() {
    const deadlineTriggers = [
        path.join(process.cwd(), 'temp_deadline_trigger.txt'),
        path.join(process.cwd(), 'memory', 'critical_deadlines.txt')
    ];

    // 1. Check for explicit trigger files (often created by the LLM agent 
    //    after analyzing interaction context/sentiment)
    if (deadlineTriggers.some(file => fs.existsSync(file))) {
        return true;
    }

    // 2. Date-based trigger: If a file named after today exists in a 'deadlines' dir
    const todayStr = new Date().toISOString().split('T')[0];
    const dailyDeadlineFile = path.join(process.cwd(), 'memory', 'deadlines', `${todayStr}.txt`);
    if (fs.existsSync(dailyDeadlineFile)) {
        return true;
    }

    return false;
}

runPulse().catch(err => {
    console.error("PULSE_ERROR:", err.message);
    process.exit(1);
});


path: README.md
content: # NXT Pulse Agent (NXT) v0.5.0

> **Proactive energy-aware task management for OpenClaw agents.**

NXT bridges the gap between reactive chat and proactive partnership. It monitors your state and energy levels to ensure the right tasks are proposed at the right time, preventing burnout and decision paralysis.

## ✨ New in v0.5.0
- **`/pulse` Command**: Full transparency into the agent's "mind".
- **Manual Overrides**: Correct the agent if it misreads your vibe.
- **Token Efficiency**: New context guardrails (`MAX_CONTEXT_CHARS`) for power users.
- **Sensitivity Tuning**: Adjustable `PULSE_SENSITIVITY`.

## 📦 Installation

```bash
clawhub install nxt-pulse-agent
```

## ⚙️ Configuration

To configure NXT Pulse Agent, add a `config` object to your skill entry in `openclaw.json`:

```json
{
  "skills": {
    "entries": {
      "nxt-pulse-agent": {
        "enabled": true,
        "config": {
          "PULSE_SENSITIVITY": 3,
          "MAX_CONTEXT_CHARS": 5000,
          "PULSE_COOLDOWN": "4h",
          "DOWNTIME_KEYWORDS": [],
          "CONTEXT_SOURCES": ["memory/daily-jurnal.md", "logs/activity.log"]
        }
      }
    }
  }
}
```

| Setting | Description | Default |
|---------|-------------|---------|
| `PULSE_SENSITIVITY` | 1-5 scale for energy state triggers (1=conservative, 5=sensitive). | `3` |
| `MAX_CONTEXT_CHARS` | Character limit for reading external context sources per pulse. | `5000` |
| `PULSE_COOLDOWN` | Minimum time duration between proactive nudges (e.g. 1h, 4h). | `4h` |
| `DOWNTIME_KEYWORDS` | Optional manual triggers. Note: Semantic detection works in any language by default. | `[]` |
| `SCOPE` | Interaction scope: `dm` or `group`. | `dm` |

## 🕹 Commands

- **/pulse**: Check current state.
- **/pulse set [green/yellow/red]**: Manual override.
- **/pulse quiet [time]**: Mute proactive nudges (e.g., `1h`).

## 🛠 How it Works

NXT uses **Semantic Pulse Checks**. It reads the "vibe" of recent messages. If you say "I've had a long day," the agent updates your state to `🔴 Low` and shifts from "Productivity Mode" to "Downtime Protocol."

---
Developed by **adnXone** (@adnxone). 
[GitHub](https://github.com/adnXone/nxt-pulse-agent) | [ClawHub](https://clawhub.ai/nxt-pulse-agent)


path: _meta.json
content: ownerId: kn79tepwe85k64v9mbvewmt8r584phxf
slug: nxt-pulse-agent
version: 0.5.0
publishedAt: 1776750468141

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)