diff --git a/README.md b/README.md index b078d835..dff61c4d 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ We strongly recommend: - Never using production tokens or credentials - Being prepared to revoke and replace all tokens used with this system -Minimum system requirements to run `hive.mjs`: +**Minimum system requirements:** ``` 1 CPU Core @@ -92,25 +92,20 @@ Minimum system requirements to run `hive.mjs`: ## 🚀 Quick Start -### Global Installation - -#### Using Bun (Recommended) - -```bash -bun install -g @link-assistant/hive-mind -``` +Choose your preferred installation method: -#### Using Node.js - -```bash -npm install -g @link-assistant/hive-mind -``` +| Method | Best For | Guide | +| ----------------------- | ------------------------------------- | ------------------------------------------------------- | +| **Docker** | Local development, multiple instances | [Docker Installation](#docker-installation) | +| **Helm/Kubernetes** | Production deployments, scaling | [Helm Installation](#helm-installation) | +| **Ubuntu 24.04 Server** | Dedicated VMs/VPS | [Server Installation](#ubuntu-2404-server-installation) | +| **Global npm/bun** | Quick local testing | [Global Installation](#global-installation) | ### Docker Installation Run the Hive Mind using Docker for safer local installation - no manual setup required: -**Note:** Docker is much safer for local installation and can be used to install multiple isolated instances on a server or Kubernetes cluster. For Kubernetes deployments, see the [Helm chart installation](#helm-installation-kubernetes) section below. +**Note:** Docker is much safer for local installation and can be used to install multiple isolated instances on a server or Kubernetes cluster. For Kubernetes deployments, see the [Helm Installation](#helm-installation) section below. ```bash # Pull the latest image from Docker Hub @@ -140,9 +135,9 @@ solve https://github.com/owner/repo/issues/123 - ✅ Easy to run multiple instances with different GitHub accounts - ✅ Consistent environment across different machines -See [docs/DOCKER.md](./docs/DOCKER.md) for advanced Docker usage. +See [docs/DOCKER.md](./docs/DOCKER.md) for advanced Docker usage including persistent storage, Docker Compose, and CI/CD configuration. -### Helm Installation (Kubernetes) +### Helm Installation Deploy Hive Mind on Kubernetes using Helm: @@ -170,7 +165,7 @@ See [docs/HELM.md](./docs/HELM.md) for detailed Helm configuration options. **Note:** The Helm chart is published to [ArtifactHub](https://artifacthub.io/packages/helm/link-assistant/hive-mind) for easy discovery. -### Installation on Ubuntu 24.04 server +### Ubuntu 24.04 Server Installation 1. Reset/install VPS/VDS server with fresh Ubuntu 24.04 2. Login to `root` user. @@ -281,7 +276,23 @@ The oAuth callback server on 1455 port will be started, and the link to oAuth wi 3. Use your browser on machine where you started the tunnel from, paste there the link from `codex login` command, and go there using your browser. Once redirected to localhost:1455 you will see successful login page, and in `codex login` you will see `Successfully logged in`. After that `codex login` command will complete, and you can use `codex` command as usual to verify. It should also be working with `--tool codex` in `solve` and `hive` commands. -### Core Operations +### Global Installation + +**For quick testing (not recommended for production).** + +#### Using Bun (Recommended) + +```bash +bun install -g @link-assistant/hive-mind +``` + +#### Using Node.js + +```bash +npm install -g @link-assistant/hive-mind +``` + +## Core Operations ```bash # Solve using maximum power @@ -631,6 +642,18 @@ grep -E '\(cd /tmp/gh-issue-solver-[0-9]+ && claude --resume [0-9a-f-]{36}\)' hi For comprehensive configuration including environment variables, timeouts, retry limits, Telegram bot settings, YouTrack integration, and all CLI options, see [docs/CONFIGURATION.md](./docs/CONFIGURATION.md). +## Documentation + +| Document | Description | +| -------------------------------------------------- | --------------------------------------------------- | +| [docs/USAGE.md](./docs/USAGE.md) | Complete CLI and Telegram bot usage guide | +| [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) | All configuration options and environment variables | +| [docs/FEATURES.md](./docs/FEATURES.md) | Detailed feature explanations | +| [docs/COMPARISON.md](./docs/COMPARISON.md) | Comparisons with alternatives | +| [docs/DOCKER.md](./docs/DOCKER.md) | Docker installation and configuration | +| [docs/HELM.md](./docs/HELM.md) | Kubernetes/Helm deployment guide | +| [docs/BEST-PRACTICES.md](./docs/BEST-PRACTICES.md) | CI/CD recommendations for best results | + ## 🐛 Reporting Issues ### Hive Mind Issues @@ -655,9 +678,9 @@ All documentation files are automatically checked: find docs/ -name "*.md" -exec wc -l {} + | awk '$1 > 1000 {print "ERROR: " $2 " has " $1 " lines (max 1000)"}' ``` -## Server diagnostics +## Server Diagnostics -Identify screens that are parents of processes that eating the resources +Identify screens that are parents of processes eating the resources: ```bash TARGETS="62220 65988 63094 66606 1028071 4127023" @@ -679,7 +702,7 @@ for p in $TARGETS; do done ``` -Show details about the proccess +Show details about the process: ```bash procinfo() { @@ -732,15 +755,15 @@ procinfo 62220 ## Maintenance -### Reboot server. +### Reboot Server ``` sudo reboot ``` -That will remove all dangling unused proccesses and screens, which will in turn free the RAM and reduce CPU load. Also reboot may clear all temporary files, so next step can do nothing if reboot was done. +That will remove all dangling unused processes and screens, which will in turn free the RAM and reduce CPU load. Also reboot may clear all temporary files, so next step can do nothing if reboot was done. -### Cleanup disk space. +### Cleanup Disk Space ``` df -h @@ -758,7 +781,7 @@ sudo chown root:root /tmp sudo chmod 1777 /tmp ``` -### Close all screens to free up RAM +### Close All Screens to Free up RAM ```bash # close all (Attached or Detached) sessions diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 7fef2234..23ef92eb 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -1,6 +1,6 @@ # Docker Support for Hive Mind -This document explains how to run Hive Mind in Docker containers. +This document explains how to run Hive Mind in Docker containers. For usage instructions after installation, see [USAGE.md](./USAGE.md). ## Quick Start @@ -105,7 +105,8 @@ This approach allows: ├── scripts/ │ └── ubuntu-24-server-install.sh # Installation script used by Dockerfile └── docs/ - └── DOCKER.md # This file + ├── DOCKER.md # This file + └── USAGE.md # Usage instructions (CLI and Telegram bot) ``` ## Advanced Usage @@ -216,7 +217,7 @@ If you're maintaining a fork or want to publish to your own Docker Hub account, 1. Log in to [hub.docker.com](https://hub.docker.com) 2. Click on your username in the top-right corner -3. Select **Account Settings** → **Security** +3. Select **Account Settings** -> **Security** 4. Click **New Access Token** 5. Enter a description (e.g., "GitHub Actions - Hive Mind") 6. Set permissions to **Read, Write, Delete** (required for publishing) @@ -227,7 +228,7 @@ If you're maintaining a fork or want to publish to your own Docker Hub account, ### Step 3: Add Secrets to GitHub Repository 1. Go to your GitHub repository (e.g., `https://github.com/konard/hive-mind`) -2. Click **Settings** → **Secrets and variables** → **Actions** +2. Click **Settings** -> **Secrets and variables** -> **Actions** 3. Click **New repository secret** 4. Add the following two secrets: @@ -275,7 +276,7 @@ env: **Image published but can't pull:** - Ensure the repository on Docker Hub is public (or you're authenticated) -- Check [hub.docker.com](https://hub.docker.com) → Your repositories → hive-mind → Settings → Make Public +- Check [hub.docker.com](https://hub.docker.com) -> Your repositories -> hive-mind -> Settings -> Make Public **Build succeeds but image doesn't appear:** @@ -291,3 +292,11 @@ env: - Authentication happens inside the container after it starts - Each GitHub/Claude account can have its own container instance - Docker Hub access tokens should be stored only as GitHub Secrets, never committed to the repository + +## Next Steps + +After installation and authentication, see [USAGE.md](./USAGE.md) for: + +- CLI commands (`solve`, `hive`) +- Telegram bot setup +- All available options diff --git a/docs/HELM.md b/docs/HELM.md index 08793b47..f8edd62d 100644 --- a/docs/HELM.md +++ b/docs/HELM.md @@ -1,6 +1,6 @@ -# Helm Chart Documentation +# Helm Installation -This document provides comprehensive guidance for deploying Hive Mind on Kubernetes using Helm. +This document covers Kubernetes/Helm installation for Hive Mind. For usage instructions after installation, see [USAGE.md](./USAGE.md). ## Prerequisites @@ -9,7 +9,7 @@ This document provides comprehensive guidance for deploying Hive Mind on Kuberne - `kubectl` configured to access your cluster - Sufficient cluster resources (see [Resource Requirements](#resource-requirements)) -## Installation +## Quick Start ### Add the Helm Repository @@ -41,10 +41,6 @@ helm install hive-mind link-assistant/hive-mind -n hive-mind ## Configuration -### Default Values - -The default `values.yaml` provides sensible defaults for most deployments. Key configuration options: - ### Resource Requirements Default resource allocation: @@ -95,7 +91,7 @@ persistence: ### Authentication Configuration -Hive Mind requires GitHub and Claude authentication. These should be configured via Kubernetes secrets: +Hive Mind requires GitHub and Claude authentication. Configure via Kubernetes secrets: #### Create GitHub Token Secret @@ -151,7 +147,7 @@ env: ### Autoscaling -Enable horizontal pod autoscaling for multiple bot instances: +Enable horizontal pod autoscaling: ```yaml autoscaling: @@ -205,11 +201,11 @@ affinity: topologyKey: kubernetes.io/hostname ``` -## Common Use Cases +## Deployment Examples ### Example 1: Single Bot Instance -Simple deployment for testing or small-scale usage: +Simple deployment for testing: ```yaml # values-simple.yaml @@ -348,7 +344,7 @@ helm rollback hive-mind 2 helm uninstall hive-mind ``` -**Note:** By default, PersistentVolumeClaims are not deleted automatically. To delete them: +**Note:** PersistentVolumeClaims are not deleted automatically. To delete them: ```bash kubectl delete pvc -l app.kubernetes.io/name=hive-mind @@ -466,7 +462,7 @@ volumeMounts: readOnly: true ``` -## Monitoring and Observability +## Monitoring ### Resource Monitoring @@ -478,7 +474,7 @@ kubectl top pods -l app.kubernetes.io/name=hive-mind watch kubectl top pods -l app.kubernetes.io/name=hive-mind ``` -### Logging +### Logging Integration Integrate with logging systems like ELK, Loki, or CloudWatch: @@ -526,13 +522,21 @@ podAnnotations: 5. **Regular Updates:** Keep the chart and container image updated -## Support and Contributing +## Resources - **GitHub Issues:** https://github.com/link-assistant/hive-mind/issues - **Documentation:** https://github.com/link-assistant/hive-mind - **Docker Hub:** https://hub.docker.com/r/konard/hive-mind - **ArtifactHub:** https://artifacthub.io/packages/helm/link-assistant/hive-mind +## Next Steps + +After installation and authentication, see [USAGE.md](./USAGE.md) for: + +- CLI commands (`solve`, `hive`) +- Telegram bot setup +- All available options + ## License This Helm chart is released under the Unlicense. See the [LICENSE](https://github.com/link-assistant/hive-mind/blob/main/LICENSE) file for details. diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 00000000..5ae4f549 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,350 @@ +# Hive Mind: Usage Guide + +This document covers how to use Hive Mind after installation. For installation instructions, see: + +- [README.md](../README.md) - Quick start and Ubuntu 24.04 server installation +- [DOCKER.md](./DOCKER.md) - Docker installation +- [HELM.md](./HELM.md) - Kubernetes/Helm installation + +## Prerequisites + +Before using Hive Mind, ensure you have completed authentication: + +1. **GitHub CLI authentication** - Required for repository access +2. **Claude authentication** - Required for AI operations + +If you haven't authenticated yet, see the [Authentication](#authentication) section below. + +## Usage Options + +Once your environment is set up (via any installation method), you can use Hive Mind in two ways: + +1. **[CLI (Command Line)](#cli-usage)** - Direct terminal commands +2. **[Telegram Bot](#telegram-bot)** - Remote control via Telegram + +--- + +## CLI Usage + +### solve - Solve GitHub Issues + +The `solve` command automatically resolves GitHub issues by creating pull requests. + +```bash +solve [options] +``` + +**Examples:** + +```bash +# Solve using maximum power +solve https://github.com/owner/repo/issues/123 --auto-continue --attach-logs --verbose --model opus --auto-fork --think max + +# Solve with auto-fork if no write access +solve https://github.com/owner/repo/issues/123 --auto-fork --model sonnet + +# Solve issue with PR to custom branch (manual fork mode) +solve https://github.com/owner/repo/issues/123 --base-branch develop --fork + +# Continue working on existing PR +solve https://github.com/owner/repo/pull/456 --model opus + +# Resume from Claude session when limit is reached +solve https://github.com/owner/repo/issues/123 --resume session-id + +# Dry run to see what would happen +solve https://github.com/owner/repo/issues/123 --dry-run +``` + +**Most frequently used options:** + +| Option | Alias | Description | Default | +| --------- | ----- | --------------------------------------- | ------- | +| `--model` | `-m` | AI model to use (sonnet, opus, haiku) | sonnet | +| `--think` | | Thinking level (low, medium, high, max) | - | + +**Other useful options:** + +| Option | Alias | Description | Default | +| --------------- | ----- | --------------------------------------------- | ------- | +| `--tool` | | AI tool (claude, opencode, codex, agent) | claude | +| `--verbose` | `-v` | Enable verbose logging | false | +| `--attach-logs` | | Attach logs to PR (may expose sensitive data) | false | +| `--help` | `-h` | Show all available options | - | + +> **Full options list**: See [CONFIGURATION.md](./CONFIGURATION.md#solve-options) for all available options including forking, auto-continue, watch mode, and experimental features. + +### hive - Orchestrate Multiple Issues + +The `hive` command monitors repositories and solves multiple issues automatically. + +```bash +hive [options] +``` + +**Examples:** + +```bash +# Monitor single repository with specific label +hive https://github.com/owner/repo --monitor-tag "bug" --concurrency 4 + +# Monitor all issues in an organization with auto-fork +hive https://github.com/microsoft --all-issues --max-issues 20 --once --auto-fork + +# Monitor user repositories with high concurrency +hive https://github.com/username --all-issues --concurrency 8 --interval 120 --auto-fork + +# Skip issues that already have PRs +hive https://github.com/org/repo --skip-issues-with-prs --verbose + +# Auto-cleanup temporary files and auto-fork if needed +hive https://github.com/org/repo --auto-cleanup --auto-fork --concurrency 5 +``` + +**Most frequently used options:** + +| Option | Alias | Description | Default | +| -------------- | ----- | --------------------------------------- | ------- | +| `--model` | `-m` | AI model to use (sonnet, opus, haiku) | sonnet | +| `--think` | | Thinking level (low, medium, high, max) | - | +| `--all-issues` | `-a` | Monitor all issues (ignore labels) | false | +| `--once` | | Single run (don't monitor continuously) | false | + +**Other useful options:** + +| Option | Alias | Description | Default | +| ------------------------ | ----- | ---------------------------------------------- | ------- | +| `--tool` | | AI tool (claude, opencode, agent) | claude | +| `--concurrency` | `-c` | Number of parallel workers | 2 | +| `--skip-issues-with-prs` | `-s` | Skip issues with existing PRs | false | +| `--verbose` | `-v` | Enable verbose logging | false | +| `--attach-logs` | | Attach logs to PRs (may expose sensitive data) | false | +| `--help` | `-h` | Show all available options | - | + +> **Full options list**: See [CONFIGURATION.md](./CONFIGURATION.md#hive-options) for all available options including project monitoring, YouTrack integration, and experimental features. + +### Session Management + +```bash +# Resume when Claude hits limit +solve https://github.com/owner/repo/issues/123 --resume 657e6db1-6eb3-4a8d + +# Continue session interactively in Claude Code +(cd /tmp/gh-issue-solver-123456789 && claude --resume session-id) +``` + +### Monitoring & Logging + +Find resume commands in logs: + +```bash +grep -E '\(cd /tmp/gh-issue-solver-[0-9]+ && claude --resume [0-9a-f-]{36}\)' hive-*.log +``` + +--- + +## Telegram Bot + +The Telegram bot provides remote control of Hive Mind from any device. + +### Test Drive + +Want to see the Hive Mind in action? Join our Telegram channel: + +**[Join https://t.me/hive_mind_pull_requests](https://t.me/hive_mind_pull_requests)** + +### Starting the Bot + +**Using Links Notation (recommended):** + +```bash +screen -S bot # Enter new screen for bot + +hive-telegram-bot --configuration " + TELEGRAM_BOT_TOKEN: '849...355:AAG...rgk_YZk...aPU' + TELEGRAM_ALLOWED_CHATS: + -1002975819706 + -1002861722681 + TELEGRAM_HIVE_OVERRIDES: + --all-issues + --once + --skip-issues-with-prs + --attach-logs + --verbose + --no-tool-check + --auto-continue-on-limit-reset + TELEGRAM_SOLVE_OVERRIDES: + --attach-logs + --verbose + --no-tool-check + --auto-continue-on-limit-reset + TELEGRAM_BOT_VERBOSE: true +" + +# Press CTRL + A + D for detach from screen +``` + +**Using individual command-line options:** + +```bash +screen -S bot # Enter new screen for bot + +hive-telegram-bot --token 849...355:AAG...rgk_YZk...aPU --allowed-chats "( + -1002975819706 + -1002861722681 +)" --hive-overrides "( + --all-issues + --once + --skip-issues-with-prs + --attach-logs + --verbose + --no-tool-check + --auto-continue-on-limit-reset +)" --solve-overrides "( + --attach-logs + --verbose + --no-tool-check + --auto-continue-on-limit-reset +)" --verbose + +# Press CTRL + A + D for detach from screen +``` + +**Note:** Register your own bot with https://t.me/BotFather to get the bot token. + +### Bot Commands + +All commands work in **group chats only** (not in private messages): + +#### `/solve` - Solve GitHub Issues + +``` +/solve [options] + +Examples: +/solve https://github.com/owner/repo/issues/123 --model sonnet +/solve https://github.com/owner/repo/issues/123 --model opus --think max +``` + +#### `/hive` - Run Hive Orchestration + +``` +/hive [options] + +Examples: +/hive https://github.com/owner/repo +/hive https://github.com/owner/repo --all-issues --max-issues 10 +/hive https://github.com/microsoft --all-issues --concurrency 3 +``` + +#### `/limits` - Show Usage Limits + +``` +/limits + +Shows: +- CPU usage and load average +- RAM usage (used vs total) +- Disk space usage +- GitHub API rate limits +- Claude usage limits (session and weekly) +``` + +#### `/help` - Get Help and Diagnostic Info + +``` +/help + +Shows: +- Chat ID (needed for TELEGRAM_ALLOWED_CHATS) +- Chat type +- Available commands +- Usage examples +``` + +### Bot Features + +- **Group Chat Only**: Commands work only in group chats (not private messages) +- **Full Options Support**: All command-line options work in Telegram +- **Screen Sessions**: Commands run in detached screen sessions +- **Chat Restrictions**: Optional whitelist of allowed chat IDs +- **Diagnostic Tools**: Get chat ID and configuration info + +### Bot Security Notes + +- Only works in group chats where the bot is admin +- Optional chat ID restrictions via `TELEGRAM_ALLOWED_CHATS` +- Commands run as the system user running the bot +- Ensure proper authentication (`gh auth login`, `claude`) + +--- + +## Authentication + +### GitHub CLI Authentication + +```bash +gh-setup-git-identity +``` + +Or manually: + +```bash +gh auth login -h github.com -s repo,workflow,user,read:org,gist +``` + +Follow the prompts to authenticate with your GitHub account. The system will perform all actions using this account. + +### Claude Authentication + +```bash +claude +``` + +Follow the on-screen instructions to complete authentication. + +### Codex Authentication (Optional) + +For OpenAI Codex users: + +1. Connect to your instance with SSH tunnel: + + ```bash + ssh -L 1455:localhost:1455 root@123.123.123.123 + ``` + +2. Start codex login OAuth server: + + ```bash + codex login + ``` + +3. Copy the OAuth link and open it in your browser on the machine where you started the tunnel. + +--- + +## Advanced Usage + +### Review Commands (Alpha) + +```bash +# Run collaborative review process +review --repo owner/repo --pr 456 + +# Multiple AI reviewers for consensus +./reviewers-hive.mjs --agents 3 --consensus-threshold 0.8 +``` + +### Environment Variables & Configuration + +For comprehensive configuration including environment variables, timeouts, retry limits, Telegram bot settings, YouTrack integration, and all CLI options, see [CONFIGURATION.md](./CONFIGURATION.md). + +--- + +## Getting Help + +- Use `--help` flag with any command for detailed options +- See [CONFIGURATION.md](./CONFIGURATION.md) for full configuration reference +- See [FEATURES.md](./FEATURES.md) for feature explanations +- See [COMPARISON.md](./COMPARISON.md) for comparisons with alternatives +- Report issues at https://github.com/link-assistant/hive-mind/issues