Twig

Project Positioning#

Twig is an Agentic Development Environment developed by PostHog, designed to free product engineers from daily distractions through AI agents. The project is currently in pre-alpha stage, officially marked as "not production-ready".

Core Components#

Agent Framework Capabilities#

• ACP Protocol: Standardized agent-client communication via Agent Client Protocol
• Multiple Adapters: Claude (in-process), Codex (subprocess stdin/stdout)
• Permission Modes: Always ask (default) / Accept edits / Plan mode / Bypass permissions
• Execution Environment: Cloud sandbox + local in-process dual mode
• Session Recovery: SessionLogWriter + ResumeSaga atomic operations with auto-rollback
• Tree State Tracking: TreeTracker captures git worktree snapshots for cloud↔local switching

Architecture Design#

Main Process (Node.js)              Renderer Process (React)
┌───────────────────────┐           ┌───────────────────────────┐
│  DI Container         │           │  DI Container             │
│  ├── GitService       │◄─tRPC──►│  ├── TRPCClient           │
│  └── ...              │  (ipc)   │  └── TaskService, ...     │
├───────────────────────┤           ├───────────────────────────┤
│  System I/O           │           │  Zustand Stores (state)   │
│  (fs, git, shell)     │           │                           │
└───────────────────────┘           └───────────────────────────┘

Tech Stack: Electron + React + TypeScript (98.3%) + Tailwind CSS + Zustand + Vite + InversifyJS + tRPC + Zod

Installation#

Prerequisites: Node.js 22+, pnpm 10.23.0

npm install -g pnpm
pnpm install
cp .env.example .env
pnpm dev  # Run agent and twig app in parallel

Agent SDK Usage#

import { Agent } from "@posthog/agent/agent"

const agent = new Agent({
  posthog: {
    apiUrl: "https://app.posthog.com",
    getApiKey: () => process.env.POSTHOG_PERSONAL_API_KEY!,
    projectId: 12345,
  },
})

const connection = await agent.run(taskId, runId, {
  repositoryPath: "/path/to/repo",
  adapter: "claude", // or "codex"
})

Key Configuration#

Environment Variables: POSTHOG_API_KEY, POSTHOG_API_HOST, POSTHOG_PERSONAL_API_KEY, POSTHOG_PROJECT_ID, JWT_PUBLIC_KEY

Workspace Config (twig.json):

{
  "scripts": {
    "init": "npm install",
    "start": ["npm run server", "npm run client"],
    "destroy": "docker-compose down"
  }
}

Project Activity#

• Current Version: v0.27.15
• Releases: 286+
• Contributors: 18+
• Organization: PostHog Inc.
• Contact: jonathan@posthog.com