:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
[!IMPORTANT] Interested in the PostHog desktop app? Join the waitlist or hop into our Discord.
Found a bug or want to share feedback? Open the account menu in PostHog Desktop and select Send feedback…, or open an issue on GitHub.
PostHog Desktop
This is the source for the PostHog desktop and web hosts and the agent framework that powers them.
[!NOTE] This directory lives at
products/desktopinside posthog/posthog. If you already have that repo checked out, there is no separate clone:cd products/desktopand follow the setup below. It is a standalone pnpm workspace with its own lockfile and Node version.
Development
Prerequisites
- Node.js 22+
- pnpm 10.23.0
Setup
# Install pnpm if you haven't already
npm install -g pnpm
# Install dependencies for all packages
pnpm install
# Optional: copy environment config
# Only needed for code signing (APPLE_*) or PostHog analytics (VITE_POSTHOG_*).
# The app runs fine in dev without it.
cp .env.example .env
Running in development
By default, pnpm dev uses phrocs (our custom process runner) to run the agent and code app in parallel. phrocs auto-installs and keeps itself up to date: on every pnpm install the local binary is checked against the latest phrocs-latest release checksums and re-downloaded if it differs (skipped when offline or in CI). pnpm dev only downloads it if it is missing entirely. It reads the mprocs.yaml config file. The binary lives at bin/phrocs and is git-ignored.
# Run both agent (watch mode) and code app in parallel
pnpm dev
# Or run them separately:
pnpm dev:agent # Run agent in watch mode
pnpm dev:code # Run code app
# Use mprocs instead of phrocs
pnpm dev:mprocs
Want to connect to a local PostHog instance? See docs/LOCAL-DEVELOPMENT.md for OAuth setup and connecting to localhost:8010.
Utility scripts
Scripts in scripts/ for development and debugging:
| Script | Description |
|---|---|
scripts/clean-posthog-code-macos.sh |
Remove all PostHog app data from macOS (caches, preferences, logs, saved state). Use --app flag to also delete PostHog.app from /Applications. |
scripts/test-access-token.js |
Validate a PostHog OAuth access token by testing API endpoints. Usage: node scripts/test-access-token.js <token> <project_id> [region] |
Project structure
products/desktop/
├── apps/
│ ├── code/ # Electron desktop app (React, Vite)
│ └── web/ # Web host (cloud-only)
├── packages/
│ ├── agent/ # TypeScript agent framework
│ ├── core/ # Shared business logic
│ ├── ui/ # Shared React UI
│ ├── workspace-server/ # Local filesystem, git, and process services
│ └── platform/ # Host capability interfaces
└── docs/ # Development and operational guides
Documentation
| File | Description |
|---|---|
| Documentation index | Development, architecture, testing, operations, and feature guides |
| Desktop app guide | Building, signing, distribution, and workspace configuration |
| Proposed mobile replacement | Independent native app proposed for products/mobile |
| Architecture and code rules | Source of truth for architecture, code style, and testing rules |
| Contributing | How to contribute to PostHog Desktop |
Contributing
We love contributions big and small. See CONTRIBUTING.md to get started.