An operating system for AI agents. Built to last.
A minimal kernel. Modular extensions. Trees that hold data, run AI, and connect to each other across a federated network. Everything below explains how.
Human thought is structured like a tree. Language reflects that structure. So if you build a system as a tree, you can use language directly as the interface.
Every AI framework starts from code: "How do I chain LLM calls? How do I manage context? How do I route between agents?" They build plumbing and hope meaning emerges. The language and the system are separate things with a translation layer between them. That translation layer is always the weak point.
TreeOS noticed that concepts already branch like a tree. "Health" divides into "Fitness" and "Food." "Fitness" divides into exercises. That's not a database schema someone designed. That's how concepts actually relate. The hierarchy is natural. So TreeOS structured its translation layer to mirror that hierarchy. The routing feels invisible because it follows the same shape as the concepts it routes.
The AI doesn't execute your intent through a foreign layer. It inhabits the node you're standing at. At a fitness node its tools are workout-specific, its context is sets and reps, its mode determines coaching vs logging. At a food node everything shifts to macros and meals. Same AI, different environment, shaped entirely by position.
Most AI frameworks are imperative: you tell the system what to do. In TreeOS, the routing is declarative: you tell it where you are, and the doing follows. The tools, context, and constraints change based on position. The architecture does the work that prompt engineering usually does. The AI has genuine situational awareness through structure, not through one giant system prompt.
You plant a seed on a server. It grows trees. Each tree is a hierarchy of nodes where AI lives permanently. It builds structure, accumulates knowledge, tracks data, and talks to people through any channel. Navigate to a position in the tree and the AI changes what it can do, what it knows, and how it thinks. Position determines reality.
The kernel is minimal. Two database schemas (Node and User), a conversation loop, a hook system, a cascade engine, and an extension loader. Everything else is an extension you install. Strip every extension and the kernel still boots. It defines the contract that everything builds on.
TreeOS is one operating system built on the kernel. 120 extensions across four bundles plus base and standalone. But TreeOS is just one interpretation. A medical platform, a code review pipeline, a research assistant could all be built on the same kernel. Same relationship as Linux and Ubuntu. The kernel is the seed. The extensions are the distribution.
A personal tree connected to Telegram. You text it thoughts throughout the day. It captures and places them into the right branch. Navigate to /Health/Food and say "ate chicken and rice." It parses macros, updates your running totals, tells you where you stand. Navigate to /Health/Fitness and say "bench 135x10,10,8." It records sets, tracks progressive overload, detects when you're ready for more weight. Different position, different AI.
A research community tree with branches per topic. Reddit comments arrive through a gateway channel and get placed into the right branch. The intelligence bundle works in the background. The tree compresses its own knowledge. It detects contradictions between branches. A digest goes out each morning via Telegram. The tree monitors what it knows, what it doesn't, and where the gaps are.
A company tree where each department is a branch. The AI at /Engineering has access to shell commands and code review tools. The AI at /Sales has CRM tools and email gateway. The AI at /Finance has transaction tracking and reporting. Same kernel. Same conversation loop. Different extensions activated at each position through spatial scoping.
A persistent AI that lives in a structure, accumulates context across every channel, knows itself, communicates internally through cascade signals, and connects to the outside world through gateways. Every extension reads from every other. The whole is more than the parts.
Run your own land (server):
npx create-treeos my-land cd my-land node boot.js
First boot walks you through setup: domain, name, LLM connection, extension selection. Any OpenAI-compatible endpoint works: Ollama, OpenRouter, Anthropic, local models.
Or connect to an existing land as a user:
npm install -g treeos treeos connect https://treeos.ai treeos register treeos start
Where you are determines what the AI can do. No mode switching menu. Navigation IS mode switching. cd / and the AI becomes a system operator. cd ~ and it becomes your personal assistant. cd MyTree and it works the tree with you.
/System management. Extensions, config, users, peers, diagnostics. Admin access required.
~Personal space. Raw ideas, notes, chat history, contributions. Organize and reflect.
/MyTreeChat reads and writes. Place adds content silently. Query reads only. Be lets the tree guide you. The orchestrator classifies intent.
You send a message. The orchestrator (itself an extension) classifies it. Is it about food? Fitness? A general question? It routes to the right extension's mode. The mode sets the AI's system prompt and available tools. The AI responds, calling tools as needed through MCP. One message can trigger multiple tool calls in a loop until the AI is done or hits the iteration cap.
Every prompt starts with a position block the AI can't skip. It always knows where it is: which tree, which node, which user.
[Position] User: tabor Tree: My Fitness (abc-123-def) Current node: Push Day (xyz-456-ghi) You are tabor's personal fitness coach... Current time: Friday, April 11, 2026, 7:42 AM EDT
Extensions inject context through the enrichContext hook. The food extension adds today's macros. The fitness extension adds the current program. The recovery extension adds sleep and energy. The AI reads all of it. It knows because extensions told it.
Five resolution chains determine what happens at every position: extension scope (what's active here), tool scope (what tools the AI has), mode resolution (which prompt fires), LLM resolution (which model runs), and LLM config (iteration limits, timeouts). All walk the same cached ancestor snapshot. One DB query serves all five.
The tree has a grammar. You speak naturally. The system parses.
Nodes are nouns. Bench Press. Protein. Chapter 3. They are things with identity, position, and relationships. They sit in the tree and hold meaning.
Extensions are verbs. Food tracks. Fitness logs. Recovery reflects. Study teaches. They are ways of being at a position. Install an extension and the tree gains a new capability, a new way to act on its nouns.
Routing is parsing. "Ate eggs" contains food nouns. "Bench 135" contains fitness nouns. The routing index is a vocabulary list: which nouns belong to which verb. It maps territory. This noun-space belongs to this verb.
Modes are conjugation. Once the territory is identified, the intent determines the tense:
Review (past tense) "how did I do" "my progress" Coach (future/subjunctive) "what should I" "help me" Plan (imperative) "build" "create" "add" Log (present tense) "ate eggs" "bench 135x10"
A message flows through three stages. What noun? The routing index identifies the territory (food, fitness, study). What tense? The suffix pattern identifies the conjugation (review, coach, plan, log). Dispatch. The right verb in the right tense handles the sentence.
The user speaks natural language. The tree parses it into noun + verb + tense. The node receives it. The extension acts on it. The mode thinks in the right frame. That is the grammar of TreeOS.
The system is a natural language computer. The seed is the parser. Extensions are the vocabulary. The tree is the syntax tree. The user just talks.
A folder with two files. A manifest declares what it needs and provides. An init function wires it in. Extensions give the AI new tools (what it can do), new knowledge (what it knows via enrichContext), and new behaviors (how it thinks via modes).
120 extensions ship with TreeOS. From a one-hook response formatter to a full conversation orchestrator that routes every message. From a nutrition tracker that parses "ate a banana" into protein, carbs, and fats to a gateway system that opens trees to Discord, Telegram, Slack, email, SMS, Reddit, and Matrix.
Spatial scoping controls where extensions are active. Block an extension at any node and it loses all power there and below. Tools disappear. Hooks stop firing. Modes don't resolve. Confined extensions (like shell, solana) are active nowhere until you explicitly allow them at a specific branch.
treeos ext-block shell # shell tools gone from here and below treeos ext-allow solana # solana tools activated at this branch only treeos ext-scope # see what's active at this position
Extensions communicate through three patterns: hooks (pub/sub events), exports (direct function calls via getExtension()), and metadata (shared state on nodes). They never import each other directly. The kernel is the bus.
The tree structure is not a database for an application. It IS the application. A food tree has a Log node where you talk, metric nodes that count protein, carbs, and fats, a Meals subtree that tracks patterns by slot, and a History node that archives daily summaries. A fitness tree has muscle groups, exercise nodes with sets and weight, a program node, and a history node. You say what you ate. One tool call parses and stores it. You say what you lifted. Same pattern.
Neither food nor fitness knows the other exists. But a channel between them carries data both ways. The fitness AI sees today's calories. The food AI sees today's workout. The tree connected them. Not the code. The structure.
Most things people build will be tree shapes, not extensions. Extensions add capabilities. Trees arrange them into applications. The distinction tells you when to write code and when to just build structure.
Four primitives. Structure: Node (12 fields) and User (7 fields) plus a metadata Map where extensions store everything. Intelligence: the conversation loop, LLM resolution, tool execution via MCP. Extensibility: the loader, 30 hooks, 5 registries (hooks, modes, orchestrators, socket handlers, auth strategies). Communication: cascade signals, .flow result storage, the response protocol.
Six system nodes at boot: Land Root, .identity (Ed25519 keys), .config (all runtime config), .peers (federation), .extensions (registry), .flow (cascade results in daily partitions).
Six rules, never violated: seed never imports from extensions, extensions import from seed, extensions reach each other through getExtension() or hooks, extension data lives in metadata Maps, seed schemas never change, zero getExtension() calls in seed.
An open pub/sub bus. Before hooks run sequentially and can cancel. After hooks run in parallel and react. Any hook name is valid. Extensions fire their own with extName:hookName convention.
beforeNote / afterNoteNote lifecyclebeforeNodeCreate / afterNodeCreateNode creationbeforeStatusChange / afterStatusChangeStatus changesbeforeNodeDeleteDeletion, cleanupbeforeContributionContribution data modificationenrichContextInject extension data into AI context (sequential)beforeLLMCall / afterLLMCallLLM API call lifecyclebeforeToolCall / afterToolCallMCP tool executionbeforeResponseModify AI response before clientbeforeRegister / afterRegisterUser registrationafterSessionCreate / afterSessionEndSession lifecycleafterNavigate / onNodeNavigateNavigation eventsafterNodeMoveNode reparentedafterMetadataWriteMetadata changesafterScopeChangeExtension scope changesafterOwnershipChangeOwnership changesafterBootPost-boot setuponCascadeCascade signal handler (sequential)onDocumentPressureDocument approaching size limitonTreeTripped / onTreeRevivedCircuit breaker eventsWhen content is written at a cascade-enabled node, the kernel fires onCascade. Extensions propagate signals to children, siblings, or remote lands. Every signal produces a visible result stored in .flow with daily partitions.
Two entry points. checkCascade fires automatically on content writes. deliverCascade is called by extensions to propagate externally. The kernel never blocks inbound signals. Always accepts. Always writes a result.
Six result statuses: succeeded, failed, rejected, queued, partial, awaiting. Results stored in daily partition nodes under .flow. This is how the food extension routes macros to metric nodes, how fitness routes workout data to exercise nodes, and how signals flow between trees across lands.
Technically an extension. Architecturally a primitive. Governing is the coordination substrate that any other extension can consume so it doesn't have to reinvent how plans get drafted, contracts get ratified, branches get dispatched, or failures get judged. Without governing, a tree is a folder structure. With it, every scope becomes an addressable domain where work coordinates across branches without drifting apart.
Governing composes in five layers. Rulership (Pass 1, shipped) defines five roles. Ruler decides and ratifies. Planner advises on decomposition. Contractor commits shared vocabulary. Foreman manages execution as a call stack. Worker produces artifacts at leaf scopes. Courts (Pass 2) will adjudicate disagreements. Reputation (Pass 3) will shape future routing from accumulated track record. Structural Remedies (Pass 4) will let Rulership intervene through quarantines, replacements, or decommissioning when something goes wrong. Economy (Pass 5) will route resources through coalitions and budgets.
The first four roles (Ruler, Planner, Contractor, Foreman) stay domain-neutral. The Worker is where workspace extensions specialize the substrate for their domain. code-workspace adds file editing tools and code validators on top of Worker. book-workspace adds chapter writing and prose validators. A future civilization extension would add civic action tools and community-norm validators. The other roles stay uniform.
Self-promotion at every depth. A node becomes a Ruler the moment it accepts authority for its domain. Three uniform call sites. A root node accepts authority when a user request arrives. A branch accepts authority when dispatched as a sub Ruler. A Worker accepts authority retroactively when it discovers its work is compound. Same lifecycle event, same metadata write, same architectural shape, root or ten levels deep. Authority distributes to where work happens rather than concentrating at the top.
LCA correctness on contracts. Every contract carries a scope (global, shared:[X,Y], or local:[X]). The Lowest Common Ancestor of a contract's named consumers must sit at or above the Contractor's emission position. Contracts that overreach are rejected at parse time. This is what keeps coordination boundaries honest as trees grow deep.
Governing pairs with swarm for parallel execution. Governing decides what gets done and ratifies the shared vocabulary. Swarm dispatches the branches in parallel, tracks status, reconciles with the tree, and resumes interrupted work. Mechanism and policy split cleanly.
Navigate trees like a filesystem. cd, ls, mkdir, rm, mv. Extension commands appear automatically based on what the connected land has installed.
treeos cd Life/Health/Fitness treeos chat "bench 135x10,10,8" treeos be # the tree guides you through your workout treeos note "Hit PR on squat today" treeos query "how's my progress this month" treeos tree # see the structure treeos ext-scope # see what's active here
The CLI is built for TreeOS. It is not part of the kernel. Anyone building on the seed can build their own CLI, frontend, or interface. TreeOS also has a web dashboard, server-rendered HTML pages, and a standalone chat interface.
Model-agnostic. Any OpenAI-compatible endpoint: Ollama, OpenRouter, Anthropic, local models, custom deployments. Each user has a default LLM connection. Tree owners can override per-tree. Extensions register additional LLM slots for per-mode assignments. API key is not required for local models like Ollama.
Resolution chain: extension slot on tree, tree default, extension slot on user, user default. First match wins. Failover on errors. Priority queue ensures human sessions run before background jobs.
treeos llm add # add a connection (Ollama, OpenRouter, etc) treeos llm assign # assign to a specific tree or mode
Lands connect through the Canopy protocol. Each land is sovereign. Your data stays on your server. Remote users are ghost records (username + home land URL). The real user data never leaves their home land.
Peers discover each other through the Horizon or by direct peering. The Horizon is discovery, not authority. Remove it and peering still works. Messages are signed with Ed25519 keys. Cascade signals flow between lands. A tree on Land A writes content. An extension propagates to Land B via Canopy. Land B accepts it, fires onCascade, writes to .flow.
Extensions group into bundles. Install a bundle and the loader resolves everything. Remove one extension and the rest keep working.
Core experience. Orchestrator, navigation, dashboard, notifications, console, HTML rendering, team, channels, heartbeat, purpose, phase, remember, breath.
The nervous system. Signal propagation, perspective filtering, sealed transport, codebook compression, gap detection, long memory, pulse monitoring, flow visualization.
Self-awareness. Context compression, contradiction detection, user modeling, evolution tracking, semantic search, boundary detection, competence tracking, reflection, autonomous intent.
External channels. Gateway core plus Discord, Telegram, Slack, email, SMS, Matrix, Reddit, X, webhooks, tree-to-tree.
Hygiene. Pruning, rerooting, changelog, daily digest, work delegation.
Persona, mycelium, peer-review, seed-export, governance, teach, split, approve.
treeos ext install treeos-cascade # install a bundle treeos ext install persona # install standalone treeos ext publish my-extension # publish your own
Three terms that get conflated. They are not the same.
The seed is the kernel. Two schemas, a conversation loop, hooks, registries, a cascade engine, and an extension loader. It boots with zero extensions and still works. Everything else builds on it. The seed never changes per install. It is the contract.
TreeOS is the first operating system built on the seed. It is a bundle of around 100 extensions that ship together. Governance, mycelium, cascade, intelligence, connect, maintenance, the proficiency apps. Most of what this guide describes lives in TreeOS. It is the reference implementation and a good starting point. Run the setup wizard with the recommended profile and you are running TreeOS. You can strip it down to a minimal land, install only the extensions you want, fork it entirely, or build a different OS on the same kernel. TreeOS is a choice, not the substrate.
A land is a running server. A Node.js process with the seed loaded, a database connected, an LLM wired in, and whatever extensions the operator chose to install. Every land boots from the seed. Most lands run TreeOS by default, but a land could run an entirely different extension set. A land is the deployment. TreeOS is the bundle most lands deploy. The seed is what every land has in common no matter what bundle they run.
When this guide names a feature like governance or mycelium or cascade, those are TreeOS extensions. When it talks about hooks, schemas, the conversation loop, or registries, those are seed primitives. A land is wherever both end up running together.
Every tunable value lives in the .config system node. Readable and writable via CLI, API, or the land-manager AI. No code editing. No restarts for most values. 100+ config keys covering LLM, conversation, sessions, notes, cascade, uploads, circuit breakers, and more.
treeos config set maxToolIterations 25 treeos config set llmTimeout 900 treeos config set cascadeEnabled true treeos config set treeCircuitEnabled true
The tree is multi-agent. Multiple users, sessions, background jobs, gateway channels, cascade signals. Reads are fully concurrent. Scoped writes (metadata per namespace) are concurrent across namespaces. Structural mutations (create, move, delete) use sorted node locks with 30s TTL.
The kernel protects itself: hook circuit breakers auto-disable failing handlers, tool circuit breakers disable broken tools per session, tree circuit breakers trip unhealthy trees. Document size guards prevent runaway metadata. Ancestor caches prevent N+1 queries. LLM priority queues ensure humans run before background jobs.
Create a folder in extensions/. Add manifest.js and index.js. Restart. Your extension loads.
// manifest.js
export default {
name: "my-ext",
version: "1.0.0",
needs: { models: ["Node"], services: ["hooks", "protocol"] },
provides: { cli: [{ command: "my-cmd", description: "Does a thing" }] },
};
// index.js
export async function init(core) {
core.hooks.register("afterNote", async (data) => {
// react to notes being written
}, "my-ext");
return {
router, // HTTP routes at /api/v1
tools: [...], // MCP tools for the AI
exports: { ... }, // for other extensions
};
}Store data in node.metadata under your extension name via setExtMeta. An operating system is just extensions working together. The seed grows whatever you plant.
REST at /api/v1/. Bearer token or API key auth. Every tree operation, note, value, and AI interaction is accessible via HTTP. The protocol endpoint at /api/v1/protocol returns loaded extensions, capabilities, and CLI commands.
Response shape: { status: "ok", data } or { status: "error", error: { code, message } }. Semantic error codes (NODE_NOT_FOUND, UNAUTHORIZED, DOCUMENT_SIZE_EXCEEDED, etc.) that mean something.
The seed is AGPL-3.0. Run it, modify it, build on it. If you modify the seed and run it as a service, share your seed modifications. Extensions are separate works that interact through the defined API. Extension authors choose their own license. The seed license does not infect extensions.
The tree exists in time. Three extensions operate at different frequencies. Stack all three and you get the tree's complete waveform.
Detects awareness vs attention in conversation. The AI adjusts its approach in real time.
Activity-driven metabolism. Fast when active. Slow when quiet. Stops when dormant. Extensions listen to exhale instead of running their own timers.
Growth, peak, hardening, dormancy. Each ring records who the tree was during that period. The tree remembers every age.
The kernel provides one primitive: onCascade. Three layers emerge from extensions using it at different scales.
Local to one land. Cascade results pool in daily partitions. Trees pull what they need through perspective filters. The land's groundwater.
Direct land-to-land peering. Ed25519 signed. Intentional. deliverCascade sends signals across lands. The remote kernel accepts, fires onCascade, writes to .flow.
An extension any land installs to become a routing node. Reads signal metadata, evaluates what each connected land needs, delivers where useful. The forest's nervous system between roots.
The kernel does not know about fitness, food, wallets, blogs, scripts, energy budgets, dream cycles, or gateway channels. It does not render HTML. It does not meter usage. It does not schedule tasks. It does not propagate signals.
It provides structure, intelligence, extensibility, and communication. Extensions provide meaning. The kernel is 12 fields on a node, 7 fields on a user, a conversation loop, 30 hooks, 5 registries, a cascade engine, and a response protocol. Everything else is an extension someone built.
The seed is small so the tree can be anything.
Advanced operators can adjust these values via treeos config set. Most lands never need to. Defaults are safe.
socketMaxBufferSize1048576Max WS message size (bytes)socketPingTimeout30000WS ping timeout (ms)socketPingInterval25000WS ping interval (ms)socketConnectTimeout10000WS connection timeout (ms)maxConnectionsPerIp20Per-IP WS connection capllmClientCacheTtl300User LLM client cache lifetime (seconds)canopyProxyCacheTtl60Canopy proxy client cache lifetime (seconds)apiOrchestrationTimeout1140000API request timeout (ms)canopyHeartbeatInterval300000Heartbeat frequency (ms)canopyDegradedThreshold2Failed heartbeats before degradedcanopyUnreachableThreshold12Failed heartbeats before unreachablecanopyDeadThresholdDays30Days before dead peer cleanupcanopyOutboxInterval60000Outbox processing frequency (ms)canopyMaxRetries5Event delivery retriescanopyEventDeliveryTimeout15000Per-event delivery timeout (ms)canopyDestLimitPerCycle10Events per destination per cycleorchestratorLockTtlMs1800000Lock TTL before auto-expire (ms)lockSweepInterval300000Lock cleanup sweep (ms)uploadCleanupInterval21600000Upload cleanup frequency (ms)uploadGracePeriodMs3600000File age before deletion (ms)uploadCleanupBatchSize1000Max files deleted per cleanup cycleretentionCleanupInterval86400000Retention job frequency (ms)cascadeCleanupInterval21600000Cascade result cleanup frequency (ms)dnsLookupTimeout5000DNS resolution timeout for custom LLM URLs (ms)mcpConnectTimeout10000MCP client connection timeout (ms)mcpStaleTimeout3600000MCP client idle timeout before sweep (ms)orchestratorInitTimeout30000Background pipeline init timeout (ms)hookTimeoutMs5000Per-hook handler timeout (ms)hookMaxHandlers100Max handlers per hook namehookCircuitThreshold5Consecutive failures before hook auto-disablehookCircuitHalfOpenMs300000Tripped handler recovery test delay (ms)hookChainTimeoutMs15000Cumulative timeout for sequential hook chains (ms)ancestorCacheMaxEntries50000Max cached ancestor chainsancestorCacheMaxDepth100Parent chain depth limitmaxContributorsPerNode500Max contributors per nodemetadataMaxNestingDepth5Max metadata nesting depthmcpConnectRetries2MCP reconnect attempts for pipelinescontributionQueryLimit5000Max contribution docs per querynoteQueryLimit5000Max notes per querynoteSearchLimit500Max notes per searchsubtreeNodeCap10000Max nodes in subtree traversalcircuitFlowScanLimit5000Max cascade results scanned per health checktreeAncestorDepth50Max ancestors in context buildtreeContributionsPerNode500Max contributions per node in contexttreeNotesPerNode100Max notes per node in contexttreeMaxChildrenResolve200Max children resolved per nodetreeAllDataDepth20Max depth for getAllNodeDatametadataNamespaceMaxBytes524288Per-namespace metadata cap in bytes