Skip to content

: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.

3.9 KB
Raw Blame

[!IMPORTANT] Interested in the PostHog desktop app? Join the waitlist or hop into our Discord.

Download the latest version

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/desktop inside posthog/posthog. If you already have that repo checked out, there is no separate clone: cd products/desktop and 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.