Harbor CLI

A CLI tool for managing local development services with ease. Harbor helps you orchestrate multiple development services in a tmux session, perfect for microservices and polyglot projects.

✨ Features

• 🛠️ Automatic Service Discovery: Detects project types and suggests appropriate commands
• 📁 Flexible Configuration: Store config in harbor.json or package.json
• 🚀 One-Command Launch: Start all services with a single command
• 🔄 Dependency Management: Automatically checks for required system dependencies
• 🎯 Multi-Language Support: Works with Node.js, Go, Rust, Python, PHP, Java, and more
• 🖥️ Tmux Integration: Professional terminal multiplexing for service management
• 📝 Service Logging: Stream service output to log files for monitoring and debugging
• 🏷️ Custom Session Names: Configure unique tmux session names
• 🤖 AI Agent Integration: Inter-pane communication lets AI agents observe and interact with services

Installation

bun add -g @abyrd9/harbor-cli

npm install -g @abyrd9/harbor-cli

Prerequisites

Harbor automatically checks for these required dependencies:

• tmux - Terminal multiplexer for managing services
• jq - JSON processor for service management

If missing, Harbor will provide installation instructions.

Quick Start

1. Initialize your project:

   harbor dock

   This scans your directory structure and creates a harbor configuration.

2. Add more services (optional):

   harbor moor

   Scans for new services and adds them to your configuration.

3. Launch all services:

   harbor launch

   Starts all configured services in organized tmux windows.

Configuration

Harbor supports two configuration formats:

Option 1: harbor.json

Create a dedicated configuration file:

{
  "services": [
    {
      "name": "database",
      "path": "./db",
      "preStage": {
        "command": "docker-compose up -d postgres",
        "wait": 5,
        "timeout": 60
      },
      "command": "npm run dev",
      "log": true,
      "maxLogLines": 500
    },
    {
      "name": "api",
      "path": "./go-api",
      "preStage": {
        "command": "go mod download",
        "wait": 2
      },
      "command": "go run .",
      "log": true,
      "maxLogLines": 500
    },
    {
      "name": "frontend",
      "path": "./vite-frontend",
      "command": "npm run dev",
      "log": true
    }
  ],
  "before": [
    {
      "path": "./",
      "command": "echo 'Starting development environment...' && docker-compose up -d"
    },
    {
      "path": "./scripts",
      "command": "./setup-dev.sh"
    }
  ],
  "after": [
    {
      "path": "./",
      "command": "echo 'Development environment ready!'"
    }
  ],
  "sessionName": "my-project-dev"
}

Option 2: package.json

Store configuration directly in your package.json:

{
  "name": "my-project",
  "version": "1.0.0",
  "harbor": {
    "services": [
      {
        "name": "frontend",
        "path": "./frontend",
        "command": "npm run dev"
      },
      {
        "name": "api",
        "path": "./api",
        "command": "go run main.go"
      }
    ],
    "before": [
      {
        "path": "./",
        "command": "docker-compose up -d database"
      }
    ],
    "after": [
      {
        "path": "./",
        "command": "echo 'All services are running!'"
      }
    ]
  }
}

Commands

| Command | Description | |---------|-------------| | harbor dock | Initialize Harbor config by auto-discovering services in your project | | harbor moor | Scan for and add new services to your existing Harbor configuration | | harbor launch | Start all services in a tmux session (-d for headless) | | harbor anchor | Attach to a running Harbor session | | harbor scuttle | Stop all services and kill the session | | harbor bearings | Show status of running services | | harbor --help | Show comprehensive help with feature descriptions | | harbor --version | Show version information |

Inter-Pane Communication

| Command | Description | |---------|-------------| | harbor hail <service> "<cmd>" | Send keystrokes to another service pane | | harbor survey <service> | Capture output from a service pane | | harbor parley <service> "<cmd>" | Execute command and capture response | | harbor whoami | Show current pane identity and access | | harbor context | Output full session context for AI agents |

Command Options

• -p, --path <path>: Specify project root path (defaults to ./)

Supported Project Types

Harbor automatically detects and configures services for:

• Node.js: package.json → npm run dev
• Go: go.mod → go run .
• Rust: Cargo.toml → cargo run
• Python: requirements.txt → python app.py
• PHP: composer.json → php artisan serve
• Java: pom.xml/build.gradle → mvn spring-boot:run or ./gradlew bootRun

How It Works

1. Service Discovery: Harbor scans your directory for folders containing project files
2. Command Detection: Based on project type, suggests appropriate development commands
3. Configuration Generation: Creates/updates harbor config with discovered services
4. Tmux Session: Launches each service in its own tmux window with proper working directories
5. Process Management: All services run independently with proper I/O handling

Terminal Multiplexer (Tmux)

Harbor uses tmux for professional service management. Essential shortcuts:

Session Management

• Ctrl+a d - Detach from session (services continue running)
• Ctrl+a :attach - Reattach to session
• Ctrl+a & - Kill current window
• Ctrl+a ? - Show all keybindings

Window Navigation

• Ctrl+a c - Create new window
• Ctrl+a n - Next window
• Ctrl+a p - Previous window
• Ctrl+a 0-9 - Jump to window number
• Ctrl+a w - List all windows

Pane Management

• Ctrl+a % - Split window vertically
• Ctrl+a " - Split window horizontally
• Ctrl+a →/←/↑/↓ - Navigate between panes
• Ctrl+a x - Close current pane

Advanced Usage

Custom Commands

Override auto-detected commands by editing your configuration:

{
  "services": [
    {
      "name": "custom-service",
      "path": "./my-service",
      "command": "custom-command --with-flags"
    }
  ]
}

Service Logging for AI Agents

Enable logging to stream service output to files in .harbor/. This is particularly useful when working with AI coding assistants (like Opencode, Codex, or Claude) that can read log files to understand what's happening in your services.

{
  "services": [
    {
      "name": "api",
      "path": "./api",
      "command": "go run .",
      "log": true,
      "maxLogLines": 500
    },
    {
      "name": "frontend",
      "path": "./frontend", 
      "command": "npm run dev",
      "log": true
    }
  ]
}

Options:

• log: true to enable logging (default: false)
• maxLogLines: Maximum lines to keep in log file (default: 1000)

Log files are:

• Stored in .harbor/ directory (add to .gitignore manually)
• Named {session}-{service}.log (e.g., local-dev-test-api.log)
• Automatically trimmed to prevent unbounded growth
• Stripped of ANSI escape codes for clean, readable output

Use case: Point your AI assistant to the .harbor/ folder so it can monitor service logs, spot errors, and understand runtime behavior while helping you develop.

Inter-Pane Communication for AI Agents

Harbor enables AI agents running in one pane to observe and interact with other services. This is powerful for AI-assisted development workflows where an agent needs to monitor logs, send commands to REPLs, or coordinate between services.

Configuration

Add canAccess to specify which services a pane can communicate with:

{
  "services": [
    {
      "name": "repl",
      "path": "./backend",
      "command": "bin/mycli"
    },
    {
      "name": "agent",
      "path": ".",
      "command": "opencode",
      "canAccess": ["repl", "web"]
    },
    {
      "name": "web",
      "path": "./frontend",
      "command": "npm run dev"
    }
  ]
}

Commands

Survey - Capture output from another pane:

harbor survey repl --lines 50

Hail - Send keystrokes to another pane (fire-and-forget):

harbor hail repl "user query --email [email protected]"

Parley - Execute command and capture response (uses markers for clean output):

harbor parley repl "users" --timeout 5000

Whoami - Check current pane identity and access:

harbor whoami

Context - Get full session documentation (markdown, great for AI context):

harbor context

Access Control

• Services can only access panes listed in their canAccess array
• Commands run from outside tmux (external terminal) bypass access control
• Access is enforced based on the HARBOR_SERVICE environment variable

Environment Variables

Each pane automatically receives these environment variables:

• HARBOR_SESSION - Session name
• HARBOR_SOCKET - Tmux socket name
• HARBOR_SERVICE - Current service name
• HARBOR_WINDOW - Window number

Use Case: AI Agent Integration

Add to your agent's instructions:

When starting, run `harbor whoami` to check your harbor context.
Use `harbor survey <service>` to observe other panes.
Use `harbor parley <service> "<cmd>"` to interact with REPLs/CLIs.

Before/After Scripts

Run custom scripts before and after your services start:

{
  "before": [
    {
      "path": "./infrastructure",
      "command": "docker-compose up -d"
    },
    {
      "path": "./",
      "command": "npm run setup:dev"
    }
  ],
  "after": [
    {
      "path": "./",
      "command": "npm run seed:database"
    },
    {
      "path": "./scripts",
      "command": "./notify-dev-ready.sh"
    }
  ]
}

Execution Flow:

1. Before scripts run sequentially before services start
2. Services launch in tmux windows
3. After scripts run sequentially after services are ready

Use Cases:

• Set up databases or infrastructure
• Run database migrations or seeds
• Send notifications when environment is ready
• Clean up temporary files
• Run integration tests

Selective Launch

Currently launches all services. Future versions may support selective service launching.

Environment Variables

Services inherit your shell environment. Use .env files or export variables before running harbor launch.

Troubleshooting

Common Issues

1. "Missing required dependencies"

   • Install tmux and jq as indicated in the error message

2. "No harbor configuration found"

   • Run harbor dock to initialize configuration
   • Ensure you're in the correct project directory

3. Services not starting

   • Check that commands are correct in your harbor configuration
   • Verify project dependencies are installed in each service directory
   • Check tmux windows for error messages

4. Tmux not responding

   • Try tmux kill-session -t harbor to clean up
   • Restart with harbor launch

Examples

Monorepo Setup

my-project/
├── frontend/     (package.json)
├── backend/      (go.mod)
├── database/     (docker-compose.yml)
└── harbor.json

Polyglot Microservices

services/
├── auth-service/     (Node.js)
├── user-service/     (Go)
├── payment-service/  (Python)
└── notification-service/ (Rust)

Contributing

Contributions are welcome! Please feel free to:

• Report bugs and request features via GitHub Issues
• Submit pull requests for improvements
• Help improve documentation

License

MIT - See LICENSE file for details