Important
Twig is pre-alpha and not production-ready. Interested? Email jonathan@posthog.com
Found a bug or have feedback? Open an issue on GitHub.
This is the monorepo for PostHog's Twig apps and the agent framework that powers them.
- Node.js 22+
- pnpm 10.23.0
# 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# 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 appWant to connect to a local PostHog instance? See docs/LOCAL-DEVELOPMENT.md for OAuth setup and connecting to localhost:8010.
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] |
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.)
| File | Description |
|---|---|
| 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 |
| CLAUDE.md | Code style, patterns, and testing guidelines |
| docs/LOCAL-DEVELOPMENT.md | Connecting Twig to a local PostHog instance |
| docs/UPDATES.md | Release versioning and git tagging |
| docs/TROUBLESHOOTING.md | Common issues and fixes |
See docs/TROUBLESHOOTING.md for common issues (black screen, Electron install failures, native module crashes, etc.).