Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 1 addition & 100 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,100 +1 @@
> [!IMPORTANT]
> PostHog Code is pre-alpha and not production-ready. Interested? Join our [Discord](https://discord.gg/aSrHKVNVdR)

**[Download the latest version](https://github.com/PostHog/code/releases/latest)**

Found a bug or have feedback? [Open an issue](https://github.com/PostHog/code/issues/new) on GitHub.

# PostHog Code

This is the monorepo for PostHog Code 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

# Optional: copy environment config
# Only needed for code signing (APPLE_*) or PostHog analytics (VITE_POSTHOG_*).
# The app runs fine in dev without it.
cp .env.example .env

```

### Running in Development

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.

```bash
# Run both agent (watch mode) and code app in parallel
pnpm dev

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

# Manually update phrocs to the latest version
pnpm update:phrocs

# Use mprocs instead of phrocs
pnpm dev:mprocs
```

> **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-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. |
| `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

```
posthog-code/
├── apps/
│ ├── code/ # 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/code/README.md](./apps/code/README.md) | Desktop app: building, signing, distribution, and workspace configuration |
| [apps/code/ARCHITECTURE.md](./apps/code/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 |
| [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute to PostHog Code |
| [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) | Connecting PostHog Code 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 |

## Contributing

We love contributions big and small. See [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.

## Troubleshooting

See [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for common issues (black screen, Electron install failures, native module crashes, etc.).
this is okay
Loading