: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.
PostHog
The agentic workspace for product builders
The Goal
Free product engineers from distractions so they can focus on what they love: building great features. By using agents to transform all data collected across PostHog's products into actionable "tasks," then exposing them with that context through a single interface, we can automate all the chores and save developers hours every day, giving them more time to ship.
Development
Prerequisites
- Node.js 22+
- pnpm 10+
Setup
# Install pnpm if you haven't already
npm install -g pnpm
# Install dependencies
pnpm install
# Run in development mode
pnpm run start
# Build for production
pnpm run make
# Other useful commands
pnpm run check:write # Linting & typecheck
Keyboard Shortcuts
↑/↓- Navigate tasksEnter- Open selected task⌘R- Refresh task list⌘⇧[/]- Switch between tabs⌘W- Close current tab
Building Distributables
To create production distributables (DMG, ZIP):
# Package the app
pnpm package
# Create distributables (DMG + ZIP)
pnpm make
Output will be in:
out/mac-arm64/PostHog.app- Packaged appout/PostHog-Desktop-*.dmg- macOS installerout/make/zip/- ZIP archives
Note: Native modules for the DMG maker are automatically compiled via the prePackage hook. If you need to manually rebuild them, run:
pnpm build-native
Auto Updates & Releases
PostHog auto-updates on macOS and Windows. Current builds use electron-updater, which reads the latest-mac.yml and latest.yml manifests published with each non-draft GitHub release and downloads the matching archive. Builds made by the old Electron Forge toolchain (v0.55.x and earlier) take a single bridge update through the public update.electronjs.org service, which serves the same GitHub releases to their built-in Squirrel client, and become electron-updater clients from the next launch. See docs/UPDATES.md and docs/AUTO-UPDATE-TESTING.md.
There are two ways a release can fire:
- Scheduled (default): automatic at 17:00 and 01:00 UTC.
- Manual: for a hotfix, ask a
team-posthog-desktopmember to runDesktop Tag Releaseonmasterfrom the Actions tab.
Local prep (only needed for one-off manual builds):
- Export a GitHub token with
reposcope asGH_PUBLISH_TOKEN; set bothGH_TOKENandGITHUB_TOKENto its value locally (e.g., in.envrc). In GitHub, store the token as theGH_PUBLISH_TOKENrepository secret. - Run
pnpm run maketo sanity check artifacts.
Set ELECTRON_DISABLE_AUTO_UPDATE=1 if you ever need to ship a build with auto updates disabled.
macOS Code Signing & Notarization
macOS packages are signed and notarized automatically when these environment variables are present:
export APPLE_CODESIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
export APPLE_ID="[email protected]"
export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export APPLE_TEAM_ID="TEAMID"
For CI releases, configure matching GitHub Actions secrets:
APPLE_IDAPPLE_APP_SPECIFIC_PASSWORDAPPLE_TEAM_IDAPPLE_CODESIGN_CERT_BASE64– Base64-encoded.p12export of the Developer ID Application certificate (include the private key)APPLE_CODESIGN_CERT_PASSWORD– Password used when exporting the.p12
CI derives the signing identity from the certificate, so it needs no APPLE_CODESIGN_IDENTITY secret. Set that variable only for local signing.
The Publish Release workflow imports the certificate into a temporary keychain, signs each artifact with hardened runtime enabled (using Electron's default entitlements), and notarizes it before upload whenever these secrets are available.
For local testing, copy codesign.env.example to .env.codesign, fill in the real values, and load it before running pnpm run make:
set -a
source .env.codesign
set +a
pnpm run make
Set SKIP_NOTARIZE=1 if you need to generate signed artifacts without submitting to Apple (e.g., while debugging credentials):
SKIP_NOTARIZE=1 pnpm run make
Windows code signing
Windows builds are signed through Azure Artifact Signing when these environment variables are present:
export AZURE_TENANT_ID="xxx"
export AZURE_CLIENT_ID="xxx"
export AZURE_CLIENT_SECRET="xxx"
They authenticate an Entra app registration that holds the Artifact Signing Certificate Profile Signer role on the posthog-desktop account (West US 2, certificate profile posthog-desktop-public). CI reads them from the DESKTOP_AZURE_CODESIGN_* repository secrets. Without them the build packages unsigned, which is what pull request builds, fork PRs and local builds get. A manual run of the desktop-build-test workflow signs and verifies the result, which is how to check the pipeline before a release.
electron-builder installs the TrustedSigning PowerShell module on the build machine and signs every executable through it, so signing only runs on Windows. Nothing is downloaded: Microsoft issues a short-lived certificate inside the service and returns only the signature.
The certificate subject is set as publisherName in electron-builder.ts and baked into app-update.yml. electron-updater rejects an update whose signature does not match it, so keep it identical to the certificate profile's subject in Azure.
Workspace Configuration (posthog-code.json)
PostHog supports per-repository configuration through a posthog-code.json file. This lets you define scripts that run automatically when workspaces are created or destroyed.
File Locations
PostHog searches for configuration in this order (first match wins):
.posthog-code/{workspace-name}/posthog-code.json- Workspace-specific configposthog-code.json- Repository root config
Schema
{
"scripts": {
"init": "npm install",
"start": ["npm run server", "npm run client"],
"destroy": "docker-compose down"
}
}
| Script | When it runs | Behavior |
|---|---|---|
init |
Workspace creation | Runs first, fails fast (stops on error) |
start |
After init completes | Continues even if scripts fail |
destroy |
Workspace deletion | Runs silently before cleanup |
Each script can be a single command string or an array of commands. Commands run sequentially in dedicated terminal sessions.
Examples
Install dependencies on workspace creation:
{
"scripts": {
"init": "pnpm install"
}
}
Start development servers:
{
"scripts": {
"init": ["pnpm install", "pnpm run build"],
"start": ["pnpm run dev", "pnpm run storybook"]
}
}
Clean up Docker containers:
{
"scripts": {
"destroy": "docker-compose down -v"
}
}
Workspace Environment Variables
PostHog automatically sets environment variables in all workspace terminals and scripts. These are available in init, start, and destroy scripts, as well as any terminal sessions opened within a workspace.
| Variable | Description | Example |
|---|---|---|
POSTHOG_CODE_WORKSPACE_NAME |
Worktree name, or folder name in root mode | my-feature-branch |
POSTHOG_CODE_WORKSPACE_PATH |
Absolute path to the workspace | /Users/dev/.posthog-desktop/worktrees/repo/my-feature |
POSTHOG_CODE_ROOT_PATH |
Absolute path to the repository root | /Users/dev/repos/my-project |
POSTHOG_CODE_DEFAULT_BRANCH |
Default branch detected from git | main |
POSTHOG_CODE_WORKSPACE_BRANCH |
Initial branch when workspace was created | posthog/my-feature |
POSTHOG_CODE_WORKSPACE_PORTS |
Comma-separated list of allocated ports | 50000,50001,...,50019 |
POSTHOG_CODE_WORKSPACE_PORTS_RANGE |
Number of ports allocated | 20 |
POSTHOG_CODE_WORKSPACE_PORTS_START |
First port in the range | 50000 |
POSTHOG_CODE_WORKSPACE_PORTS_END |
Last port in the range | 50019 |
Note: POSTHOG_CODE_WORKSPACE_BRANCH reflects the branch at workspace creation time. If you or the agent checks out a different branch, this variable will still show the original branch name.
Port Allocation
Each workspace is assigned a unique range of 20 ports starting from port 50000. The allocation is deterministic based on the task ID, so the same workspace always receives the same ports across restarts.
Usage Examples
Use ports in your start scripts:
{
"scripts": {
"start": "npm run dev -- --port $POSTHOG_CODE_WORKSPACE_PORTS_START"
}
}
Reference the workspace path:
echo "Working in: $POSTHOG_CODE_WORKSPACE_NAME"
echo "Root repo: $POSTHOG_CODE_ROOT_PATH"
Troubleshooting
"Plan & usage" tab is missing
The app couldn't reach PostHog, usually because of a restrictive network, firewall, or tracker blocker. Connect to a VPN (or fix the network) and restart the app.