Huly Vibe Sync
Bidirectional synchronization service between Huly and Vibe Kanban using Model Context Protocol (MCP)
Ask AI about Huly Vibe Sync
Powered by Claude Β· Grounded in docs
I know everything about Huly Vibe Sync. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Huly-Vibe Sync Service
Bidirectional synchronization service between Huly and Vibe Kanban using the Model Context Protocol (MCP).
Features
- β Bidirectional Sync: Huly β Vibe Kanban for project and task state
- β REST API Integration: Fast, efficient Huly REST API client for optimal performance
- β Incremental Sync: Only fetches issues modified since last sync (timestamp-based)
- β‘ Parallel Processing: Concurrent project sync with configurable workers (default: 5)
- π Smart Caching: Skips empty projects to reduce API load
- β±οΈ Fast Sync: 10-second intervals for near real-time updates (~3-5s per cycle)
- β Full Description Support: Multi-line issue descriptions preserved with all formatting
- β Status Synchronization: Task status changes sync both ways (Huly and Vibe)
- β Filesystem Path Mapping: Automatic project path detection from Huly descriptions
- β Configurable Intervals: Run once, continuous sync, or on-demand
- β Docker Support: Fully containerized with health checks
- β MCP Fallback: Optional MCP protocol support for backwards compatibility
Performance
Current Configuration (Optimized):
- Sync Interval: 10 seconds (configurable)
- Incremental Sync Time: 3-5 seconds (only fetches changed issues)
- Active Projects: Processes only ~8-10 projects with issues (skips 30+ empty)
- Parallel Workers: 5 concurrent project syncs
- Near Real-Time: Changes sync within 10-15 seconds
Previous (Sequential):
- Sync Interval: 30 seconds
- Full Sync Time: 25-30 seconds
- All 44 projects processed sequentially
Quick Start
Using Pre-built Docker Image (Recommended)
# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/oculairmedia/huly-vibe-sync:latest
# Or use docker-compose with the pre-built image
cd /opt/stacks/huly-vibe-sync
cp .env.example .env
# Edit docker-compose.yml to use: image: ghcr.io/oculairmedia/huly-vibe-sync:latest
docker-compose up -d
docker-compose logs -f
Building from Source
cd /opt/stacks/huly-vibe-sync
cp .env.example .env
docker-compose build
docker-compose up -d
docker-compose logs -f
Docker Images
Pre-built Docker images are automatically published to GitHub Container Registry:
- Latest (main branch):
ghcr.io/oculairmedia/huly-vibe-sync:latest - Develop branch:
ghcr.io/oculairmedia/huly-vibe-sync:develop - Tagged releases:
ghcr.io/oculairmedia/huly-vibe-sync:v1.0.0 - Commit SHA:
ghcr.io/oculairmedia/huly-vibe-sync:main-<sha>
Images are built for both linux/amd64 and linux/arm64 platforms.
Configuration
Environment Variables
See .env.example for all available options. Key settings:
# Core Settings
HULY_API_URL=http://192.168.50.90:3457/api
HULY_USE_REST=true
VIBE_MCP_URL=http://192.168.50.90:9717/mcp
# Sync Behavior
SYNC_INTERVAL=10000 # 10 seconds (default: 10000ms)
INCREMENTAL_SYNC=true # Only fetch changed issues
PARALLEL_SYNC=true # Process projects concurrently
MAX_WORKERS=5 # Max concurrent API calls
SKIP_EMPTY_PROJECTS=true # Skip projects with 0 issues
# Dry Run Mode
DRY_RUN=false # Set to true for testing
Performance Tuning
For faster sync:
- Reduce
SYNC_INTERVALto 5000 (5 seconds) or 3000 (3 seconds) - Increase
MAX_WORKERSto 8-10 (monitor API load) - Enable
SKIP_EMPTY_PROJECTS=true(recommended)
For lower API load:
- Increase
SYNC_INTERVALto 30000 (30 seconds) or higher - Reduce
MAX_WORKERSto 3 - Set
PARALLEL_SYNC=falsefor sequential processing
Monitor performance:
docker logs huly-vibe-sync 2>&1 | grep "Slow tool execution"
docker logs huly-vibe-sync 2>&1 | grep "sync completed"
Documentation
π Local Documentation
Comprehensive documentation is organized in the docs/ directory:
- Documentation Index - Complete documentation overview
- API Reference - API specifications and integration guides
- Architecture - System design and architecture
- Guides - Deployment, testing, and agent management
- Deployment Guide - Quick deployment reference
- Testing Guide - Testing documentation
π External Documentation
See comprehensive documentation in BookStack under "MCP Integration Research" β "Huly-Vibe Bidirectional Sync Service"
Project Registry API
Register a project
POST /api/registry/projects
Request body:
{
"filesystem_path": "/opt/stacks/letta-mobile-bz40.2.8",
"name": "Letta Mobile",
"git_url": "https://github.com/oculairmedia/letta-mobile-bz40.2.8.git"
}
filesystem_pathis required and must be an absolute pathnameandgit_urlare optional- the path must exist and be a git repository
Update a project
PATCH /api/registry/projects/:id
Request body:
{
"filesystem_path": "/opt/stacks/letta-mobile",
"git_url": "https://github.com/oculairmedia/letta-mobile.git"
}
filesystem_pathmust be absolute when provided- existing fields are preserved when omitted
- returns the updated project row
CLI usage
Register a project:
npm run vibesync -- project-register /opt/stacks/letta-mobile-bz40.2.8 \
--name "Letta Mobile" \
--git-url "https://github.com/oculairmedia/letta-mobile-bz40.2.8.git"
Update project path or git URL:
npm run vibesync -- project-update LETTAMOBILE \
--filesystem-path /opt/stacks/letta-mobile \
--git-url "https://github.com/oculairmedia/letta-mobile.git"
