Zeta

Zeta is an agentic coding task management platform focused on fast planning, execution, and switching between coding tasks with minimal workflow overhead.

For deeper context:

• Product vision and requirements: PRODUCT.md
• Repository architecture and contributor conventions: AGENTS.md

Table of Contents

• Getting Started
• Tech Stack
• Monorepo Structure
• Architecture Overview
• Development Commands
• Package Generation
• Testing and Quality Checks
• Where to Learn More

Getting Started

Prerequisites

• Node.js 24.12.0 (managed via .node-version for fnm)
• npm 11.6.2

Install

From the repository root:

npm install

Run in Development

Run all workspace dev tasks through Turborepo:

npm run dev

Run only a specific workspace:

npm run dev -- --filter=@zeta/cli
npm run dev -- --filter=desktop

Tech Stack

• Monorepo and task orchestration: Turborepo + npm workspaces
• Language: TypeScript
• Desktop app: Electron + React + Vite + Tailwind CSS + shadcn/ui
• CLI app: Node.js + Commander
• Shared business logic: packages/commands (CQRS-style command/query flows)

Monorepo Structure

apps/
  cli/       # Node CLI adapter for shared commands
  desktop/   # Electron + React desktop UI
packages/
  commands/  # Shared domain/business commands and queries

Package Responsibilities

• packages/commands
  • Shared feature logic used by both desktop and CLI.
  • Uses feature-first folders and CQRS-style separation (commands for writes, queries for reads).
  • Current project-focused flows include project creation and project listing.
• apps/cli
  • Thin command-line adapter.
  • Parses input with Commander and delegates execution to @zeta/commands.
  • Current command shape includes zeta projects add [folderPath].
• apps/desktop
  • Electron shell with React renderer.
  • Presents feature UI (tasks, projects, agents, automations) and calls shared logic through IPC handlers backed by @zeta/commands.

Architecture Overview

This repo follows vertical-slice/feature-first architecture:

• Keep feature code together; only move code to shared locations when truly shared.
• Separate write and read flows (CQRS mindset).
• Prefer composition over inheritance.
• Model operations as focused units with a single execute path.

In packages/commands, a typical slice includes:

• command/query contracts
• service for validation/business rules
• facade for orchestration
• repository for persistence
• model/response contracts

Development Commands

Run from repo root unless noted.

npm run dev
npm run build
npm run lint
npm run typecheck

Useful filtered runs:

npm run dev -- --filter=@zeta/cli
npm run dev -- --filter=desktop
npm run build -- --filter=@zeta/commands

Workspace-level examples:

npm --workspace apps/desktop run dev
npm --workspace apps/cli run build
npm --workspace apps/cli run start

Package Generation

Use Turborepo generators to scaffold new workspaces and React component packages.

# Interactive built-in workspace generator
npm run gen:workspace

# Workspace templates backed by local template packages
npm run gen:workspace:ts-lib
npm run gen:workspace:react-ui

# Custom React component package generator
npm run gen:react-package

Template workspaces used by turbo generate workspace --copy ...:

• @zeta/template-ts-lib
• @zeta/template-react-ui

Testing and Quality Checks

• Automated tests: no committed test framework yet.
• Use these checks today:

npm run lint
npm run typecheck
npm run build

Where to Learn More

• PRODUCT.md: goals, requirements, non-goals, and success criteria.
• AGENTS.md: architecture conventions, package responsibilities, coding style, and contribution guidance.