Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Run Your First Holon

An end-to-end walkthrough from zero to a federated, scored, MCP-callable holon

This is the practical companion to What is a Holon?. It walks through the actual steps of getting a holon running—people coordinating in chat, contributions being recognized, work being scored, federation to other holons, and AI agents able to participate via MCP.

You can stop after any step. Each one produces a working holon at a different level of capability.

Level 0 — A chat group

The simplest holon is a group of people coordinating in one channel. No tools required.

  1. Create a Telegram (or any chat) group.

  2. Write the holon's purpose in the channel description: one sentence about what the holon is for.

  3. Invite the people who will participate.

That's it. You have a holon: it has a membrane (the group), shared DNA (the purpose), and members. Everything that follows just makes it more legible.

Level 1 — Add HolonsBot

This step turns informal coordination into structured, attributable records.

  1. Follow Setting up your holonic organization to deploy HolonsBot (or its modern incarnation @holons/telegram-ui) into the group.

  2. Add the bot as an administrator.

  3. Try the basic verbs:

Verb
Example

Create a task

/task water the seedlings

Recognize a contribution

/appreciate @laura for hosting tonight's call

Make an offer

/offer yoga sessions on Tuesday mornings

Make a request

/request someone to drive the truck on Friday

See where everyone stands

/status

The holon now has a task log, an appreciation record, and an open board of needs and offers. It is a Managed Holon.

Level 2 — Define what counts

The next step is to make the holon's values explicit. This is what shapes what gets recognized.

  1. Add chromosomes describing your values, tools, and practices — through the bot or directly via the DNA domain.

  2. Build a DNA sequence from the chromosomes that most define this holon (max 20).

  3. Tune the value equation weights so contributions you care about (hours, appreciations, completed quests, specific currencies) carry the right relative weight.

A nature-stewardship holon might weight outcomes (completed) and appreciations heavily, with hours secondary. A research collective might weight hours and currencies (paid grants) higher. There is no universal right answer—the equation is the culture.

Level 3 — Federate

A single holon is useful. A federation is regenerative.

  1. Identify one or two sibling holons—other groups doing related work.

  2. Use the bot's /federate command (or call the federation domain directly) to declare the trust relationship.

  3. Once federated, you can publish quests, offers, requests, or appreciations across the boundary. Holons that share a settings hex can also be discovered by anyone subscribing to that cell.

Federation is bilateral and revocable. Each side keeps its own DNA, value equation, and rules; only the items each chooses to publish cross the membrane.

Level 4 — Open to AI agents

This is what makes the difference between a holon that AI watches and a holon AI participates in.

Option A — In-process Claude loop

Use @holons/ai-ui when you want intelligence embedded in the holon's own infrastructure (a bot handler, a cron job, a webhook):

The agent runs as the holon, with the actor identity you've configured (HOLONS_ACTOR_* env vars).

Option B — MCP server for external agents

Use @holons/mcp-ui when you want external clients (Claude Desktop, IDE plugins, custom agents) to participate:

Configure the MCP client with the appropriate HOLONS_PEER, HOLONS_APP, and HOLONS_ACTOR_* env vars. The agent now sees ~100 tools spanning every core domain.

A holon at this level has:

  • Humans coordinating through chat.

  • Programmatic records (tasks, expenses, appreciations) that drive scoring.

  • A clear identity (DNA) and culture (value equation).

  • Trust relationships with sibling holons (federation).

  • AI agents able to read, write, and act as first-class members.

A worked example: the community garden

Three people start a neighborhood garden:

  1. Level 0. They create a Telegram group, write "we steward this land and grow food for the block" in the description, and invite five neighbors.

  2. Level 1. They add HolonsBot. The first week they log 11 tasks (/task plant herbs, /task fix the gate hinge) and exchange 23 appreciations.

  3. Level 2. They add chromosomes — regenerative practice, mutual aid, gardening tools, consent-based decisions. They tune their value equation: completed: 3 (outcomes matter more than starting things), appreciations: 2 (peer recognition is core), hours: 1. The bot's /status now reflects what they actually value.

  4. Level 3. Three nearby gardens federate with them. A surplus harvest gets /published to the federation; a request for help with a workshop reaches all four gardens at once. A bioregional aggregator subscribed to the settings-hex picks up the workshop and lists it on a regional board.

  5. Level 4. They configure the MCP server with the garden's identity and connect Claude. Now a member can ask Claude, in a sentence, to "schedule a watering rotation for the next two weeks based on the weather forecast and people's stated availability." Claude reads the holon's state, calls the appropriate MCP tools, and the rotation appears as a set of recurring quests—every member can see, accept, or reassign them.

Where to go from here

  • Tune the system. Read Scoring and adjust your value equation; read DNA and refine your chromosomes.

  • Compose flavors. Layer a Splitter Holon on top to route incoming funds; declare Zones for differentiated participation.

  • Connect deeper. Read Funding Flow for the protocol-level mechanics of multi-currency, threshold-based distribution.

  • Glossary. Anything unfamiliar lives in the Glossary.

PreviousWhat is a Holon?NextGlossary

Last updated

Was this helpful?