convez.ai
AgenteDesenvolvimento WebAvançado
kirinchen

Porthole - Interface Web para Agents de Coding

kirinchen/porthole

Interface web para conversar com agents coding enquanto edita arquivos

Ver no GitHub
InicialPluginScore · de 0 a 100

Uma GUI web path-scoped que permite comunicação eficiente com agents Claude rodando em seus repositórios através do navegador. Combina explorador de arquivos, editor Markdown com live-preview e mermaid interativo, chat em tempo real com agents, sessões de terminal tmux e CLI nativo — tudo em um painel de três colunas sincronizadas.

Instalação

$npx convez-ai kirinchen/porthole

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 semanas
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Desenvolvimento de software colaborativo com agents Claude
  • Edição e refatoração de código com assistência em tempo real
  • Gerenciamento e visualização de diagramas mermaid interativos
  • Execução de comandos e sessões de terminal persistentes em repositórios

Veredito

Porthole é uma solução sofisticada para fluxo de trabalho local/confiável, combinando editor, terminal e agent IA em um único painel. Requer compreensão clara do modelo de segurança (path guards, sem autenticação) e é adequado apenas para ambientes de confiança — não serve para múltiplos usuários ou internet pública.

README

A tradução para o português deste README ainda está na fila.

porthole · 舷窗

一個 path-scoped 的 web 介面,讓你透過瀏覽器跟住在各 repo 裡的 agent(claude -p)高效溝通。 A path-scoped web GUI to talk to the coding agents living in your repos — through the browser.

仿 Obsidian / VSCode 的三欄佈局:左邊看檔案樹、中間編輯檔、右邊跟 agent 對話或開終端 —— 三者同框,邊改檔邊對話。

overview


它能做什麼

  • Explore — 檔案樹 + Markdown 即時預覽 / 編輯(CodeMirror 6,Obsidian 式 live-preview,內嵌 mermaid 互動圖)。依所在目錄新增檔 / 目錄、上傳檔案。
  • Chat — 跟 active repo 的 agent 對話,claude -p 逐字串流,紀錄寫進 doc/chat/。
  • Session — 列出可恢復的 claude session,點一個接進背景 tmux(detach 後背景續跑)。
  • CLI — 真 PTY 終端,CWD 鎖在 repo root。

右側面板可切 Chat / Session / CLI,且保活不卸載(切走不斷終端);可拖寬、撐滿覆蓋中央、或最小化到右緣。

編輯(CM6 即時預覽 + mermaid 互動 box)終端(CLI / Session)
editorcli

mermaid 圖表 GUI 編輯

編輯 Markdown 時,每個 ```mermaid 區塊都有 GUI tab,可圖形化編輯後正規化寫回(空白行右鍵也能一鍵插入各圖型範例)。節點圖型用 React Flow + dagre 自動排版,共用雙擊改字 / 拖把手連線 / Delete 刪 / 復原重做 / 複製貼上 / 全螢幕;sequence 則是清單式表單。支援 5 種圖型:

FlowchartState diagram
flowchartstate
ERDClass diagram
erdclass
Sequence diagram(清單式)
sequence

各圖型僅支援其常用子集(subgraph / composite state / loop/alt 等退回純文字編輯)。


安全模型(請先讀)

porthole 預設只給單機自用 + 信任網路。請務必理解:

  • 無認證。CLI / Session 是完整 PTY,等同以執行身分的完整 RCE;path guard 只鎖 fs 讀寫與子程序 CWD,不限制終端能跑什麼。
  • path guard(安全命脈):所有 fs 讀寫、claude/tmux 的 CWD 一律 realpath 正規化後驗證仍落在 basePath 內,.. / symlink 逃逸即 403。靠 code 擋,不靠 prompt。
  • WS 同源檢查 擋 CSWSH(跨站網頁連本機 WS 拿 shell);綁 127.0.0.1 也擋不住,故此檢查不可少。
  • 綁定:預設 127.0.0.1。要遠端用,建議綁 tailscale 網卡 IP(只 tailnet 可達)。不要綁 0.0.0.0 —— 那會連同整個 LAN 一起開放。

一句話:這是「給自己用的遠端終端」,不是多人服務。只在你完全信任的網路裡跑。細節見 doc/SPEC.md §2。


快速開始

git clone https://github.com/kirinchen/porthole.git
cd porthole
npm install && npm run install:all   # 根層工具 + server/web 依賴

cp .env.example .env                 # 設定:HOST / PORT / PORTHOLE_BASE
# 編輯 .env:PORTHOLE_BASE 指向你放各 repo 的母目錄

npm run dev                          # 開發(前後端分離 + 熱更新)
# 或
npm run prod                         # 建置前端 + 單 port 4321 serve

瀏覽器開 http://<host>:<port>/<repo> —— URL 第一段 = active repo(如 /myproject)。

常駐部署(systemd user service)見 RUN.md 與 deploy/。


技術

  • 前端:Vite + React 19 + TypeScript(strict)+ Antd 6 + CodeMirror 6 + xterm.js
  • 後端:Fastify(單 port,serve build + REST/SSE + WebSocket + path 映射)
  • 終端:node-pty + tmux;LLM:shell out 到 claude -p(不整合 SDK)

設計原則:安全邊界優先、deterministic-first、LLM as Unix tool、薄。


文件

Ver o original no GitHub

Bom para

Relacionados