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

``bash
bun add -g @abyrd9/harbor-cli
`

`bash
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:
`bash
harbor dock
`
This scans your directory structure and creates a harbor configuration.

2. Add more services (optional):
`bash
harbor moor
`
Scans for new services and adds them to your configuration.

3. Launch all services:
`bash
harbor launch
`
Starts all configured services in organized tmux windows.

Configuration

Harbor supports two configuration formats:

$3

Create a dedicated configuration file:

`json
{
"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"
}
`

$3

Store configuration directly in your package.json:

`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 |

$3

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

$3

- -p, --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:

$3


- 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

$3

- 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

$3

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

Advanced Usage

$3

Override auto-detected commands by editing your configuration:

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

$3

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.

`json
{
"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.

$3

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:

`json
{
"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:
`bash
harbor survey repl --lines 50
`

Hail - Send keystrokes to another pane (fire-and-forget):
`bash
harbor hail repl "user query --email test@example.com"
`

Parley - Execute command and capture response (uses markers for clean output):
`bash
harbor parley repl "users" --timeout 5000
`

Whoami - Check current pane identity and access:
`bash
harbor whoami
`

Context - Get full session documentation (markdown, great for AI context):
`bash
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:

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

$3

Run custom scripts before and after your services start:

`json
{
"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

$3

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

$3

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

Troubleshooting

$3

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

$3


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

$3

`
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