A CLI tool for orchestrating local development services in a tmux session. Perfect for microservices and polyglot projects with automatic service discovery and before/after script support.
npm install @abyrd9/harbor-cliA 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.
- š ļø 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
``bash`
bun add -g @abyrd9/harbor-cli
`bash`
npm install -g @abyrd9/harbor-cli
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.
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.
Harbor supports two configuration formats:
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"
}
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!'"
}
]
}
}
| 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 |
| 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 |
- -p, --path : Specify project root path (defaults to ./)
Harbor automatically detects and configures services for:
- Node.js: package.json ā npm run devgo.mod
- Go: ā go run .Cargo.toml
- Rust: ā cargo runrequirements.txt
- Python: ā python app.pycomposer.json
- PHP: ā php artisan servepom.xml
- Java: /build.gradle ā mvn spring-boot:run or ./gradlew bootRun
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
Harbor uses tmux for professional service management. Essential shortcuts:
- 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 paneAdvanced 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 outputUse 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 directory3. 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 launchExamples
$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)
``Contributions are welcome! Please feel free to:
- Report bugs and request features via GitHub Issues
- Submit pull requests for improvements
- Help improve documentation
MIT - See LICENSE file for details