:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
PostHog AI scene — agent guide
This is the scene for PostHog AI, PostHog's agent. It hosts two coexisting runtimes, chosen per conversation by conversation.agent_runtime ('langgraph' | 'sandbox'):
langgraph— the legacy runtime. Frozen.sandbox— the new runtime (Claude Code/Codex agent-server over SSE). New work goes here.
Naming: the user-facing product is PostHog AI (was "Max"). Use "PostHog AI" in all user-facing copy. The directory stays
scenes/max/, and existing internal identifiers (Max*components,MaxUIContext,maxThreadLogic,maxContextLogic, the "Max Context" subsystem) keep their names — don't mass-rename. New code shouldn't introduce fresh "Max" branding in copy.
For the Max Context subsystem (how scenes expose dashboards/insights/events to the assistant), see
README.md. This guide does not repeat it.
1. Legacy vs new runtime — read this first
Per-concern mapping, langgraph (LEGACY, frozen) → sandbox (NEW, build here):
- Runtime flag:
agent_runtime === 'langgraph'→agent_runtime === 'sandbox' - Stream logic:
maxThreadLogic.tsx(LangGraph stream loop) →runStreamLogic(SSE; inproducts/posthog_ai/frontend/logics/) - Activity renderer:
components/Activity/LangGraphActivity.tsx→RunActivity(inproducts/posthog_ai/frontend/components/) - Thread renderer:
Thread.tsx(default path) →Thread.tsxbinds the surface'sThreadView - Context shape: rich
MaxUIContext(full objects) → flatAttachedContext(typed refs, agent fetches) - Approvals:
DangerousOperationApprovalCard.tsx/approvalOperationUtils.ts→ the surface'sPermissionInput/QuestionInput - Tool widgets:
messages/(LangGraph presenters) → the surface'stoolRegistry. The centralfrontend/src/posthogAiToolRenderers.tsmanifest combines product-owned declarations before rendering. Max consumes the widgets; it does not register them.
Rule: do not extend the LangGraph path unless explicitly asked
New behavior — new tools, new context types, new UI affordances — goes on the sandbox path. The LangGraph runtime is slated for removal once sandbox reaches parity; keeping its surface from growing makes the eventual deletion a clean removal rather than an untangling.
- ✅ Bugfixes that keep existing LangGraph conversations working.
- ✅ The quill skin of the LangGraph thread and composer behind
phai-quillortoday-rail-nav:Thread.tsx,QuillQuestionInput.tsx, theQuill*siblings incomponents/andmessages/quill/fork only the view, and share behavior throughuseQuestionInput,useModeSelector,useAnswerRatingand the surface's shared presenters. A message presenter that has both skins switches onuseQuillThread()at its top, likePlanningAnswer, and keeps its quill body inmessages/quill/. Code outside the thread (the composer,Intro, the suggestion badges) has no thread context, so it switches onuseThreadSkin()fromapi/logics, which reads the flags. It stays out ofapi/primitivesbecause the homepage composer loads eagerly. - ❌ Net-new capability on the LangGraph path.
- ❌ New fields on
MaxUIContextfor a sandbox feature — useAttachedContextinstead. - ❌ No new MaxTools.
If a task genuinely needs the LangGraph path extended, confirm that intent explicitly before touching maxThreadLogic.tsx, LangGraphActivity.tsx, max-constants.tsx (EnhancedToolCall), the MaxUIContext half of maxContextLogic.ts, or messages/.
2. Sandbox architecture & conventions live with the surface
The sandbox runtime's heart — runStreamLogic (SSE connection, the append-only log, the pure
foldLogToThread projection, permission routing) — and the conventions for working on it (logic-not-
component, runtime-agnostic plain-props UI, atomic memoized leaves, pure projection) are documented in
products/posthog_ai/frontend/AGENTS.md, where that code now lives. Read it before touching the surface.
What's Max-specific on the sandbox path and stays here: Thread.tsx branches high on
conversation.agent_runtime and, for the sandbox branch, binds runStreamLogic (keyed by the
conversation id) and renders ThreadView from the surface — passing resolved props down, never
parsing wire frames in a Max component.
4. The sandbox surface lives in products/posthog_ai/frontend
The conversation-agnostic sandbox run surface (stream logic, thread/tool/permission/composer components,
policy, wire types) no longer lives under scenes/max — it's the composable PostHog AI agent-run
library at products/posthog_ai/frontend, consumed here through its tiered api/<module> facade
(import { ... } from 'products/posthog_ai/frontend/api/readableRun' / api/runSurface / api/primitives /
api/logics / api/types / api/tools — there is no root barrel; pick the narrowest tier). See that
directory's README.md for the tier decision table + recipes and its AGENTS.md for layout, the public API
(ReadonlyRunSurface, the RunSurface compound, Thread, Composer, runStreamLogic, the tool registry),
and the hard rule that it must never import scenes/max.
What stays in scenes/max: conversation orchestration (maxLogic, maxThreadLogic, maxGlobalLogic), the
Max Context subsystem, slash commands, useMaxTool/MaxTool, feedback/ratings, and the frozen LangGraph
path (including its messages/* presenters). The PostHog product tool renderers (insight, dashboard,
recordings, notebook, query) live in products/posthog_ai/frontend/components/tool/widgets; error tracking
and replay vision own their widget families under their respective products/<product>/frontend directories.
Error tracking contributes a declaration list to the central manifest, so its cards render on the sandbox path too.
Replay vision has no declaration yet, so its scan widget renders only on the LangGraph path until one is added.
Max's LangGraph path consumes the heavier ones (VisualizationWidget / RecordingsWidget) through api/dataWidgets,
and error-tracking and replay-vision widgets directly from their owning products.
5. Where do I add X?
The first three now live in products/posthog_ai/frontend (the shared surface) — make the change there, not in scenes/max:
- A new thread-item type →
products/posthog_ai/frontend/types/streamTypes.ts(theThreadItemunion), handle it infoldLogToThread, and add a memoized leaf renderer wired intoThreadView/ThreadRow. - A new permission affordance / auto-approval rule →
products/posthog_ai/frontend/policy/toolPolicy.ts, then surface it throughPermissionInput. - New stream telemetry → a guarded
posthog.capturein the relevantrunStreamLogiclistener (fire-once, suppressed on replay). - A new product tool renderer (renders a PostHog entity) → the owning product’s frontend + declare it in
products/<product>/frontend/posthogAiToolRenderers.tsx(the central manifest makes it available before any scene renders). - New context the agent should see → register it from the owning product via the surface's context seam:
useAttachedContext/AttachedContextProvider/attachedContextLogic.registerContext(seeproducts/posthog_ai/frontend/AGENTS.md§3). NotMaxUIContext, and no new fields on the legacy stores. Scenes now register their on-screen context natively into that seam, andmaxThreadLogic's sandbox send merges the seam's items intoattached_context— that bridge lives here and is deleted withscenes/max. - UI that reacts to the agent calling a tool (sandbox path) → subscribe via the surface's
useToolStreamListener/toolStreamEventsLogic(resolved tool names, replay suppressed by default). The legacyuseMaxToolcallbackfires on LangGraph only.
6. Don'ts
- Don't extend the LangGraph runtime unless explicitly asked.
- Don't parse wire frames or hold SSE state inside a component.
- Don't mutate thread/invocation state from a listener — derive it in the projection.
- Don't add
MaxUIContextfields for a sandbox feature — useAttachedContext. - Don't subscribe to all sandbox selectors when you need one.
- Don't big-bang-move files on the active branch.