Skip to content

Commit 0b337a5

Browse files
TwixesTwixes
committed
feat: add documentation for new Inbox product
1 parent 73df64a commit 0b337a5

14 files changed

Lines changed: 533 additions & 6 deletions

‎contents/docs/inbox/changelog.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Inbox Changelog
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
## 2024-05-20: Inbox Beta Launch
8+
9+
We are excited to launch the first beta of **Inbox**!
10+
11+
### Features
12+
- **Signal Sources:** Connect PostHog Error Tracking, Support, and GitHub Issues.
13+
- **AI Prioritization:** Automated P0-P3 ranking based on product impact.
14+
- **Self-Driving Research:** Agents use MCP to find root causes in your codebase.
15+
- **Automated PRs:** One-click implementation for actionable bugs.
16+
17+
---
18+
19+
For older updates on PostHog Code, check the [PostHog Code Changelog](/docs/code/changelog).

‎contents/docs/inbox/research-and-implementation.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Research and Implementation
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
The "self-driving" magic of Inbox happens through two core background tasks: **Research** and **Implementation**. These are performed by autonomous AI agents.
8+
9+
## Research Tasks
10+
11+
When a signal (like a Sentry error or a GitHub issue) arrives, an agent is dispatched to investigate.
12+
13+
### Codebase Context (MCP)
14+
The agent uses a **Model Context Protocol (MCP) server** to interact with your codebase. This allows it to:
15+
- Search for specific symbols, classes, or functions.
16+
- Read file contents.
17+
- List directory structures.
18+
19+
### Root Cause Analysis
20+
By combining the production signal (e.g., a stack trace from Error Tracking) with codebase access, the agent identifies the root cause.
21+
- **Example:** An agent sees a `DoesNotExist` error in production data and finds the exact line in `billing_manager.py` where a database query is missing a null check.
22+
23+
## Implementation Tasks
24+
25+
Once the research is complete and a fix is identified, the agent moves to implementation.
26+
27+
### Sandboxed Execution
28+
The agent clones your repository into a secure, sandboxed environment. It then:
29+
1. Creates a new git branch (e.g., `ai-fix/billing-null-check`).
30+
2. Applies the code changes.
31+
3. Runs any local tests (if configured).
32+
33+
### Pull Request Generation
34+
The agent pushes the branch to your remote (e.g., GitHub) and opens a Pull Request.
35+
- **Description:** The PR includes an AI-generated summary of the problem, the proposed change, and the research reasoning.
36+
- **Labels:** PRs are automatically labeled with `LLM context` or `PostHog Agent` to notify reviewers.
37+
38+
## Auditing the Agent
39+
40+
Every action the agent takes is logged. You can view the **Agent Log** directly in the Inbox to see:
41+
- Which files the agent read.
42+
- Which search queries it ran.
43+
- How it arrived at the final implementation logic.
44+
45+
This transparency ensures that you can trust the "self-driving" process even as it automates the tedious parts of your job.

‎contents/docs/inbox/signal-sources.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Connecting Signal Sources
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
Inbox identifies potential work by monitoring **Signal Sources**. These sources provide the raw data that AI agents use to research and triage issues.
8+
9+
## Internal PostHog Sources
10+
11+
These sources are available by default if you are already using PostHog.
12+
13+
### Error Tracking
14+
Monitors your production exceptions. Inbox triggers reports when:
15+
- A new unique error is first seen.
16+
- An error is reopened after being marked resolved.
17+
- There is a significant spike in error volume for an existing issue.
18+
19+
### Support Conversations
20+
Analyzes user support tickets from PostHog's built-in [support features](/docs/support). It identifies actionable bug reports or feature requests hidden within user chats.
21+
22+
### Session Replay
23+
(Beta) Uses AI to analyze [session recordings](/docs/session-replay) for anomalous user behavior, UX friction points, or rage clicks that don't necessarily trigger an error log.
24+
25+
## External Integrations
26+
27+
You can connect external tools to Inbox to consolidate your engineering work into one place.
28+
29+
### GitHub Issues
30+
Inbox monitors your repositories for new issues. When a GitHub issue is opened, Inbox automatically kicks off a **Research Task** to see if it can propose a fix.
31+
32+
### Linear & Zendesk
33+
By connecting Linear (for project management) or Zendesk (for customer support), Inbox can:
34+
1. Read the ticket/issue context.
35+
2. Search your codebase for relevant logic.
36+
3. Propose a fix that references the original ticket ID.
37+
38+
## Configuration
39+
40+
To manage your sources:
41+
1. Navigate to **Inbox** in the main PostHog navigation.
42+
2. Click the **Settings** icon (or the "Signal Sources" tab).
43+
3. Toggle the sources you wish to enable and follow the authentication prompts for external services.
44+
45+
> **Note:** For agents to successfully research issues from these sources, you must have a connected repository with a configured [MCP server](/docs/ai-engineering/mcp).

‎contents/docs/inbox/start-here.mdx‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Getting started with Inbox
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
import { QuestLog, QuestLogItem } from 'components/Docs/QuestLog'
8+
import OSButton from 'components/OSButton'
9+
10+
PostHog **Inbox** is your command center for self-driving development. It uses signals from your production data—like error spikes, user complaints, and session anomalies—to automatically research issues, write code fixes, and open pull requests.
11+
12+
Instead of reactive firefighting, Inbox moves your workflow to a "proactive merging" model where AI agents do the heavy lifting of investigation and implementation.
13+
14+
<QuestLog firstSpeechBubble="Let's set up your self-driving command center!" lastSpeechBubble="Your Inbox is ready. Time to start merging!">
15+
16+
<QuestLogItem
17+
title="Connect your Signal Sources"
18+
subtitle="Required"
19+
icon="IconPlug"
20+
>
21+
22+
Inbox identifies work by monitoring "Signals." To get started, you need to connect the sources where your product data and user feedback live.
23+
24+
- **Internal:** Enable [Error Tracking](/docs/error-tracking), [Support Conversations](/docs/support), and [Session Replay](/docs/session-replay).
25+
- **External:** Connect your [GitHub Issues, Linear, or Zendesk](/docs/inbox/signal-sources) accounts.
26+
27+
<OSButton variant="primary" asLink to="/docs/inbox/signal-sources">
28+
Configure sources
29+
</OSButton>
30+
31+
</QuestLogItem>
32+
33+
<QuestLogItem
34+
title="Triage actionable reports"
35+
subtitle="Required"
36+
icon="IconTerminal"
37+
>
38+
39+
Once sources are connected, Inbox clusters signals into **Reports**. Each report is automatically ranked by:
40+
41+
- **Priority (P0-P3):** Determined by the impact on user flow and code importance.
42+
- **Actionability:** Marked as "Actionable" if an agent has found a clear path to a fix.
43+
44+
Review your first report to see the root cause analysis and the proposed resolution logic.
45+
46+
<OSButton variant="primary" asLink to="/docs/inbox/triage-and-priority">
47+
Learn about prioritization
48+
</OSButton>
49+
50+
</QuestLogItem>
51+
52+
<QuestLogItem
53+
title="Audit Agent Research"
54+
subtitle="Recommended"
55+
icon="IconMagnifyingGlass"
56+
>
57+
58+
For actionable reports, an AI agent automatically performs a **Research Task**. It uses the [Model Context Protocol (MCP)](/docs/ai-engineering/mcp) to search your codebase and identify the exact lines of code causing the issue.
59+
60+
You can audit the agent's logs to see exactly how it navigated your repo and reached its conclusions.
61+
62+
<OSButton variant="primary" asLink to="/docs/inbox/research-and-implementation">
63+
See how agents research
64+
</OSButton>
65+
66+
</QuestLogItem>
67+
68+
<QuestLogItem
69+
title="Merge your first PR"
70+
subtitle="The Goal"
71+
icon="IconRocket"
72+
>
73+
74+
When research is complete, the agent executes an **Implementation Task**: cloning your repo, creating a branch, and opening a GitHub PR.
75+
76+
Each PR includes an AI-generated description of the problem and the change. Your job is simply to review the code in GitHub and click **Merge**.
77+
78+
<OSButton variant="primary" asLink to="/docs/inbox/research-and-implementation#implementation-tasks">
79+
Review the PR workflow
80+
</OSButton>
81+
82+
</QuestLogItem>
83+
84+
</QuestLog>
85+
86+
## Next steps
87+
88+
- Explore [how prioritization works](/docs/inbox/triage-and-priority) to focus on what matters.
89+
- Deep dive into [Agent Research](/docs/inbox/research-and-implementation) to understand the "self-driving" engine.
90+
- If you run into issues, check the [troubleshooting guide](/docs/inbox/troubleshooting).

‎contents/docs/inbox/triage-and-priority.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Triage and Prioritization
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
The Inbox isn't just a list of errors; it's an intelligent triage system. It uses AI to cluster millions of raw signals into actionable **Reports** and ranks them so you know what to work on first.
8+
9+
## Understanding Reports
10+
11+
A **Report** is a high-level summary of an issue. Each report contains:
12+
- **The "What":** A clear description of the bug or problem.
13+
- **Priority:** Ranked from P0 (Critical) to P3 (Low).
14+
- **Actionability:** A status indicating if the AI agent has found a clear path to a code-based fix.
15+
16+
## How Priority is Determined
17+
18+
Inbox uses a "Product-Aware" prioritization engine. Instead of just looking at error frequency, it analyzes:
19+
1. **Code Importance:** Does the issue occur in a "hot path" like your checkout, signup, or billing logic?
20+
2. **User Impact:** How many unique users are affected? Are they on a high-value billing plan?
21+
3. **Severity:** Is the product completely broken for these users, or is it a minor UX glitch?
22+
23+
## The Triage Workflow
24+
25+
1. **P0 & P1 (Immediate Action):** These should be your first priority. If they are marked as **Actionable**, an agent has likely already opened a pull request.
26+
2. **Actionable Reports:** Focus on these even if the priority is lower. These represent "slam dunk" fixes where the agent has already done the research and implementation work for you.
27+
3. **Needs Research:** If a report isn't yet actionable, you can manually trigger a **Research Task** to have an agent investigate the codebase.
28+
29+
## Assigning Owners
30+
31+
Inbox automatically suggests reviewers and owners for each report based on:
32+
- **GitHub Blame:** Who recently touched the affected lines of code.
33+
- **Historical Ownership:** Who has resolved similar issues in this part of the codebase before.

‎contents/docs/inbox/troubleshooting.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Troubleshooting
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
## Common Issues
8+
9+
### Sources are connected but no signals appear
10+
- **Check Permissions:** Ensure your PostHog API key has `read` permissions for the products you've enabled (e.g., Error Tracking).
11+
- **Verify Activity:** Signals only appear for *new* activity. If your product currently has no errors or support tickets, the Inbox will remain empty.
12+
13+
### Agent fails to find the root cause
14+
- **MCP Server Status:** Ensure your [MCP server](/docs/ai-engineering/mcp) is correctly configured and reachable by PostHog.
15+
- **Codebase Indexing:** Large repositories may take time to index. If the agent can't find a file you know exists, try re-triggering the Research Task.
16+
17+
### GitHub PRs aren't being created
18+
- **GitHub App Installation:** Ensure the PostHog GitHub App is installed on the specific repositories you want to automate.
19+
- **Branch Permissions:** The agent needs permission to push branches to your repository. Check your GitHub branch protection rules.
20+
21+
### Prioritization feels incorrect
22+
- **Hot Path Configuration:** You can manually tag certain files or directories as "Hot Paths" in your Inbox settings to increase the priority of issues occurring in those files.
23+
24+
## Getting Help
25+
26+
If you're still stuck:
27+
- Check our [community forum](/questions).
28+
- Reach out to us via the **Support** widget in your PostHog instance.

‎contents/docs/posthog-code/inbox-changelog.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Inbox Changelog
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
## 2024-05-20: Inbox Beta Launch
8+
9+
We are excited to launch the first beta of **Inbox**!
10+
11+
### Features
12+
- **Signal Sources:** Connect PostHog Error Tracking, Support, and GitHub Issues.
13+
- **AI Prioritization:** Automated P0-P3 ranking based on product impact.
14+
- **Self-Driving Research:** Agents use MCP to find root causes in your codebase.
15+
- **Automated PRs:** One-click implementation for actionable bugs.
16+
17+
---
18+
19+
For older updates on PostHog Code, check the [PostHog Code Changelog](/docs/code/changelog).

‎contents/docs/posthog-code/inbox-research.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Research and Implementation
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
The "self-driving" magic of Inbox happens through two core background tasks: **Research** and **Implementation**. These are performed by autonomous AI agents.
8+
9+
## Research Tasks
10+
11+
When a signal (like a Sentry error or a GitHub issue) arrives, an agent is dispatched to investigate.
12+
13+
### Codebase Context (MCP)
14+
The agent uses a **Model Context Protocol (MCP) server** to interact with your codebase. This allows it to:
15+
- Search for specific symbols, classes, or functions.
16+
- Read file contents.
17+
- List directory structures.
18+
19+
### Root Cause Analysis
20+
By combining the production signal (e.g., a stack trace from Error Tracking) with codebase access, the agent identifies the root cause.
21+
- **Example:** An agent sees a `DoesNotExist` error in production data and finds the exact line in `billing_manager.py` where a database query is missing a null check.
22+
23+
## Implementation Tasks
24+
25+
Once the research is complete and a fix is identified, the agent moves to implementation.
26+
27+
### Sandboxed Execution
28+
The agent clones your repository into a secure, sandboxed environment. It then:
29+
1. Creates a new git branch (e.g., `ai-fix/billing-null-check`).
30+
2. Applies the code changes.
31+
3. Runs any local tests (if configured).
32+
33+
### Pull Request Generation
34+
The agent pushes the branch to your remote (e.g., GitHub) and opens a Pull Request.
35+
- **Description:** The PR includes an AI-generated summary of the problem, the proposed change, and the research reasoning.
36+
- **Labels:** PRs are automatically labeled with `LLM context` or `PostHog Agent` to notify reviewers.
37+
38+
## Auditing the Agent
39+
40+
Every action the agent takes is logged. You can view the **Agent Log** directly in the Inbox to see:
41+
- Which files the agent read.
42+
- Which search queries it ran.
43+
- How it arrived at the final implementation logic.
44+
45+
This transparency ensures that you can trust the "self-driving" process even as it automates the tedious parts of your job.

‎contents/docs/posthog-code/inbox-sources.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Connecting Signal Sources
3+
sidebar: Docs
4+
showTitle: true
5+
---
6+
7+
Inbox identifies potential work by monitoring **Signal Sources**. These sources provide the raw data that AI agents use to research and triage issues.
8+
9+
## Internal PostHog Sources
10+
11+
These sources are available by default if you are already using PostHog.
12+
13+
### Error Tracking
14+
Monitors your production exceptions. Inbox triggers reports when:
15+
- A new unique error is first seen.
16+
- An error is reopened after being marked resolved.
17+
- There is a significant spike in error volume for an existing issue.
18+
19+
### Support Conversations
20+
Analyzes user support tickets from PostHog's built-in [support features](/docs/support). It identifies actionable bug reports or feature requests hidden within user chats.
21+
22+
### Session Replay
23+
(Beta) Uses AI to analyze [session recordings](/docs/session-replay) for anomalous user behavior, UX friction points, or rage clicks that don't necessarily trigger an error log.
24+
25+
## External Integrations
26+
27+
You can connect external tools to Inbox to consolidate your engineering work into one place.
28+
29+
### GitHub Issues
30+
Inbox monitors your repositories for new issues. When a GitHub issue is opened, Inbox automatically kicks off a **Research Task** to see if it can propose a fix.
31+
32+
### Linear & Zendesk
33+
By connecting Linear (for project management) or Zendesk (for customer support), Inbox can:
34+
1. Read the ticket/issue context.
35+
2. Search your codebase for relevant logic.
36+
3. Propose a fix that references the original ticket ID.
37+
38+
## Configuration
39+
40+
To manage your sources:
41+
1. Navigate to **Inbox** in the main PostHog navigation.
42+
2. Click the **Settings** icon (or the "Signal Sources" tab).
43+
3. Toggle the sources you wish to enable and follow the authentication prompts for external services.
44+
45+
> **Note:** For agents to successfully research issues from these sources, you must have a connected repository with a configured [MCP server](/docs/ai-engineering/mcp).

0 commit comments

Comments
 (0)