Skip to main content

horrible-dashboard documentation

A unified one-stop app for everything — "emacs for the agentic era". One web UI serves two layouts: a browser app and a cross-platform desktop app (a Tauri shell wrapping the same frontend).

These pages are the contract between the code and anyone (human or agent) working on it — they describe the codebase as it is, not as it once was.

The big picture​

Contents​

Getting started

  • Setup & running — prerequisites, install, and how to bring up the browser and desktop layouts; mirrors the package.json scripts.

Architecture

  • Layout shell — the shared frontend layout (workspace, panels, command palette) and how the browser and desktop (Tauri) versions differ.
  • Windowing — the dockable workspace: how views (panels and widgets) open as tabbed/split/floating panes, views vs pane instances, and layout persistence.
  • Plugin SDK — the public frontend plugin contract (@horribledashboard/sdk): package format, authoring guide, runtime shims, versioning, trust model, catalog/install lifecycle.
  • Backend plugin SDK — its server-side counterpart (backend.sdk): plugins contribute HTTP routes, agent tools, /ws channels, lifespan hooks, and dash facades; discovered from bundled dirs, HORRIBLE_PLUGINS_DIR, and pip entry points.
  • Python SDK (dash) — the in-REPL handle for scripting the running app (panes, workspaces, layout, I/O telemetry, settings).
  • Agent tools & permissions — the generalized agent tool surface (agentTools, agent-exposed commands, pull-based getAgentContext()), the capability-manifest protocol, and the Claude Code–style permission system that gates side effects. (Implemented; the editor, file explorer, and terminal modules are layered onto it.)
  • Agent ⇄ editor trajectories — sequence diagrams of how the agent reaches the editor's language intelligence: the thread-based LSP transport (the Windows --reload spawn fix), agent-driven rename/diagnostics, LSP-grounded ghost text, workspace-relative file paths, stale-buffer resolution, and the tool-calling reliability work (temperature, forced retry) with the measured A/B results.
  • Future pane types (ideas) — brainstorm, not committed. Parked ideas for new view/pane/window kinds (companion, ambient, ephemeral, PiP, portal…) and where each would hook into the windowing seams.
  • Distributed peer fabric — how nodes connect to other users' nodes over TCP/IP: Ed25519 node identity, the signed PeerEnvelope wire protocol + handshake, the hybrid transport abstraction (direct, relay, LAN), trust modes, and the process-global PeerHub vs the per-browser /ws.
  • Network protocol & scenarios — mermaid sequence diagrams of the websocket protocols across situations (one user/two tabs, two users direct, via a relay intermediary, collaborative panes, agent-to-agent, peer chat) and the proposed lobby (P2P + intermediary + discovery) design.
  • Agent commons (design) — proposed, not implemented. A public square for nodes that don't already know each other to discover, meet, and collaborate safely: signed profiles, vector matchmaking, a two-sided consent + progressive-trust ladder, and reputation — built on the lobby, Ed25519 identity, and read-only agent-to-agent gating. Includes a BitTorrent-style hybrid discovery plan (DHT/gossip + bootstrap/relay) that demotes any single server from a SPOF to one node among many, an interop analysis (A2A/MCP/AP2/A2UI — adopt A2A Agent Cards + tasks over the peer wire; the fabric is the layer no standard covers), and a phased v1 implementation plan.

Modules — one page per feature module, each describing how it plugs into the layout shell and how it behaves in the browser vs the desktop app:

Sync policy (enforced)​

Docs live next to the code on purpose, and changes that affect them must update them in the same change:

  • New module → new docs/modules/<name>.mdx page following the existing template (purpose, panels/commands contributed, backend surface, browser vs desktop behavior).
  • New panel, command, capability, or backend route on an existing module → update that module's page.
  • Changes to the workspace/docking system, command palette, keybindings, platform capability service, or either app entry → update docs/architecture/layout-shell.mdx.
  • Renaming or removing any of the above → same rule, including deleting docs for removed features.
  • Adding, renaming, or changing a script in the repo-root package.json (or the backend run/test commands) → update docs/setup.mdx.

A Stop hook (.claude/hooks/docs_check.py) flags any change set that touches apps/, packages/, backend/, or package.json without touching docs/, as a safety net. Pure refactors with no behavioral or interface change don't need doc edits — say so when the hook asks.

This documentation site​

These pages render as a Docusaurus site whose source of truth is this docs/ directory — the site config lives in website/ and reads ../docs directly, so editing a page here is editing the site. Diagrams use Mermaid fenced code blocks.

  • pnpm --filter @horrible/docs start — local dev server with live reload.
  • pnpm --filter @horrible/docs build — production build (run before pushing to catch broken links and MDX errors).
  • Pushing to main deploys to GitHub Pages via .github/workflows/docs.yml.

Status​

The monorepo (apps/web, apps/desktop, packages/core, packages/ui, backend/) is scaffolded and verified. Implemented modules: dashboard, agent, observability, clubhouse, marketplace, settings, editor (note/file buffers + recent-notes widget), file explorer, terminal (PTY), database (psql-like inspector + SQLite vector store), visualizer (HTML5 Canvas, Three.js, Babylon.js scripts, and headless Pygame subprocess frame streaming), and network (the distributed peer fabric — node identity, hybrid direct/relay/LAN transports, agent-to-agent, and collaborative shared panes). The agent tool & permission surface (agent-tools.mdx) is in place and the editor, files, and terminal modules are layered onto it (read tools + gated side-effecting tools behind the Claude Code–style permission engine). The flow canvas (flow-canvas.mdx) ships its Phase-0/1 spine: an n8n-style canvas whose Agent nodes reuse the shared orchestrator loop, runnable end to end (Phase 2+ — Tool/Router nodes, run history — is design).

What still needs doing:

  • Editor: desktop-only osfile: source (arbitrary OS files via Tauri native dialogs) — designed in editor.mdx, not yet implemented.
  • File explorer: live files.* WS watch events (clients currently re-list to refresh) — see file-explorer.mdx.
  • Full chat cockpit: the agent's conversational workspace view beyond the home ask bar — still design.
  • An experimental Electron shell lives on the electron-shell branch (docs/architecture/electron-shell.md there).

Each module page carries its own phase markers (e.g. editor C1–C5, files B3/B4, terminal D2/D3) — those are the source of truth for per-module progress.