installing-posthog-from-chat

Installing PostHog from chat

Wizard is PostHog's setup agent. With wizard-install-start it runs in a cloud workspace on a GitHub repository, makes the code changes, and opens a pull request. The user reviews and merges that pull request. Nothing changes on their default branch until they do.

Work through the steps in order. Skip a step when its outcome is already known from the conversation.

1. Connect GitHub

The run uses the project's GitHub connection, so the project needs one.

1. Call integrations-list and look for an integration with kind github.
2. When there is none, give the user this link, built from the base URL and project ID in your context: <base URL>/integrations/connect/github/?project_id=<project id>&connect_from=mcp. They install the PostHog GitHub App and choose which repositories it can access. Wait until they say they are done, then call integrations-list again.

2. Pick the repository

Call integrations-github-repos-retrieve with the GitHub integration's ID. Use search when the user named the repository, and page with offset when has_more is true.

• One clear match: confirm it with the user in one line.
• Several matches: list them and ask which one.
• No match: the GitHub App cannot access it. Ask the user to add the repository to the app's repository access in GitHub, then search again.

Pass the repository as full_name (owner/name).

The setup agent works at the repository root. If the user describes a monorepo where the app lives in a subdirectory, tell them the run may not find it, and offer to try anyway.

3. Start the run

Call wizard-install-start with:

• repository: the owner/name from step 2.
• branch: only when the user wants a branch other than the default one. The pull request targets that branch.
• idempotency_key: a fresh unique value for this request. Reuse the same value if you retry after a network error, so the retry returns the same run.

Errors the user can act on:

Error code	What to do
github_not_connected	Go back to step 1.
repository_not_accessible	Ask the user to add the repository to the PostHog GitHub App, then retry with a new idempotency_key.
run_already_active	The user already has a run in progress in this project. Ask them to wait for it, or check it in PostHog.
HTTP 429	The user reached the hourly or daily limit for setup runs. Relay the message. Don't retry right away.

Tell the user the run started and share the url from the response, where they can follow it in PostHog.

4. Poll the run

Call wizard-install-status with the run_id about every 30 seconds while status is created or running. A run usually takes several minutes.

• Relay next_step to the user when it changes. It is written to be passed on as is.
• Mention progress from tasks when it helps, but don't send an update on every poll.
• Stop polling when status is completed, failed, or cancelled.

When the client cannot wait that long in one turn, tell the user the run is in progress and check again when they come back.

5. Share the result

• completed with pull_request_url: share the link. Say the user should review the changes and merge the pull request to finish setting up PostHog.
• completed without pull_request_url: the setup agent changed nothing, often because PostHog is already set up. Relay next_step.
• failed: relay next_step and error_message. Offer to start a new run when next_step suggests one.