Higherup Agent

Connect AI coding assistants to your local development environment

Quick Start • Features • Documentation • Troubleshooting

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

# Install globally via npm
npm install -g higherup

# Verify installation
higherup --version

First-Time Setup

1. Create an account at 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...)

4. Save your API token (one-time):

higherup config --token YOUR_API_TOKEN

5. Connect your project:

cd /path/to/your/project
higherup connect --workspace YOUR_WORKSPACE_ID

That's it! Your agent is now listening for commands from AI platforms.

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

Start the agent and connect to Higherup service.

higherup connect [options]

Options:
  -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).

higherup quick

# Prompts you to select from available workspaces
# Then connects automatically

higherup config

Manage agent configuration.

# Save API token
higherup config --token YOUR_API_TOKEN

# Set default workspace
higherup config --workspace ws_abc123

# 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 sessions and connection status.

higherup status [options]

Options:
  -v, --verbose    Show detailed session info
  -w, --workspace  Filter by workspace ID

Examples:
  higherup status
  higherup status --verbose

higherup logs

View agent logs for debugging.

higherup logs [options]

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

higherup doctor

Diagnose common issues and check system requirements.

higherup doctor

# Checks:
# - Node.js version
# - Network connectivity
# - API token validity
# - Screen capture tools
# - File permissions

higherup init

Initialize Higherup in the current directory.

higherup init

# Creates .higherup/ directory with:
# - config.json
# - .gitignore entry
# - README with setup instructions

Keyboard Shortcuts

While the agent is running, use these shortcuts:

• h - Show help
• s - Show session statistics
• q - Quit gracefully
• Ctrl+C - Force quit

Security

Workspace Sandboxing

All file operations are restricted to your workspace directory. Path traversal attempts are automatically blocked:

# ✅ Allowed
/workspace/src/app.js

# ❌ Blocked
/workspace/../../../etc/passwd

Autonomous Mode

By default, the agent has safety restrictions. Enable --autonomous to remove all limits:

higherup connect -w ws_abc123 --autonomous

⚠️ 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:

export HIGHERUP_API_TOKEN=your_token
higherup connect -w ws_abc123

Platform Requirements

Supported Operating Systems

• ✅ macOS (10.15+)
• ✅ Linux (Ubuntu, Debian, Fedora, Arch)
• ✅ Windows (10/11)

Dependencies

• Node.js: 18.0.0 or higher
• Screen Capture (optional):
  • macOS: Built-in screencapture
  • Windows: Built-in PowerShell
  • Linux: scrot or imagemagick

# 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:

# 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:

# 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

Problem: Screenshots fail or return black screen

Solutions:

macOS:

# Grant Screen Recording permission:
# System Preferences → Security & Privacy → Screen Recording
# Add Terminal or your terminal app

Linux:

# Install required tools
sudo apt install scrot imagemagick

# Test manually
scrot test.png

Windows:

# Ensure PowerShell execution policy allows scripts
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Permission Errors

Problem: EACCES: permission denied

Solutions:

# 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:

# 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

# 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

# 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

# .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

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
• WebSocket: Real-time command streaming
• MCP Protocol: Native AI assistant integration

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Support

• 📚 Documentation
• 💬 Discord Community
• 🐛 Report Issues
• 📧 Email Support

License

MIT © Higherup