@cometdigitalagency/kanban-teams-sync

Auto-sync pi-teams task board to pi-kanban web dashboard for Oh My Pi (OMP).

This extension automatically mirrors your team's pi-teams tasks to pi-kanban format, enabling real-time visualization in a web UI with hot-reload via Server-Sent Events (SSE). No manual refresh needed—tasks update instantly on the kanban board.

Features

✅ Automatic Sync — Tasks sync every 2 seconds (configurable)
✅ Real-Time Hot Reload — Changes appear instantly via SSE
✅ Multi-Team Support — Sync multiple teams simultaneously
✅ Auto-Start — Runs on OMP session startup
✅ Watch Mode — Detects new, modified, and deleted tasks
✅ Zero Config — Works out-of-the-box after installation

Quick Start

1. Prerequisites

• OMP (Oh My Pi) installed and running
• pi-kanban web dashboard running (see setup below)
• pi-teams tasks directory: ~/.pi/tasks/

2. Install Package

omp install npm:@cometdigitalagency/kanban-teams-sync

3. Configure OMP

Edit ~/.omp/settings.json:

{
  "packages": [
    "@cometdigitalagency/kanban-teams-sync"
  ],
  "env": {
    "OMP_TEAMS_SYNC": "software",
    "OMP_TEAMS_SYNC_INTERVAL": "2000",
    "OMP_TEAMS_SYNC_ENABLED": "true"
  }
}

4. Reload OMP

omp /reload

On startup, you should see:

[omp-pi-teams-kanban-sync] Initialized with teams: software
[sync] watching software (interval: 2000ms)

5. View in pi-kanban

The kanban dashboard should auto-detect the session. Look for pi-teams/software in the sessions list.

---

Complete Setup Guide

Install OMP

# Install Oh My Pi globally
npm install -g @oh-my-pi/cli

# Start OMP
omp

Install pi-kanban

pi-kanban is a separate tool that visualizes pi-teams tasks. Install and run it:

# Clone or download pi-kanban
git clone https://github.com/NikiforovAll/pi-kanban.git
cd pi-kanban

# Install dependencies
npm install

# Start the web server (runs on http://localhost:3460)
node server.js

Or use npx:

npx pi-kanban

Install This Extension

Once OMP is running, install the kanban-teams-sync extension:

# In OMP session
omp install npm:@cometdigitalagency/kanban-teams-sync

Or manually edit ~/.omp/settings.json:

{
  "packages": [
    "@cometdigitalagency/kanban-teams-sync"
  ],
  "env": {
    "OMP_TEAMS_SYNC": "software",
    "OMP_TEAMS_SYNC_INTERVAL": "2000",
    "OMP_TEAMS_SYNC_ENABLED": "true"
  }
}

Reload OMP:

omp /reload

---

How It Works

Architecture:

pi-teams tasks           → kanban-teams-sync → pi-kanban format
~/.pi/tasks/software/    → (watch mode)       → ~/.pi/agent/kanban/tasks/pi-teams-software/
   ↓                     ↓                      ↓
JSON task files      Sync every 2s         Web UI displays tasks
   (source)          (auto-detect)         (hot reload via SSE)

Startup Flow:

1. OMP starts
2. Extension initializes
3. Spawns watch process for each configured team
4. Creates synthetic JSONL session file for pi-kanban discovery
5. Watches task directory every 2 seconds for changes
6. Syncs any changes to kanban format in real-time

Sync Features:

• ✅ New tasks detected automatically
• ✅ Modified tasks updated instantly
• ✅ Deleted tasks marked as deleted (not removed)
• ✅ Task relationships (blockedBy, blocks) preserved
• ✅ Metadata synced (description, team, priority)

---

Configuration

Environment Variables

Configure in ~/.omp/settings.json:

Variable	Default	Description
OMP_TEAMS_SYNC	software	Comma-separated team names to sync (e.g., software,product,ops)
OMP_TEAMS_SYNC_INTERVAL	2000	Sync interval in milliseconds
OMP_TEAMS_SYNC_ENABLED	true	Enable/disable auto-sync

Multiple Teams

{
  "env": {
    "OMP_TEAMS_SYNC": "software,product,infrastructure",
    "OMP_TEAMS_SYNC_INTERVAL": "3000"
  }
}

This will sync three teams and check for changes every 3 seconds.

---

Testing

1. Verify Manual Sync

node ~/.pi/scripts/sync-pi-teams-to-kanban.mjs software

Expected output:

[2026-06-09T...] synced software: 5 tasks

2. Test Watch Mode

Terminal 1: Start watch mode

node ~/.pi/scripts/sync-pi-teams-to-kanban.mjs software --watch

Terminal 2: Create a task

cat > ~/.pi/tasks/software/test-task.json << 'EOF'
{
  "id": "test-task",
  "subject": "🎯 Test Task",
  "description": "This is a test task",
  "status": "pending",
  "blocks": [],
  "blockedBy": []
}
EOF

Terminal 1: Should show within 2 seconds

[2026-06-09T...] synced software: 6 tasks

3. Test OMP Auto-Start

omp /reload

Watch for log messages:

[omp-pi-teams-kanban-sync] Initialized with teams: software
[sync] watching software (interval: 2000ms)

4. Verify Kanban Display

Open pi-kanban: http://localhost:3460

Look for session named pi-teams/software with your tasks displayed.

---

Directories

Source (pi-teams)

~/.pi/tasks/software/
├── task-1.json
├── task-2.json
└── ...

Output (pi-kanban format)

~/.pi/agent/kanban/tasks/pi-teams-software/
├── task-1.json (synced)
├── task-2.json (synced)
└── ...

Session Metadata

~/.pi/agent/sessions/pi-teams/
└── pi-teams-software.jsonl (pi-kanban discovery)

---

Troubleshooting

Tasks Not Syncing

# 1. Check if script exists
ls ~/.pi/scripts/sync-pi-teams-to-kanban.mjs

# 2. Run manual sync
node ~/.pi/scripts/sync-pi-teams-to-kanban.mjs software

# 3. Check source tasks
ls ~/.pi/tasks/software/

# 4. Check synced output
ls ~/.pi/agent/kanban/tasks/pi-teams-software/

Extension Not Loading

# Verify config
cat ~/.omp/settings.json | jq .

# Check package is installed
npm list @cometdigitalagency/kanban-teams-sync

# Reinstall
omp install npm:@cometdigitalagency/kanban-teams-sync

# Reload
omp /reload

pi-kanban Not Detecting Tasks

# Verify session file exists
cat ~/.pi/agent/sessions/pi-teams/pi-teams-software.jsonl

# Verify kanban task files exist
ls ~/.pi/agent/kanban/tasks/pi-teams-software/

# Restart pi-kanban
# (It watches for changes automatically)

---

Publishing Notes

This package is published to npm as @cometdigitalagency/kanban-teams-sync.

To authenticate and publish (maintainers only):

# Login to npm
npm login --scope=@cometdigitalagency

# Publish
npm publish --access public

---

Development

Run Locally

cd ~/Documents/GitHub/omp/kanban-teams-sync
npm run dev

Build

TypeScript source compiles to JavaScript on-the-fly via tsx loader.

---

Links

• Repository: https://github.com/cometdigitalagency/kanban-teams-sync
• NPM Package: https://npmjs.com/package/@cometdigitalagency/kanban-teams-sync
• pi-kanban: https://github.com/NikiforovAll/pi-kanban
• Oh My Pi: https://github.com/oh-my-pi/omp

---

License

MIT

Restart OMP:

omp /reload

On startup, you'll see:

[omp-pi-teams-kanban-sync] Initialized with teams: software
[sync] watching software (interval: 2000ms)

View in pi-kanban

/kanban open web

Look for sessions named pi-teams/software, pi-teams/product, etc.

How it works

Startup:

• Extension runs on OMP session start
• Spawns sync script for each team in OMP_TEAMS_SYNC
• Syncs once, then watches for changes every 2 seconds (configurable)

One-way sync:

• Source: ~/.pi/tasks/<team>/*.json (pi-teams)
• Output: ~/.pi/agent/kanban/tasks/pi-teams-<team>/ (pi-kanban format)
• Creates synthetic JSONL session so pi-kanban discovers the team
• Deletes removed tasks automatically

Watch mode:

• Polls every 2 seconds (default)
• Detects new, modified, and deleted tasks
• Mirrors changes to pi-kanban format immediately

Testing

1. Manual sync

node ~/.pi/scripts/sync-pi-teams-to-kanban.mjs software

Expected:

[2026-06-09T...] synced software: 3 tasks

Check files created:

ls ~/.pi/agent/kanban/tasks/pi-teams-software/
ls ~/.pi/agent/sessions/pi-teams/pi-teams-software.jsonl

2. Watch mode

Terminal 1:

node ~/.pi/scripts/sync-pi-teams-to-kanban.mjs software --watch

Terminal 2 (create a task):

omp -p "Create a task in the software team with subject 'Test task'"

Terminal 1 should show sync output within 2 seconds:

[2026-06-09T...] synced software: 4 tasks

3. OMP auto-start

omp /reload

Check logs:

[omp-pi-teams-kanban-sync] Initialized with teams: software
[sync] watching software (interval: 2000ms)

4. View results

/kanban open web

Navigate to pi-teams/software session. Tasks should match ~/.pi/tasks/software/.

Configuration

Variable	Default	Purpose
OMP_TEAMS_SYNC	software	Comma-separated teams to sync
OMP_TEAMS_SYNC_INTERVAL	2000	Watch interval in milliseconds
OMP_TEAMS_SYNC_ENABLED	true	Enable/disable auto-sync

Example: sync multiple teams

{
  "env": {
    "OMP_TEAMS_SYNC": "software,product,ops",
    "OMP_TEAMS_SYNC_INTERVAL": "3000"
  }
}

License

MIT