higherup 1.0.1 → 2.1.0

package/README.md

@@ -1,62 +1,128 @@
-# Higherup
+# Higherup Agent
 
-**Give AI agents full access to your development machine.**
+<div align="center">
 
-A CLI agent that connects your local environment to Higherup, enabling AI platforms to execute commands, manage files, capture screens, and work autonomously.
+**Connect AI coding assistants to your local development environment**
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/higherup.svg)](https://www.npmjs.com/package/higherup)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Quick Start](#quick-start) • [Features](#features) • [Documentation](#documentation) • [Troubleshooting](#troubleshooting)
+
+</div>
+
+---
+
+## What is Higherup?
+
+Higherup is a lightweight CLI agent that bridges cloud-based AI coding platforms with your local development environment. It enables AI assistants like Claude, GPT, and others to:
+
+- ✅ Execute commands in your terminal
+- ✅ Read and write files in your workspace
+- ✅ Capture screenshots for visual debugging
+- ✅ Monitor system resources
+- ✅ Work autonomously with full access (optional)
+
+**Perfect for:** AI-assisted development, remote pair programming, automated workflows, and autonomous coding agents.
+
+## Quick Start
+
+### Installation
 
 ```bash
-# Install globally from npm
+# Install globally via npm
 npm install -g higherup
 
-# Or clone and build locally
-git clone https://github.com/hnibbo/HUagent
-cd agent
-npm install
-npm run build
-npm link
+# Verify installation
+higherup --version
 ```
 
-## Quick Start
+### First-Time Setup
+
+1. **Create an account** at [higherup.ai](https://higherup.ai)
+2. **Create a workspace** in the dashboard
+3. **Copy your credentials:**
+   - Workspace ID (e.g., `ws_abc123...`)
+   - API Token (e.g., `hup_xyz789...`)
 
-1. **Sign up** at [higherup.ai](https://higherup.ai) and create a workspace
-2. **Copy your credentials** from the dashboard:
-   - Workspace ID
-   - API Token
-3. **Configure the agent** (one-time setup):
+4. **Save your API token** (one-time):
 
 ```bash
 higherup config --token YOUR_API_TOKEN
 ```
 
-4. **Connect your workspace**:
+5. **Connect your project:**
 
 ```bash
-higherup connect -w YOUR_WORKSPACE_ID -p /path/to/your/project
+cd /path/to/your/project
+higherup connect --workspace YOUR_WORKSPACE_ID
 ```
 
-5. **Enable autonomous mode** (optional - removes all restrictions):
+That's it! Your agent is now listening for commands from AI platforms.
 
-```bash
-higherup connect -w YOUR_WORKSPACE_ID -p . --autonomous
-```
+## Features
+
+### 🚀 Core Capabilities
+
+| Feature | Description | Command Example |
+|---------|-------------|-----------------|
+| **Command Execution** | Run any shell command | `npm install`, `git status` |
+| **File Operations** | Read, write, copy, move, delete | Read `package.json`, create files |
+| **Directory Listing** | Browse project structure | List files recursively |
+| **Screen Capture** | Take screenshots | Capture browser, IDE, terminal |
+| **System Info** | Get OS, CPU, memory details | Check available resources |
+| **Process Management** | List running processes | Monitor active services |
+| **File Search** | Find content across files | Search for functions, imports |
+
+### 🎯 Advanced Features
+
+- **Auto-Reconnection**: Automatically reconnects on network issues
+- **Workspace Sandboxing**: Restricts operations to your project directory
+- **Real-time Stats**: Monitor commands executed, uptime, bandwidth
+- **Keyboard Shortcuts**: Quick access to help, stats, and quit
+- **Streaming Output**: See command results in real-time
+- **Autonomous Mode**: Remove all restrictions for full AI control
 
 ## Commands
 
 ### `higherup connect`
 
-Connect a local workspace to Higherup.
+Start the agent and connect to Higherup service.
 
 ```bash
 higherup connect [options]
 
 Options:
-  -w, --workspace <id>   Workspace ID from dashboard (required)
-  -p, --path <path>      Local workspace path (default: current directory)
-  -t, --token <token>    API token (or use config/env var)
-  -n, --name <name>      Custom agent name for identification
-  --autonomous           Enable autonomous mode (unrestricted access)
+  -w, --workspace <id>   Workspace ID (required)
+  -p, --path <path>      Project path (default: current directory)
+  -t, --token <token>    API token (or use config)
+  -n, --name <name>      Custom agent name
+  --autonomous           Enable unrestricted access
+  --auto-reconnect       Auto-reconnect on disconnect (default: true)
+
+Examples:
+  # Connect current directory
+  higherup connect -w ws_abc123
+
+  # Connect specific project
+  higherup connect -w ws_abc123 -p ~/projects/my-app
+
+  # Autonomous mode (full access)
+  higherup connect -w ws_abc123 --autonomous
+
+  # Custom agent name
+  higherup connect -w ws_abc123 -n "macbook-pro-dev"
+```
+
+### `higherup quick`
+
+Interactive workspace selection (if you have multiple workspaces).
+
+```bash
+higherup quick
+
+# Prompts you to select from available workspaces
+# Then connects automatically
 ```
 
 ### `higherup config`
@@ -64,132 +130,347 @@ Options:
 Manage agent configuration.
 
 ```bash
-# Save your API token
+# Save API token
 higherup config --token YOUR_API_TOKEN
 
 # Set default workspace
-higherup config --workspace YOUR_WORKSPACE_ID
+higherup config --workspace ws_abc123
 
-# Show current configuration
+# Set default path
+higherup config --path ~/projects/main
+
+# View current config
 higherup config --show
+
+# Set log level (debug, info, warn, error)
+higherup config --log-level debug
 ```
 
 ### `higherup status`
 
-Check active agent sessions.
+Check active sessions and connection status.
 
 ```bash
-higherup status
+higherup status [options]
+
+Options:
+  -v, --verbose    Show detailed session info
+  -w, --workspace  Filter by workspace ID
+
+Examples:
+  higherup status
+  higherup status --verbose
 ```
 
-## Capabilities
+### `higherup logs`
 
-When connected, AI agents can:
+View agent logs for debugging.
 
-| Capability | Description |
-|------------|-------------|
-| `command_execute` | Run any shell command |
-| `file_read` | Read file contents |
-| `file_write` | Create/modify files |
-| `file_list` | List directory contents |
-| `screen_capture` | Take screenshots |
-| `system_info` | Get machine details (OS, CPU, memory) |
+```bash
+higherup logs [options]
 
-## Autonomous Mode
+Options:
+  -n, --lines <number>  Number of lines to show (default: 50)
+  -f, --follow          Follow log output
+  --clear               Clear all logs
+
+Examples:
+  higherup logs
+  higherup logs -n 100
+  higherup logs --follow
+```
 
-Enable `--autonomous` to remove all restrictions:
+### `higherup doctor`
 
-- ✅ No command blocking
-- ✅ Full system access
-- ✅ Unrestricted file operations
-- ✅ Complete AI control
+Diagnose common issues and check system requirements.
 
 ```bash
-higherup connect -w WORKSPACE_ID -p . --autonomous
+higherup doctor
+
+# Checks:
+# - Node.js version
+# - Network connectivity
+# - API token validity
+# - Screen capture tools
+# - File permissions
 ```
 
-## Security
-
-- All connections use HTTPS encryption
-- Path traversal attacks are blocked automatically
-- Operations are restricted to your workspace directory only
-- Dangerous command patterns blocked by default (unless autonomous)
-- API tokens can be regenerated at any time
-
-## Screen Capture Requirements
+### `higherup init`
 
-- **macOS**: Built-in `screencapture` (may need Screen Recording permission)
-- **Windows**: PowerShell (built-in)
-- **Linux**: `scrot` or `imagemagick` (`import` command)
+Initialize Higherup in the current directory.
 
 ```bash
-# Linux: Install screen capture tools
-sudo apt install scrot  # Debian/Ubuntu
-sudo dnf install scrot  # Fedora
+higherup init
+
+# Creates .higherup/ directory with:
+# - config.json
+# - .gitignore entry
+# - README with setup instructions
 ```
 
-## How It Works
+## Keyboard Shortcuts
 
-1. Agent registers with Higherup using your API token
-2. Polls the server for pending commands every 2 seconds
-3. Executes commands locally in your workspace directory
-4. Reports results back to the server
-5. AI platforms receive command output in real-time
+While the agent is running, use these shortcuts:
 
-## Supported AI Platforms
+- `h` - Show help
+- `s` - Show session statistics
+- `q` - Quit gracefully
+- `Ctrl+C` - Force quit
 
-Works with any AI assistant that integrates with Higherup:
-- Claude (via MCP protocol)
-- GPT/ChatGPT
-- Lovable
-- Bolt
-- Cursor
-- Other AI platforms via the Higherup API
+## Security
 
-## Requirements
+### Workspace Sandboxing
 
-- Node.js 18+
-- macOS, Linux, or Windows
+All file operations are restricted to your workspace directory. Path traversal attempts are automatically blocked:
 
-## Environment Variables
+```bash
+# ✅ Allowed
+/workspace/src/app.js
+
+# ❌ Blocked
+/workspace/../../../etc/passwd
+```
+
+### Autonomous Mode
+
+By default, the agent has safety restrictions. Enable `--autonomous` to remove all limits:
 
 ```bash
-# API endpoint (defaults to Higherup service)
-HIGHERUP_API_URL=https://pltlcpqtivuvyeuywvql.supabase.co/functions/v1/agent-relay
+higherup connect -w ws_abc123 --autonomous
+```
 
-# Your API token (alternative to --token flag)
-HIGHERUP_API_TOKEN=your_token_here
+**⚠️ Warning:** Autonomous mode gives AI complete control. Only use with trusted AI platforms.
+
+### API Token Security
+
+- Tokens are stored in `~/.higherup/config.json` (chmod 600)
+- Never commit tokens to version control
+- Regenerate tokens if compromised
+- Use environment variables in CI/CD:
+
+```bash
+export HIGHERUP_API_TOKEN=your_token
+higherup connect -w ws_abc123
 ```
 
-## API Integration
+## Platform Requirements
 
-Once connected, AI platforms can control your machine via:
+### Supported Operating Systems
 
-- **REST API** - Standard HTTP endpoints
-- **WebSocket** - Real-time streaming
-- **MCP Protocol** - Native AI assistant integration
+- ✅ macOS (10.15+)
+- ✅ Linux (Ubuntu, Debian, Fedora, Arch)
+- ✅ Windows (10/11)
 
-See [API Documentation](https://higherup.ai/api) for details.
+### Dependencies
+
+- **Node.js**: 18.0.0 or higher
+- **Screen Capture** (optional):
+  - macOS: Built-in `screencapture`
+  - Windows: Built-in PowerShell
+  - Linux: `scrot` or `imagemagick`
+
+```bash
+# Install screen capture on Linux
+sudo apt install scrot          # Debian/Ubuntu
+sudo dnf install scrot          # Fedora
+sudo pacman -S scrot            # Arch
+```
 
 ## Troubleshooting
 
 ### Connection Issues
 
+**Problem:** `Failed to connect: Network error`
+
+**Solutions:**
 ```bash
-# Check if agent can reach the server
+# 1. Check internet connection
+ping higherup.ai
+
+# 2. Verify API endpoint
 curl https://pltlcpqtivuvyeuywvql.supabase.co/functions/v1/agent-relay
+
+# 3. Check firewall settings
+# Ensure port 443 (HTTPS) is open
+
+# 4. Try with verbose logging
+higherup connect -w ws_abc123 --log-level debug
+```
+
+### Authentication Errors
+
+**Problem:** `Invalid API token` or `Unauthorized`
+
+**Solutions:**
+```bash
+# 1. Verify token is correct
+higherup config --show
+
+# 2. Regenerate token in dashboard
+# Then update config:
+higherup config --token NEW_TOKEN
+
+# 3. Check token hasn't expired
 ```
 
 ### Screen Capture Not Working
 
-macOS: Grant Screen Recording permission in System Preferences
-Linux: Install `scrot` or `imagemagick`
+**Problem:** Screenshots fail or return black screen
+
+**Solutions:**
+
+**macOS:**
+```bash
+# Grant Screen Recording permission:
+# System Preferences → Security & Privacy → Screen Recording
+# Add Terminal or your terminal app
+```
+
+**Linux:**
+```bash
+# Install required tools
+sudo apt install scrot imagemagick
+
+# Test manually
+scrot test.png
+```
+
+**Windows:**
+```powershell
+# Ensure PowerShell execution policy allows scripts
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
 
 ### Permission Errors
 
-Ensure your API token is valid and has access to the workspace.
+**Problem:** `EACCES: permission denied`
+
+**Solutions:**
+```bash
+# 1. Check workspace permissions
+ls -la /path/to/workspace
+
+# 2. Ensure you own the directory
+sudo chown -R $USER:$USER /path/to/workspace
+
+# 3. Check if workspace path is correct
+pwd
+```
+
+### High CPU/Memory Usage
+
+**Problem:** Agent consuming too many resources
+
+**Solutions:**
+```bash
+# 1. Check stats
+# Press 's' while agent is running
+
+# 2. Reduce poll interval (edit config)
+# 3. Disable file watching if enabled
+# 4. Close unnecessary processes
+```
+
+## Environment Variables
+
+```bash
+# API Configuration
+HIGHERUP_API_URL=https://pltlcpqtivuvyeuywvql.supabase.co/functions/v1/agent-relay
+HIGHERUP_API_TOKEN=your_token_here
+
+# Agent Settings
+HIGHERUP_WORKSPACE_ID=ws_abc123
+HIGHERUP_AGENT_NAME=my-custom-name
+HIGHERUP_LOG_LEVEL=info  # debug, info, warn, error
+
+# Performance
+HIGHERUP_POLL_INTERVAL=2000  # milliseconds
+HIGHERUP_MAX_RETRIES=5
+```
+
+## Examples
+
+### Basic Development Workflow
+
+```bash
+# 1. Start agent in your project
+cd ~/projects/my-app
+higherup connect -w ws_abc123
+
+# 2. AI can now:
+# - Run tests: npm test
+# - Install packages: npm install lodash
+# - Read files: cat src/app.js
+# - Make changes: edit files
+# - Check git status: git status
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/ai-review.yml
+name: AI Code Review
+on: [pull_request]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      - run: npm install -g higherup
+      - run: |
+          higherup connect \
+            --workspace ${{ secrets.HIGHERUP_WORKSPACE }} \
+            --token ${{ secrets.HIGHERUP_TOKEN }} \
+            --autonomous
+```
+
+### Docker Usage
+
+```dockerfile
+FROM node:18-alpine
+
+# Install agent
+RUN npm install -g higherup
+
+# Set working directory
+WORKDIR /app
+
+# Copy project
+COPY . .
+
+# Start agent on container start
+CMD ["higherup", "connect", "-w", "${WORKSPACE_ID}", "--autonomous"]
+```
+
+## API Integration
+
+For platform developers integrating with Higherup:
+
+- **REST API**: [https://higherup.ai/api/docs](https://higherup.ai/api/docs)
+- **WebSocket**: Real-time command streaming
+- **MCP Protocol**: Native AI assistant integration
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Support
+
+- 📚 [Documentation](https://higherup.ai/docs)
+- 💬 [Discord Community](https://discord.gg/higherup)
+- 🐛 [Report Issues](https://github.com/hnibbo/HUagent/issues)
+- 📧 [Email Support](mailto:support@higherup.ai)
 
 ## License
 
-MIT
+MIT © Higherup
+
+---
 
+<div align="center">
+Made with ❤️ by the Higherup team
+</div>

package/dist/agent.d.ts

@@ -1,5 +1,5 @@
 /**
- * Higherup Local Agent
+ * Higherup Local Agent v2.0
  *
  * This agent runs on your local PC and connects to the Higherup service,
  * enabling secure remote command execution, file operations, and screen capture