Alphomi

English | 简体中文

Alphomi is an open local agent workspace for the web and your computer. It combines an Electron desktop shell, a Playwright browser driver, and a Python brain service into one contributor-friendly product.

Table of Contents

• Overview
• Screenshots
• Why Alphomi
• Architecture
• Repository Layout
• Quick Start
• Documentation
• Community

Overview

Alphomi is designed as a local-first agent workspace:

• Browse and work inside a desktop browser shell with tabs, navigation, downloads, and an AI sidebar.
• Run browser automation through a Playwright-based Driver.
• Orchestrate tool calls, approvals, and multi-agent workflows through a Python Brain service.
• Keep the repository open-source and modular while shipping as one desktop product.

Back to top

Screenshots

Alphomi ships with both light and dark desktop themes for the browser workspace and AI sidebar.

Light Mode	Dark Mode

Back to top

Why Alphomi

• Local-first: the Desktop, Driver, and Brain can run on your machine for fast iteration and controlled data flow.
• Contributor-friendly: the monorepo keeps app boundaries clear instead of hiding setup behind implicit scripts.
• Open-source ready: shared contracts, config docs, release notes, and maintainer guides live in the repository.
• One product, multiple runtimes: Electron handles the desktop UX, Playwright handles browser control, and Python handles orchestration.

Back to top

Architecture

flowchart LR
    U["User"] --> D["Desktop (Electron + React)"]
    D --> P["Driver (Node + Playwright)"]
    D --> B["Brain (FastAPI + WebSocket)"]
    B --> P
    B --> L["LLM API"]
    P --> C["Chromium / BrowserView / CDP"]

Loading

This repository follows a dual-stack monorepo design:

• apps/desktop owns the desktop shell and renderer UX.
• apps/driver owns Playwright sessions, automation, snapshots, and browser-facing tools.
• apps/brain owns LLM orchestration, approvals, and agent workflows.
• packages/contracts and packages/config provide shared protocol and configuration references.

Architecture Guide | ADR: Dual-Stack Monorepo | ADR: Bundled Brain Binary

Back to top

Repository Layout

apps/
  desktop/         Electron + React desktop shell
  driver/          Playwright driver and automation adapter
  brain/           Python brain service
packages/
  contracts/       Shared schemas and protocol references
  config/          Shared configuration defaults and schema docs
  ui/              Shared UI primitives for the desktop renderer
tools/
  eval-manager/    Evaluation and operational tooling
docs/
  adr/             Architecture decision records
  guides/          Contributor and release documentation
test/              Cross-app smoke and regression scripts

Back to top

Quick Start

Prerequisites

• Node.js 18.18+
• pnpm 8+
• Python 3.11+
• uv recommended for Python environment management

Bootstrap

pnpm bootstrap

pnpm bootstrap installs workspace dependencies, prepares the Python environment, installs Playwright browsers, and creates a local config.yaml from config.example.yaml if needed.

Run the Full Workspace

pnpm dev

Run a Single Layer

pnpm dev:desktop
pnpm dev:driver
pnpm dev:brain

Validate the Repository

pnpm doctor
pnpm typecheck
pnpm test
pnpm smoke
pnpm validate

Package a Local App Build

pnpm run package:mac:dir

Development Guide | Testing Guide | Release Guide

Back to top

Documentation

Getting Started

• Configuration Guide
• Development Guide
• Testing Guide
• Troubleshooting Guide

Maintainer References

• Architecture Guide
• Release Guide
• Release Checklist
• Maintainer Guide

Project Context

• Roadmap
• Changelog
• ADR Template

Back to top

Community

• Contributing Guide
• Code of Conduct
• Security Policy
• Support

The repository is currently UNLICENSED while the open-source release details are still being finalized.

Back to top