# Higherup Agent

<div align="center">

**Give AI agents full access to your development machine - command execution, file operations, screen capture, and autonomous mode**

[![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 via npm
npm install -g higherup

# Verify installation
higherup --version
```

### First-Time Setup

1. **Create an account** at [higherup.ai](https://higherup.ai)
2. **Setup your agent** (Interactive):

```bash
higherup setup
```
*This will prompt you for your API Token and guide you through workspace selection.*

3. **Start the Agent Daemon**:

```bash
higherup start
```
*Your agent is now listening for commands from AI platforms in the cloud.*

## Features

### 🚀 Core Capabilities

| Feature | Description | Command |
|---------|-------------|---------|
| **Command Execution** | Run any shell command | `npm install`, `git status` |
| **File Operations** | Read, write, copy, move, delete | `cat package.json`, `rm tmp.log` |
| **Directory Listing** | Browse project structure | `ls -R` |
| **Screen Capture** | Take screenshots | Captures browser, IDE, terminal |
| **System Info** | Get OS, CPU, memory details | `higherup status` |

## Commands

### `higherup setup`

Interactive setup to configure your authentication and workspace.
- Prompts for API Token (found in Higherup Dashboard)
- Auto-detects local project workspaces
- Links your local directory to a cloud workspace

### `higherup start`

Starts the agent daemon. This process must stay running to receive commands from the cloud.
- Connects to the Higherup Relay
- Listens for incoming tool calls
- Reports execution results back to the dashboard

### `higherup run "<command>"`

Queue a one-shot command from the CLI.
- Useful for testing or triggering commands from other scripts
- Example: `higherup run "npm run build"`

### `higherup status`

Display the current configuration, linked workspace, and system information.

### `higherup help`

Display help for all commands.

## Architecture: The Relay System

Higherup uses a secure relay architecture. The **Agent Daemon** (`higherup start`) runs on your machine and maintains a connection to our relay. When you use an AI platform (like our web dashboard or a compatible IDE extension), commands are sent to the relay and then picked up by your local agent.

```mermaid
graph LR
    User[Web Dashboard / AI] --> Relay[Higherup Relay]
    Relay --> Agent[Local Higherup Agent]
    Agent --> LocalSystem[Your Terminal / Files]
```

## Security & Safety

### Workspace Sandboxing
By default, the agent is restricted to the directory where you ran `higherup setup`. It cannot read or write files outside this path.

### Safety Engine
The agent includes a built-in safety engine that can prompt for confirmation before executing potentially destructive commands (e.g., `rm -rf /`).

### API Token Security
Your API token is used to authenticate the agent to the relay. Keep it secret. If compromised, regenerate it in the [Higherup Dashboard](https://higherup.ai/dashboard/api).

---

<div align="center">
Made with ❤️ by the Higherup team
</div>