monkey-deck

command module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 16 Imported by: 0

README

Monkey Deck

A desktop client for ACP (Agent Client Protocol) coding agents — turning OpenCode / Oh My Pi (omp) from terminal TUIs into a project-based, resumable, parallel, visual workbench.

中文版: README.zh-CN.md

Why this project

AI coding agents (OpenCode, Oh My Pi, and other ACP-implementing agents) are becoming daily drivers for development, but using them raw has real pain points:

  • Sessions are ephemeral: conversations in a TUI are gone when the terminal closes. Context, reasoning, and tool-call history never accumulate per project.
  • Many projects, much chaos: with multiple projects running in parallel, every session shares one working tree and pollutes each other's checkout; comparing two approaches means manually switching back and forth.
  • The process is a black box: what tools the agent ran, which files it changed, how many tokens it spent — all a scrolling wall of text with no structured visibility or audit trail.
  • Permissions are all-or-nothing: letting an agent freely run bash / write files is unsettling; confirming every single action is exhausting.
  • Fragmented tooling: each agent has its own interaction model and its own context; switching costs add up.

What Monkey Deck does: manages agent chat sessions per project / directory, so multiple ACP agents work in parallel in one desktop workbench — isolated, resumable, always visible:

  • Sessions pinned to projects: each session is anchored to a real project directory and survives closing the app (ACP session/resume). All data lives in local SQLite — your history is readable without a network.
  • Parallel without interference: each session gets its own git worktree (dedicated branch), so parallel experiments never pollute each other; results can be compared and merged back with one click.
  • A human in the loop: agent permission requests (run bash / write files) surface as dialogs for you to decide, with tiered rules and "remember this" — neither unrestricted nor nagging.
  • Visible process, measurable spend: reasoning, tool calls, model trace, and token / cost usage stream into the UI as they happen.
  • Pluggable agents: Oh My Pi and OpenCode are built in; any ACP-implementing agent can be added with a stdio command — gated by an ACP conformance self-check before it's allowed in.

Features

  • Pure ACP (Agent Client Protocol): the only channel between the app and an agent is ACP — no CLI stdout parsing, no HTTP+SSE. Protocol conformance is the core bet: any ACP-implementing harness is an interchangeable instance.
  • Project = directory: every session is anchored to a real project directory; parallel sessions each occupy an isolated git worktree — no interference, comparable, mergeable.
  • Local-first: SQLite is the single source of truth. No central server, no cloud dependency.
  • Pluggable harnesses: Oh My Pi (omp) and OpenCode built in; the "Add harness" dialog accepts any ACP agent via a stdio ACP command, gated by an ACP conformance self-check (ProbeHarness: controlled spawn → Initialize → NewSession → Prompt to end_turn, producing a report). Tier-1 gates must all pass before the harness is added.
  • Permission dialogs: agent RequestPermission callbacks surface to you for a decision — tiered rules, timeout fallback, configurable auto-allow.
  • Desktop-grade experience: multi-tab main window, pop-out session windows, integrated terminal, message queue with scheduled send, mermaid rendering, fuzzy search, Chinese/English UI.
  • Stays up: crash detection + auto-reconnect with exponential backoff, harness auto-upgrade checks, process-group reclamation against leaks.

Compatible ACP agents

Monkey Deck speaks pure ACP, so every agent that implements the Agent Client Protocol can be plugged in. The built-ins work out of the box; every other agent below can be added in seconds from the Add harness dialog — paste its stdio ACP command, pass the ACP conformance self-check, done.

Built-in

  • Oh My Pi (omp) — default harness
  • OpenCode

Native ACP agents (implement ACP directly, add via stdio command)

Via third-party adapters — these agents have no native ACP mode; a separate adapter binary speaks ACP on their behalf. Install the adapter and it is picked up automatically: once the adapter binary is on PATH, the agent is discovered and the pinned adapter command is spawned (Codex CLI → codex-acp; verified spawn + initialize). While the adapter is missing, a discovered entry still shows up in the agent picker — greyed out as "needs an ACP adapter" and not selectable.

  • Codex CLI — via Zed's codex-acp (the codex binary itself is not ACP-speaking)
  • Claude Agent — via Zed's claude-agent-acp (requires installing the adapter; claude acp is not a working entry)
  • Pi — via pi-acp (requires installing the adapter)
  • Bub — via bub-acp-server (requires installing the adapter)

Curated from the ACP protocol site — the Agents and Registry pages.

Installation

macOS / Linux (one line):

curl -fsSL https://raw.githubusercontent.com/JessonChan/monkey-deck/main/scripts/install.sh | sh
  • Installs to /Applications/Monkey Deck.app on macOS (ad-hoc signed — no Developer ID, notarization, or App Store needed; checksums are verified against the release's SHA256SUMS and the install fails closed on mismatch).
  • Installs the distro package (deb on dpkg systems, rpm on dnf/zypper/yum) on Linux; root is required for the package step.
  • Re-running the same command upgrades in place when a newer release exists and is a no-op when you're already up to date.
  • Windows is not supported yet.

Manual download: GitHub Releases (DMG for macOS drag-install, .deb / .rpm for Linux).

The in-app updater (macOS) then handles upgrades on its own — the installer installs the exact same per-arch zip assets the updater consumes.

Tech stack

Wails3 · Go · React 19 + TypeScript · SQLite (modernc.org/sqlite) · bun

Search keywords

ACP / Agent Client Protocol client / OpenCode client / OpenCode GUI / Oh My Pi / omp / coding agent client / AI coding agent desktop app / agent harness manager / project-based sessions / git worktree parallel / local-first / Wails3 desktop app

Development

task dev      # hot-reload development (Go + frontend together)
task build    # build the desktop app
task release:darwin  # macOS packaging (DMG + per-arch updater zips + SHA256SUMS)
go test ./... # backend unit tests

Engineering constraints, architecture direction, and roadmap live in AGENTS.md.

Reference library

The UI / architecture references a set of open-source projects; their local read-only copies (~5 GB, not committed) live in a machine-level shared directory (default /tmp/monkey-deck-reference, see AGENTS.md §0.2). After cloning, pull them with one command:

bash scripts/references.sh            # shallow-clone missing entries
bash scripts/references.sh --status   # preview (no changes)
bash scripts/references.sh --list     # full list (URL / license / purpose)

Acknowledgments

Thanks to the following open-source projects (design references, not code copies; borrowed code is attributed per each project's license in THIRD_PARTY_LICENSES.md):

License

MIT

Documentation

Overview

desktop.go:桌面 GUI 装配(应用更新 + 菜单 + 主窗口 + 窗口状态记忆 + popout 重建)。 仅 desktop 构建(不带 -tags server)编译;server 模式见 server.go 的 no-op 版本。 拆分目的:让 main.go 在 -tags server 下也能编译,启用 Wails3 server 模式做无 GUI 浏览器驱动集成测试(AGENTS.md §5.5)。GUI 专属符号(application.DefaultApplicationMenu / app.Window.NewWithOptions 等)只在非 server tag 下存在,故必须整块隔离。

remote_attach_desktop.go: desktop builds wire the embedded remote server (AGENTS.md §1.8). Server-tag builds get the no-op twin (remote_attach_server.go) — server mode already serves HTTP itself and must not double-serve.

Directories

Path Synopsis
internal
acp
Package acp 封装 coder/acp-go-sdk,实现桌面客户端侧的 ACP 客户端。
Package acp 封装 coder/acp-go-sdk,实现桌面客户端侧的 ACP 客户端。
config
Package config 处理应用配置与数据目录解析(AGENTS.md §0.5/§1.5)。
Package config 处理应用配置与数据目录解析(AGENTS.md §0.5/§1.5)。
fsview
Package fsview 提供受限工作目录内的文件浏览 / 管理。
Package fsview 提供受限工作目录内的文件浏览 / 管理。
harness
discover.go:运行时发现本机已安装的 harness + 解析本地版本 + 查上游最新版本。
discover.go:运行时发现本机已安装的 harness + 解析本地版本 + 查上游最新版本。
mcp
Package mcp 把 monkey-deck 的 MCP server 配置(store.McpServer)转成 ACP 线上的 acp.McpServer,并提供从 harness 配置文件(opencode opencode.json / OMP .mcp.json) 一次性导入的解析器。
Package mcp 把 monkey-deck 的 MCP server 配置(store.McpServer)转成 ACP 线上的 acp.McpServer,并提供从 harness 配置文件(opencode opencode.json / OMP .mcp.json) 一次性导入的解析器。
permissions
Package permissions 实现分级访问控制(AGENTS.md §3.4:有人在场,可交互)。
Package permissions 实现分级访问控制(AGENTS.md §3.4:有人在场,可交互)。
remote
Package remote embeds an optional, token-authenticated HTTP server into the desktop process so that browsers / mobile clients can connect to the very same app instance while the GUI keeps running (AGENTS.md §1.8).
Package remote embeds an optional, token-authenticated HTTP server into the desktop process so that browsers / mobile clients can connect to the very same app instance while the GUI keeps running (AGENTS.md §1.8).
shellenv
Package shellenv resolves the user's login-shell PATH into the running process, fixing the classic macOS/Linux problem where a GUI app launched from Finder/Dock/Spotlight inherits only launchd's minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin) and cannot find user-installed tools (Homebrew, bun, npm-global, nvm/volta-managed node, …).
Package shellenv resolves the user's login-shell PATH into the running process, fixing the classic macOS/Linux problem where a GUI app launched from Finder/Dock/Spotlight inherits only launchd's minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin) and cannot find user-installed tools (Homebrew, bun, npm-global, nvm/volta-managed node, …).
store
Package store 是 SQLite 的唯一入口(AGENTS.md §2.1)。
Package store 是 SQLite 的唯一入口(AGENTS.md §2.1)。
terminal
Package terminal 提供集成终端:每 session 可开多个交互式 shell(PTY), 供用户自由执行基础 shell 命令。
Package terminal 提供集成终端:每 session 可开多个交互式 shell(PTY), 供用户自由执行基础 shell 命令。
titlegen
Package titlegen 为会话生成「即时兜底标题」(无 LLM)。
Package titlegen 为会话生成「即时兜底标题」(无 LLM)。
ui
Package ui 持久化 UI 运行时状态(AGENTS.md §0.5「少量 JSON」)。
Package ui 持久化 UI 运行时状态(AGENTS.md §0.5「少量 JSON」)。
update
Package update 把 Wails3 内置的应用自更新(app.Updater)接到 GitHub Releases。
Package update 把 Wails3 内置的应用自更新(app.Updater)接到 GitHub Releases。
worktree
Package worktree 管理 git worktree:为每个 session 创建独立工作树 + 分支, 实现并行隔离(参考 orca 的 parallel worktree 模型)。
Package worktree 管理 git worktree:为每个 session 创建独立工作树 + 分支, 实现并行隔离(参考 orca 的 parallel worktree 模型)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL