omp-huly

Native Huly support cho oh-my-pi (omp) — ~102 tools + native Huly client. KHÔNG MCP, gọi thẳng Huly WebSocket/REST API. Fork của pi-huly.

Status: Ported from pi-huly 1.0.0-beta.14 → omp-huly 0.1.0 (2026-07-30). Tools-only package; skills maintained separately in ~/.omp/agent/skills/.

Tại sao omp-huly?

omp-huly là fork của pi-huly, retarget từ pi-coding-agent sang oh-my-pi (omp). Đóng gói ~102 tools thiết yếu chạy native trong omp process, kèm Huly client WebSocket/REST.

| Vấn đề | omp-huly giải quyết | |---|---| | MCP server riêng (process phụ thuộc, env vars) | 1 package native, cùng lifecycle session | | ~470 tools nhiễu LLM | ~102 tools full-CRUD-per-domain, không gap lifecycle | | Hosted Huly SaaS shutdown 2026-07-20 | Target self-hosted Huly từ đầu | | pi-huly only works on pi | Port sang omp — chạy trên oh-my-pi |

Features

• 🔑 Native, không MCP — tools chạy trong omp process, không spawn process ngoài.
• 🔑 Lean + complete — 102 tools full-CRUD-per-domain, không nhiễu context.
• 🔒 Multi-workspace — lưu token/password mỗi workspace, switch qua /huly.
• 🔀 Transport toggle — WebSocket (persistent, pool) hoặc REST (stateless), default ws.
• 🛡️ Confirm gate — destructive ops (delete) yêu cầu confirm; non-TUI auto-deny.
• 🔁 Markdown round-trip — Huly markup ↔ markdown lossless (native ref links).
• 🎨 TUI render — huly_get_issue card, huly_list_issues table, huly_get_document preview.

Requirements

• Bun ≥ 1.3.14 (omp runtime).
• oh-my-pi (omp) — peer dependencies @oh-my-pi/pi-coding-agent, @oh-my-pi/pi-tui.
• Self-host Huly instance (KHÔNG support hosted SaaS — đã shutdown 2026-07-20). Hướng dẫn self-host: https://docs.huly.io/self-host/.
• @hcengineering/* deps publish public trên npmjs.org (KHÔNG cần GitHub Packages token).

Install

omp install npm:omp-huly

Hoặc từ source:

git clone https://github.com/techio-dev/omp-huly.git
cd omp-huly
pnpm install        # no token needed — @hcengineering public on npm
pnpm run typecheck  # verify toolchain
pnpm run build      # → dist/index.mjs

Quick start (3 bước)

# 1. Cài package
omp install npm:omp-huly

# 2. Bind workspace cho cwd hiện tại (interactive — chọn workspace + project)
/huly init

# 3. Dùng tool (LLM tự gọi, hoặc bạn invoke qua prompt)
#    VD: "Tạo issue PD-1: 'Setup CI' priority high"
#    → LLM gọi huly_create_issue({project:"PD", title:"Setup CI", priority:"high"})

Configuration

omp-huly dùng 2 file global (KHÔNG env vars, KHÔNG project-local):

• ~/.omp/agent/huly/credentials.json (chmod 600, KHÔNG commit) — auth union per workspace.

  Existing pi-huly users: credentials auto-migrate từ ~/.pi/agent/huly/credentials.json → ~/.omp/agent/huly/credentials.json on first load.

  {
    "workspaces": {
      "myteam": {
        "url": "https://huly.example.com",
        "workspace": "myteam",
        "token": "tok_xxx"
      }
    }
  }

  Hoặc email/password:

  {
    "workspaces": {
      "myteam": {
        "url": "https://huly.example.com",
        "workspace": "myteam",
        "email": "[email protected]",
        "password": "pass123"
      }
    }
  }

• ~/.omp/agent/huly/config.json (non-secret) — transport + cwd binding.

  Existing pi-huly users: config auto-migrate từ ~/.pi/agent/huly/config.json.

  {
    "version": 1,
    "transport": "ws",
    "projects": {
      "/Users/me/projects/myapp": { "workspace": "myteam", "project": "PD" }
    }
  }

Cả 2 file được tạo/quản lý qua /huly init. KHÔNG edit tay trừ khi cần. Secret CHỈ trong credentials.json, KHÔNG log.

/huly command guide

Unified command, git-like subcommands:

| Subcommand | Mô tả | |---|---| | /huly | Smart: cwd bound → status; unbound → init flow | | /huly init | Setup/bind cwd (chọn workspace → verify → project → bind) | | /huly status | Diagnostics: binding, pool health, user, version | | /huly workspace list | List workspace đã config | | /huly workspace add | Add workspace (url + auth) | | /huly workspace remove <id> | Remove workspace | | /huly link [ws] [project] | Bind cwd manual | | /huly unlink | Remove cwd binding |

Tool catalog (19 domains, 102 tools)

| Domain | Tools | VD | |---|---|---| | Issues | 21 | create/list/get/update/delete/move_issue, add/remove_label, relations, templates | | Documents | 10 | create/edit/get/delete_document, teamspace CRUD | | Projects | 6 | create/list/get/update/delete_project, list_statuses | | Milestones | 6 | CRUD + set_issue_milestone | | Components | 6 | CRUD + set_issue_component | | Comments | 4 | list/add/update/delete_comment | | Workspace | 5 | get_workspace_info, list_workspaces/members, get/update_user_profile | | Labels | 4 | list/create/update/delete_label (GLOBAL namespace) | | Tags | 7 | CRUD + attach/detach/list_attached | | Tag-categories | 4 | CRUD | | Attachments | 5 | list/get/add/download (incl issue attachment) | | Todos | 7 | list/get/create/update/complete/reopen/delete | | Search | 1 | fulltext_search (global) | | Deletion | 1 | preview_deletion (cascade preview) | | Time | 1 | log_time (minutes) | | Contacts | 2 | list_employees, list_persons (assignee resolution) | | Task-management | 5 | create_issue_status, create_task_type, list/get_project_type | | Spaces | 5 | list/get_space, list/get/update_space_type | | Snapshots | 2 | list/get_document_snapshot |

Mọi tool có prefix huly_ (vd huly_create_issue). Common params:

• workspace? — override workspace (default: cwd-map)
• project? — project-scoped (issues/milestones/components)
• identifier — issue: PD-123 hoặc raw 123
• assignee? — auto-resolve currentUser email khi absent

Skills (separate package)

omp-huly là tools-only package. Huly skills (huly-docs, huly-tasks) được maintain riêng trong ~/.omp/agent/skills/ (KHÔNG bundled).

• huly-docs — DocStore adapter cho project-design workflow. Sync design docs ↔ Huly Documents.
• huly-tasks — TaskStore adapter. Sync tasks/issues ↔ Huly Issues. Hỗ trợ milestone-implement orchestrator.

Cả 2 skills đã adapted: dùng huly_ prefixed tools (KHÔNG MCP refs), giữ structure gốc. Install skills separately trong ~/.omp/agent/skills/.

Transport + Auth

• Transport (config.json):
  • ws (default) — WebSocket persistent, connection pool per-workspace (max 8 ws, LRU evict), auto-reconnect backoff. Tốt cho latency.
  • rest — REST stateless, KHÔNG pool. Tốt cho environments block WS.
• Auth (per workspace):
  • token — Huly API token (preferred).
  • email + password — login credentials (api-client connect hỗ trợ cả 2).

Troubleshooting

| Symptom | Nguyên nhân + Fix | |---|---| | NeedsInitError: No workspace resolved | cwd chưa bind. Run /huly init. | | NeedsDisambiguationError: Workspace ambiguous | Same-name diff-URL. Specify workspace param explicit. | | ConnectionError: Huly unreachable | Check URL, network, self-host Huly running. /huly status diagnostic. | | AuthError: token expired | Refresh token trong /huly workspace add. |

License

• omp-huly: MIT © can1357 (fork from pi-huly by naicoi92).
• Runtime dependency @hcengineering/*: EPL-2.0 (consumer install từ npm public — KHÔNG bundled vào dist). Xem NOTICE.md cho attribution + source availability.
• Other deps (ws, zod, @oh-my-pi/*): MIT.

Links

• GitHub
• Issues
• Upstream: pi-huly
• oh-my-pi
• Huly self-host guide