https://github.com/posthog/twig
The Agentic Development Environment
https://github.com/posthog/twig
Last synced: 4 months ago
JSON representation
The Agentic Development Environment
- Host: GitHub
- URL: https://github.com/posthog/twig
- Owner: PostHog
- License: other
- Created: 2025-09-25T21:53:50.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-02-11T18:49:16.000Z (5 months ago)
- Last Synced: 2026-02-11T21:04:25.026Z (5 months ago)
- Language: TypeScript
- Homepage:
- Size: 36.1 MB
- Stars: 21
- Watchers: 0
- Forks: 5
- Open Issues: 122
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> [!IMPORTANT]
> Twig is pre-alpha and not production-ready. Interested? Email jonathan@posthog.com
**[Download the latest version](https://github.com/PostHog/twig/releases/latest)**
Found a bug or have feedback? [Open an issue](https://github.com/PostHog/twig/issues/new) 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
```bash
# 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
```bash
# 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
```
> **Want to connect to a local PostHog instance?** See [docs/LOCAL-DEVELOPMENT.md](./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-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 [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 |
|------|-------------|
| [apps/twig/README.md](./apps/twig/README.md) | Desktop app: building, signing, distribution, and workspace configuration |
| [apps/twig/ARCHITECTURE.md](./apps/twig/ARCHITECTURE.md) | Desktop app: dependency injection, tRPC, state management, and events |
| [apps/mobile/README.md](./apps/mobile/README.md) | Mobile app: Expo setup, EAS builds, and TestFlight deployment |
| [apps/cli/README.md](./apps/cli/README.md) | CLI: stacked PR management with Jujutsu |
| [CLAUDE.md](./CLAUDE.md) | Code style, patterns, and testing guidelines |
| [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) | Connecting Twig to a local PostHog instance |
| [docs/UPDATES.md](./docs/UPDATES.md) | Release versioning and git tagging |
| [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) | Common issues and fixes |
## Troubleshooting
See [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for common issues (black screen, Electron install failures, native module crashes, etc.).