Harvest 🌱

The Holons monorepo — one shared core, five interfaces

Harvest is the unified codebase of the Holons ecosystem. It is a pnpm monorepo containing one shared core (@holons/core) and a family of interfaces that all call into it. Every action—create a task, vote on a proposal, log an expense, publish to federation—means the same thing in every interface, because every interface invokes the same core function.

What was once "the Harvest dashboard" is now apps/web inside this monorepo. The Telegram bot, CLI, AI agent loop, and MCP server live alongside it as sibling packages.

Architecture

         ┌────────────────────────────────────────────────────────┐
         │                    @holons/core                        │
         │  scoring · tasks · federation · holosphere · shopping  │
         │  settings · dna · users · expenses · calendar · library│
         │  checklists · council · categories · commands · REA    │
         └────────────────────────────────────────────────────────┘
            ▲          ▲          ▲          ▲           ▲
            │          │          │          │           │
       ┌────────┐ ┌─────────┐ ┌────────┐ ┌────────┐ ┌─────────┐
       │harvest-│ │telegram-│ │text-ui │ │ai-ui   │ │mcp-ui   │
       │  web   │ │   ui    │ │ (CLI)  │ │(Claude)│ │(MCP srv)│
       └────────┘ └─────────┘ └────────┘ └────────┘ └─────────┘
                              │
                       ▼
              HoloSphere (GunDB + Nostr federation)

Packages

Package

Path

What it owns

@holons/core

packages/core/

UI-agnostic domain logic. Scoring, tasks, federation, HoloSphere I/O, DNA, users, expenses, calendar, library, checklists, council, categories, commands, REA.

harvest-web

apps/web/

SvelteKit web app — Mapbox/H3 visualizations, schema-driven forms, federation UI. The "dashboard" most people mean when they say Harvest.

@holons/telegram-ui

packages/telegram-ui/

Telegraf bot — scenes, inline keyboards, Puppeteer screenshots. The current incarnation of HolonsBot.

@holons/text-ui

packages/text-ui/

Framework-agnostic CLI / REPL. Calls @holons/core/commands.

@holons/ai-ui

packages/ai-ui/

In-process Claude tool-use loop. Exposes @holons/core/commands directly as Claude tools so an agent can drive a holon in natural language.

@holons/mcp-ui

packages/mcp-ui/

MCP server — every public @holons/core function as an independently-callable MCP tool. Used by Claude Desktop, IDE integrations, and external agents.

The shared core

Every domain in @holons/core is published under a subpath export, so any UI imports just what it needs:

import { calculateUserScore } from '@holons/core/scoring';
import { createTask }         from '@holons/core/tasks';
import { publishFederation }  from '@holons/core/federation';

There is no cross-domain barrel — each domain stands on its own under packages/core/src/<domain>/index.ts. This is what keeps the five UIs in sync without coupling them.

A non-exhaustive view of the domains:

scoring — value-equation evaluation, per user / per action / breakdown
tasks — unified quest model (tasks, proposals, events, offers, requests)
council — proposal lifecycle and consent-based voting
dna — holon DNA sequences and chromosomes
federation — cross-holon publishing via HoloSphere + Nostr
holosphere — identity-aware reads and writes against the substrate
expenses — shared cost logging and splitting
calendar — events, recurring events, scheduling
users — multi-holon membership and appreciation tracking
library — shared resource catalog with tagging and search
checklists — recurring and role-based task lists
rea — Resource-Event-Agent accounting model
settings, categories, commands — supporting domains

Each domain has its own vitest suite under packages/core/src/<domain>/<domain>.test.ts.

The web dashboard

apps/web (formerly the standalone Harvest repo) is the SvelteKit visualization surface:

Holonic network visualization 🕸️

Interactive network graph showing holons and their relationships
Real-time updates of holon states and connections
Zoom and pan controls for easy navigation
Color-coded nodes representing different holon types and states

Holon management 🎛️

View detailed information about individual holons
Monitor holon health and status
Inspect holon properties and configurations
Track holon relationships and dependencies

Sidebar controls 📊

Filter holons by type or status
Search functionality to quickly find specific holons
Collapsible sidebar for maximizing view space
Real-time metrics and statistics

Mapbox and H3 power the geospatial views; schema-driven forms let any lens defined in core be edited from the UI.

Getting started

The monorepo uses pnpm workspaces. Node ≥20 and pnpm ≥10 are required.

# Clone the monorepo (or the standalone harvest-web, if a partial checkout is preferred)
git clone https://github.com/liminalvillage/harvest.git
cd harvest

# Install all workspaces with a single lockfile
pnpm install

# Typecheck and build all packages
pnpm -r typecheck
pnpm -r build

To run a specific UI:

Command

What it starts

pnpm dev

The web dashboard (apps/web)

pnpm dev:bot

The Telegram bot

pnpm -F @holons/text-ui exec holons --help

The CLI

pnpm -F @holons/ai-ui exec holons-ai "…"

The Claude AI loop (needs ANTHROPIC_API_KEY)

node packages/mcp-ui/dist/index.js

The MCP server (stdio)

node packages/mcp-ui/dist/index.js --port 3200

The MCP server (SSE on HTTP)

Memory management (web dashboard)

When working with large holonic networks, memory usage can be significant due to the amount of data being processed and visualized. If you encounter "JavaScript heap out of memory" errors:

# Set Node.js memory limit to 4GB
export NODE_OPTIONS="--max-old-space-size=4096"
pnpm dev

For long-running production deployments, set memory limits based on your server specifications and the size of the federated network you expect to visualize.

Adding a new shared domain

Create packages/core/src/<domain>/{index.ts, …}.ts and export from index.ts. Subpath exports cover it automatically via packages/core/package.json wildcards.
Add a vitest spec at packages/core/src/<domain>/<domain>.test.ts.
If the domain needs a new dep, add it to packages/core/package.json dependencies.

The same domain becomes available to every UI without any per-UI plumbing—and, because @holons/mcp-ui auto-registers tools for known domains, also becomes callable as an MCP tool with no extra work beyond writing a thin wrapper.

Adding a new UI

Create packages/<my-ui>/src/ and copy packages/text-ui/{package.json,tsconfig.json} as a starting point.
Depend on @holons/core via "@holons/core": "workspace:*".
Run pnpm install from the repo root.
Implement the renderer/parser/input-mode against @holons/core/commands so all UIs invoke the same actions.