Important

Twig is pre-alpha and not production-ready. Interested? Email jonathan@posthog.com

Download the latest version

Found a bug or have feedback? Open an issue on GitHub.

Twig

This is the monorepo for PostHog's Twig apps and the agent framework that powers them.

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

# Copy environment config
cp .env.example .env

Running in Development

# Run both agent (watch mode) and twig app in parallel
pnpm dev

# Or run them separately:
pnpm dev:agent  # Run agent in watch mode
pnpm dev:twig   # Run twig app

Utility Scripts

Scripts in scripts/ for development and debugging:

Script	Description
scripts/clean-twig-macos.sh	Remove all Twig app data from macOS (caches, preferences, logs, saved state). Use --app flag to also delete Twig.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

twig/
├── apps/
│   ├── twig/       # Electron desktop app (React, Vite)
│   ├── mobile/     # React Native mobile app (Expo)
│   └── cli/        # CLI for stacked PRs
├── packages/
│   ├── agent/      # TypeScript agent framework
│   ├── core/       # Shared business logic
│   ├── electron-trpc/  # tRPC for Electron IPC
│   └── shared/     # Shared utilities (Saga pattern, etc.)

Documentation

File	Description
CLAUDE.md	Code style, patterns, and testing guidelines
UPDATES.md	Release versioning and git tagging
apps/twig/README.md	Desktop app: building, signing, distribution, and workspace configuration
apps/twig/ARCHITECTURE.md	Desktop app: dependency injection, tRPC, state management, and events
apps/mobile/README.md	Mobile app: Expo setup, EAS builds, and TestFlight deployment
apps/cli/README.md	CLI: stacked PR management with Jujutsu

Troubleshooting

Electron failed to install correctly

If you see this error when running pnpm dev:

Error: Electron failed to install correctly, please delete node_modules/electron and try installing again

The electron binary didn't download during install. Fix it by running the install script manually:

cd node_modules/electron && node install.js

Or nuke it and reinstall:

rm -rf node_modules/electron && pnpm install && cd node_modules/electron && node install.js

Native module crash (libc++abi / Napi::Error)

If the app crashes with something like:

libc++abi: terminating due to uncaught exception of type Napi::Error

Native modules (like node-pty) need to be rebuilt for your Electron version:

pnpm --filter twig exec electron-rebuild