{"id":50388337,"url":"https://github.com/rckbrcls/polter","last_synced_at":"2026-05-30T16:30:42.433Z","repository":{"id":342333024,"uuid":"1173710391","full_name":"rckbrcls/polter","owner":"rckbrcls","description":"Desktop workspace for controlling commands, pipelines, processes, MCP setup, and developer automation from one Polter interface.","archived":false,"fork":false,"pushed_at":"2026-05-15T21:44:43.000Z","size":5311,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T00:12:09.970Z","etag":null,"topics":["automation","desktop-app","developer-tools","electron","electron-vite","mcp","process-management","react","turborepo","typescript"],"latest_commit_sha":null,"homepage":"https://kit.polterware.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rckbrcls.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-05T17:03:25.000Z","updated_at":"2026-05-15T21:44:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rckbrcls/polter","commit_stats":null,"previous_names":["polterware/polterbase","polterware/polter","rckbrcls/polter"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/rckbrcls/polter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fpolter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fpolter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fpolter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fpolter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rckbrcls","download_url":"https://codeload.github.com/rckbrcls/polter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fpolter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33700863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","desktop-app","developer-tools","electron","electron-vite","mcp","process-management","react","turborepo","typescript"],"created_at":"2026-05-30T16:30:41.592Z","updated_at":"2026-05-30T16:30:42.419Z","avatar_url":"https://github.com/rckbrcls.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polter\n\nPolter is a desktop-first developer control plane for shaping project-specific workspaces around machines, repositories, commands, services, and operational panels. The current repository is a `pnpm` + Turborepo monorepo with an Electron desktop app in `apps/desktop`, a Remotion presentation package in `apps/presentation`, and shared non-visual TypeScript services in `packages/core`.\n\nThe product direction is a serious control plane with this hierarchy: `Machine -\u003e Projects -\u003e Project Workspaces -\u003e Panels`. A user selects a machine, chooses one of that machine's projects, and assembles project workspaces from panels for commands, pipelines, processes, repositories, services, infrastructure, databases, agents, logs, runbooks, and release work. The current Electron renderer is intentionally UI-only and mock-first: it demonstrates the desktop experience without running real backend, IPC, process, MCP, script, or declarative apply operations from the renderer.\n\n## Problem\n\nDeveloper operations often spread across machines, repositories, shell history, package scripts, GitHub CLI, Vercel CLI, Supabase CLI, local process managers, MCP configuration, logs, runbooks, and one-off project notes. Polter brings those operational primitives into one desktop control plane so a developer can inspect the active machine, choose a project, stage commands, compose project workspaces, arrange panels, and keep automation surfaces explicit.\n\n## Main Features\n\n- Electron desktop app with a main window and a global Commander overlay.\n- Separate Remotion composition for Polter's product presentation video and future interactive preview surfaces.\n- UI-only renderer control plane with mock data for machine-scoped projects, project workspaces, Processes, Pipelines, Scripts, Infrastructure, Tool Status, MCP, Skill Setup, Project Config, Settings, and command feature views.\n- Dockable project workspace model where panels are the product unit for commands, pipelines, terminals, logs, infrastructure, future machines, environments, databases, agents, quality gates, APIs, and runbooks.\n- Typed preload bridge exposed as `window.polter`.\n- Explicit IPC channel catalog in `apps/desktop/src/shared/ipc.ts`.\n- Shared command catalog for Supabase, GitHub CLI, Vercel CLI, Git, and package-manager commands.\n- Shared process manager, pipeline engine, declarative planner, MCP installer, config storage, and desktop service helpers in `packages/core`.\n- Project-level `.polter/config.json` support for tool metadata, child repositories, environment entries, and pipelines.\n- Local global config through the `conf` package for global pipelines and saved desktop repositories.\n- Electron Builder packaging configuration for unsigned macOS, Windows, and Linux artifacts.\n\n## Technology Stack\n\n| Area | Technology |\n| --- | --- |\n| Workspace | `pnpm@10.33.0`, Turborepo |\n| Desktop runtime | Electron, electron-vite, Electron Builder |\n| Renderer | React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui, Radix/Base UI-style primitives |\n| Presentation | Remotion, React, TypeScript, Tailwind CSS |\n| UI utilities | lucide-react, cmdk, motion, sonner, Orama, dnd-kit, react-resizable-panels |\n| Core services | TypeScript, Zod, execa, conf, eventemitter3, p-limit, p-retry, which |\n| MCP support | `@modelcontextprotocol/sdk` plus local MCP installation helpers |\n| Tests | Vitest, Testing Library React, jsdom |\n\n## Architecture\n\nPolter is split into four active layers:\n\n- `apps/desktop`: Electron main process, preload bridge, renderer shell, feature modules, UI components, tests, design contract, and packaging config.\n- `apps/presentation`: Remotion source for the Polter presentation video and exported player-ready composition.\n- `packages/core`: shared non-visual services for commands, runners, processes, pipelines, declarative planning, config, MCP setup, IPC helpers, and desktop adapters.\n- Root workspace: package orchestration, Turborepo tasks, workspace lockfile, docs, and project-level `.polter/config.json`.\n\nThe product hierarchy is `Machine -\u003e Projects -\u003e Project Workspaces -\u003e Panels`. Today the renderer models that direction with UI-only and mock-first workspace state, while `packages/core` holds reusable command, process, pipeline, config, and MCP helpers that future runtime adapters can wire into the control plane.\n\nThe renderer is currently isolated from real runtime services. `apps/desktop/src/main/ipc.ts` registers public channels, but most handlers deliberately throw UI-only mode errors. The active renderer uses `apps/desktop/src/renderer/features/workbench/mock-workbench-adapter.ts` instead of calling real IPC or starting processes.\n\n```mermaid\nflowchart LR\n  User[\"Developer\"] --\u003e Desktop[\"Electron Desktop\"]\n  Desktop --\u003e Machine[\"Active Machine\"]\n  Machine --\u003e Project[\"Selected Project\"]\n  Project --\u003e Workspace[\"Project Workspaces\"]\n  Workspace --\u003e Panels[\"Dockable Panels\"]\n  Desktop --\u003e Main[\"Main Process\"]\n  Main --\u003e Window[\"Window and Commander Overlay\"]\n  Desktop --\u003e Preload[\"Preload Bridge\"]\n  Preload --\u003e Bridge[\"window.polter\"]\n  Bridge --\u003e Channels[\"IPC_CHANNELS\"]\n  Desktop --\u003e Renderer[\"React Renderer\"]\n  Renderer --\u003e Mock[\"Mock Workbench Adapter\"]\n  Main -.-\u003e Channels\n  Core[\"@polterware/core\"] --\u003e Commands[\"Command Catalog\"]\n  Core --\u003e Processes[\"Process Manager\"]\n  Core --\u003e Pipelines[\"Pipeline Engine\"]\n  Core --\u003e Config[\"Config Storage\"]\n  Core --\u003e MCP[\"MCP Setup\"]\n```\n\nSee [docs/architecture.md](docs/architecture.md) for the full technical architecture.\n\n## Folder Structure\n\n```text\n.\n├── apps/\n│   ├── desktop/              # Active Electron desktop app\n│   └── presentation/         # Remotion presentation video package\n├── packages/\n│   └── core/                 # Shared non-visual TypeScript services\n├── docs/                     # Product, architecture, setup, API, storage, and workflow docs\n├── legacy/                   # Retained archived code, not part of the active product\n├── screenshots/              # Placeholder folder for future visual evidence\n├── .github/workflows/        # Contains a stale release workflow\n├── .polter/config.json       # Project-level Polter config for this checkout\n├── pnpm-workspace.yaml\n├── turbo.json\n└── package.json\n```\n\n## Prerequisites\n\n- Node.js compatible with the Electron and TypeScript toolchain in this workspace.\n- pnpm. The root manifest declares `pnpm@10.33.0`.\n- Git for normal repository work.\n- Optional CLIs for core command catalog workflows: Supabase CLI, GitHub CLI (`gh`), Vercel CLI, and a supported package manager (`npm`, `pnpm`, `yarn`, or `bun`).\n\n## Installation\n\nInstall dependencies from the repository root:\n\n```bash\npnpm install\n```\n\nThe workspace packages are declared in `pnpm-workspace.yaml`:\n\n```yaml\npackages:\n  - \"apps/*\"\n  - \"packages/*\"\n```\n\n## Environment Configuration\n\nCopy `.env.example` when local overrides are needed:\n\n```bash\ncp .env.example .env\n```\n\nCurrent documented variables:\n\n| Variable | Purpose |\n| --- | --- |\n| `ELECTRON_RENDERER_URL` | Development renderer URL consumed by Electron when a Vite renderer server is active. |\n| `POLTER_LOG_FORMAT` | Core diagnostic log format. Supported values are inferred from code as `text` or `json`. |\n| `POLTER_LOG_LEVEL` | Core diagnostic log level. |\n| `POLTER_DEBUG` | Enables debug mode when set to `1` or `true`. |\n| `EDITOR` | Preferred editor for config/edit flows. |\n| `VISUAL` | Preferred visual editor. Takes precedence over `EDITOR`. |\n\nNo required production secrets were identified in the current active workspace.\n\n## Running Locally\n\nThe root development script delegates to Turborepo and filters the desktop package:\n\n```bash\npnpm dev\n```\n\nThe desktop package script runs:\n\n```bash\nelectron-vite dev\n```\n\nAgent sessions in this repository must not execute development, preview, build, or distribution commands. When runtime verification is needed, Erick should run the relevant command locally.\n\n## Available Scripts\n\nRoot scripts:\n\n| Script | What it does |\n| --- | --- |\n| `pnpm dev` | Runs `turbo run dev --filter=@polterware/desktop`. |\n| `pnpm build` | Runs `turbo run build`. |\n| `pnpm preview` | Runs `turbo run preview --filter=@polterware/desktop`. |\n| `pnpm dist` | Runs desktop distribution through Turbo. |\n| `pnpm dist:mac` | Builds a macOS desktop package target. |\n| `pnpm dist:win` | Builds a Windows desktop package target. |\n| `pnpm dist:linux` | Builds a Linux desktop package target. |\n| `pnpm dist:all` | Builds all configured desktop package targets. |\n| `pnpm design:lint` | Runs the desktop `DESIGN.md` lint task. |\n| `pnpm deps:electron` | Prints the Electron dependency version from the desktop package. |\n| `pnpm typecheck` | Runs package type-checking through Turbo. |\n| `pnpm test` | Runs package tests through Turbo. |\n\nDesktop package scripts are defined in `apps/desktop/package.json`. Core package scripts are defined in `packages/core/package.json`.\nPresentation package scripts are defined in `apps/presentation/package.json`.\n\n## Tests\n\nRun all active workspace tests:\n\n```bash\npnpm test\n```\n\nRun type-checking:\n\n```bash\npnpm typecheck\n```\n\nThe current test suite includes:\n\n- Electron main-process tests for IPC registration and global shortcuts.\n- Preload bridge tests for channel routing and Commander focus events.\n- Renderer tests for root surface selection, navigation catalogs, mock workbench behavior, scripts, pipelines, processes, and Commander search.\n- Core tests for command metadata, config storage, execution helpers, process manager behavior, IPC protocol, package manager detection, YAML writer, pins, suggested args, and error modeling.\n\n## Build\n\nBuild the workspace:\n\n```bash\npnpm build\n```\n\nThe desktop build uses `electron-vite` and writes:\n\n- Main process output to `apps/desktop/out/main`.\n- Preload output to `apps/desktop/out/preload`.\n- Renderer output to `apps/desktop/out/renderer`.\n\n## Packaging And Deployment\n\nPolter is packaged as an Electron desktop app through Electron Builder:\n\n```bash\npnpm dist\npnpm dist:mac\npnpm dist:win\npnpm dist:linux\npnpm dist:all\n```\n\nCurrent package targets from `apps/desktop/electron-builder.yml`:\n\n- macOS `dmg`\n- Windows `nsis` for `x64`\n- Linux `AppImage`\n\nSigning, notarization, publishing, auto-update, rollback, and production release channels were not identified in the current active codebase.\n\nThe existing `.github/workflows/release.yml` appears stale for the current monorepo because it uses Bun and root-level `src/index.tsx` / `src/mcp.ts` paths that do not exist in the active workspace layout.\n\n## Usage Examples\n\nOpen the desktop app in development:\n\n```bash\npnpm dev\n```\n\nRun static checks:\n\n```bash\npnpm typecheck\npnpm test\npnpm design:lint\n```\n\nInspect the configured Electron dependency version:\n\n```bash\npnpm deps:electron\n```\n\nExample `.polter/config.json` shape from this repository:\n\n```json\n{\n  \"version\": 1,\n  \"tools\": {\n    \"supabase\": {}\n  },\n  \"pipelines\": []\n}\n```\n\n## Current Project Status\n\n- Active product surface: Electron desktop app in `apps/desktop`.\n- Active shared logic: TypeScript core package in `packages/core`.\n- Product hierarchy: `Machine -\u003e Projects -\u003e Project Workspaces -\u003e Panels`.\n- Renderer runtime state: UI-only and mock-first.\n- Packaging: local unsigned Electron Builder configuration exists.\n- Deployment/release automation: not production-ready in the current active workspace.\n- Database: no database, ORM, migrations, or seeds are active.\n- HTTP API: not present.\n\n## Roadmap And Next Steps\n\nUseful next steps based on the current codebase:\n\n- Translate more of the panel catalog into real panel ids only when a panel has useful mock behavior or real adapters.\n- Replace UI-only IPC handlers with carefully scoped real handlers when runtime integration is approved.\n- Decide whether `.github/workflows/release.yml` should be removed or rewritten for Electron packaging.\n- Add durable local storage if project workspaces, panel layouts, command registry, audit history, machine registry, or process history move beyond config files and memory.\n- Add signing, notarization, release channel, and rollback policy before public distribution.\n- Add screenshots to `screenshots/` and reference them from this README when the UI is ready for portfolio presentation.\n\n## License\n\nNo root license file or root `license` field was identified in the active workspace.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frckbrcls%2Fpolter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frckbrcls%2Fpolter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frckbrcls%2Fpolter/lists"}