|
1 | | -> [!IMPORTANT] |
2 | | -> Interested in PostHog Code? [Join the waitlist](https://posthog.com/code) or hop into our [Discord](https://discord.gg/aSrHKVNVdR). |
3 | | -
|
4 | | -**[Download the latest version](https://github.com/PostHog/code/releases/latest)** |
5 | | - |
6 | | -Found a bug or have feedback? [Open an issue](https://github.com/PostHog/code/issues/new) on GitHub. |
7 | | - |
8 | | -# PostHog Code |
9 | | - |
10 | | -This is the monorepo for PostHog Code apps and the agent framework that powers them. |
11 | | - |
12 | | -## Development |
13 | | - |
14 | | -### Prerequisites |
15 | | - |
16 | | -- Node.js 22+ |
17 | | -- pnpm 10.23.0 |
18 | | - |
19 | | -### Setup |
20 | | - |
21 | | -```bash |
22 | | -# Install pnpm if you haven't already |
23 | | -npm install -g pnpm |
24 | | - |
25 | | -# Install dependencies for all packages |
26 | | -pnpm install |
27 | | - |
28 | | -# Optional: copy environment config |
29 | | -# Only needed for code signing (APPLE_*) or PostHog analytics (VITE_POSTHOG_*). |
30 | | -# The app runs fine in dev without it. |
31 | | -cp .env.example .env |
32 | | - |
33 | | -``` |
34 | | - |
35 | | -### Running in Development |
36 | | - |
37 | | -By default, `pnpm dev` uses phrocs (our custom process runner) to run the agent and code app in parallel. phrocs auto-installs on first run and reads the `mprocs.yaml` config file. The binary is downloaded to `bin/phrocs` and is git-ignored. |
38 | | - |
39 | | -```bash |
40 | | -# Run both agent (watch mode) and code app in parallel |
41 | | -pnpm dev |
42 | | - |
43 | | -# Or run them separately: |
44 | | -pnpm dev:agent # Run agent in watch mode |
45 | | -pnpm dev:code # Run code app |
46 | | - |
47 | | -# Manually update phrocs to the latest version |
48 | | -pnpm update:phrocs |
49 | | - |
50 | | -# Use mprocs instead of phrocs |
51 | | -pnpm dev:mprocs |
52 | | -``` |
53 | | - |
54 | | -> **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. |
55 | | -
|
56 | | -### Utility Scripts |
57 | | - |
58 | | -Scripts in `scripts/` for development and debugging: |
59 | | - |
60 | | -| Script | Description | |
61 | | -|--------|-------------| |
62 | | -| `scripts/clean-posthog-code-macos.sh` | Remove all PostHog Code app data from macOS (caches, preferences, logs, saved state). Use `--app` flag to also delete PostHog Code.app from /Applications. | |
63 | | -| `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]` | |
64 | | - |
65 | | -## Project Structure |
66 | | - |
67 | | -``` |
68 | | -posthog-code/ |
69 | | -├── apps/ |
70 | | -│ ├── code/ # Electron desktop app (React, Vite) |
71 | | -│ ├── mobile/ # React Native mobile app (Expo) |
72 | | -│ └── cli/ # CLI for stacked PRs |
73 | | -├── packages/ |
74 | | -│ ├── agent/ # TypeScript agent framework |
75 | | -│ ├── core/ # Shared business logic |
76 | | -│ ├── electron-trpc/ # tRPC for Electron IPC |
77 | | -│ └── shared/ # Shared utilities (Saga pattern, etc.) |
78 | | -``` |
79 | | - |
80 | | -## Documentation |
81 | | - |
82 | | -| File | Description | |
83 | | -|------|-------------| |
84 | | -| [apps/code/README.md](./apps/code/README.md) | Desktop app: building, signing, distribution, and workspace configuration | |
85 | | -| [apps/mobile/README.md](./apps/mobile/README.md) | Mobile app: Expo setup, EAS builds, and TestFlight deployment | |
86 | | -| [apps/cli/README.md](./apps/cli/README.md) | CLI: stacked PR management with Jujutsu | |
87 | | -| [AGENTS.md](./AGENTS.md) | Architecture rules, code style, patterns, and testing guidelines (read by Claude Code, Codex, Cursor, Aider, etc.) | |
88 | | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute to PostHog Code | |
89 | | -| [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) | Connecting PostHog Code to a local PostHog instance | |
90 | | -| [docs/UPDATES.md](./docs/UPDATES.md) | Release versioning and git tagging | |
91 | | -| [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) | Common issues and fixes | |
92 | | -| [docs/DEEP-LINKS.md](./docs/DEEP-LINKS.md) | `posthog-code://` deep link schemes and parameters | |
93 | | - |
94 | | -## Contributing |
95 | | - |
96 | | -We love contributions big and small. See [CONTRIBUTING.md](./CONTRIBUTING.md) to get started. |
97 | | - |
98 | | -## Troubleshooting |
99 | | - |
100 | | -See [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for common issues (black screen, Electron install failures, native module crashes, etc.). |
| 1 | +signing test |
0 commit comments