Everything you need to know. Simple to advanced.
TreeOS is an open source operating system for AI agents. You run a server (called a land), and AI lives there permanently. It builds and navigates tree-structured knowledge. It remembers. It grows. It connects to other lands through a federated network.
The core is minimal: nodes, notes, types, status, and an AI conversation loop. Everything else (values, schedules, scripts, wallets, versioning) is an extension you install from the registry. The system adapts to what you need.
A node has a name, a type, a status, children, and a metadata map. That is it. Notes (text or files) attach to nodes. Types (goal, plan, task, knowledge, resource, identity) tell agents what they are looking at. Status (active, completed, trimmed) tracks lifecycle. Custom types are valid.
A tree is a root node with children. A land hosts trees, runs AI, and serves the API. A user has a username, password, one default LLM connection, and a metadata map for extension data.
The kernel provides: the node/user/note/contribution models, the WebSocket server, the MCP-based AI conversation loop, the hook system, the mode registry, the orchestrator registry, and the extension loader. If you strip every extension, the kernel still boots.
Where you are determines what the AI can do. There is no mode switching menu. Navigation is mode switching. cd / puts you in land management.cd ~ puts you in personal home. cd MyTree puts you in tree mode. The AI's tools, context, and behavior change automatically.
Land (/): The root. Manage extensions, config, users, peers. The AI becomes a land operator with system-level tools. Install packages, read system nodes, run diagnostics. Requires god-tier access.
Home (~): Your personal space. Raw ideas, notes across all trees, chat history, contributions. The AI helps you organize and reflect.
Tree (/MyTree): Inside a tree. Three strict behavioral contracts apply:
How tree mode works internally (the orchestrator, classifier, placement strategy) is an extension. The built-in tree-orchestrator handles it. Replace it with your own.
Each tree can customize what tools the AI has access to. Set metadata.tools.allowed on the root node to add tools (like shell access for a DevOps tree) or metadata.tools.blocked to remove them (like blocking deletes on a reference tree). Three layers merge: mode base tools, extension tools, tree config.
An extension is a folder with a manifest.js and an index.js. The manifest declares what it needs and what it provides. The index exports an init(core) function that receives the core services bundle.
An extension can provide: HTTP routes, MCP tools, AI conversation modes, a custom orchestrator, background jobs, lifecycle hooks, CLI commands, Mongoose models, energy metering, session types, LLM assignment slots, and environment variable declarations.
Extension data lives in metadata (a Map on every node and user). Each extension gets a namespace key matching its name. The kernel never reads extension data directly. Extensions use hooks to inject their data into AI context.
Install from the registry: treeos ext install understanding. Disable: treeos ext disable understanding. Build your own: create a folder in extensions/ with a manifest.
Eight lifecycle hooks let extensions modify or react to core operations without touching core code. Register during init(core).
beforeNote / afterNote . tag version, flag dirtybeforeContribution . tag nodeVersion in audit logafterNodeCreate . initialize extension databeforeStatusChange / afterStatusChange . validate, reactbeforeNodeDelete . cleanupenrichContext . inject extension data into AI contextBefore hooks can cancel operations. After hooks run in parallel. enrichContext runs sequentially. All handlers have a 5 second timeout.
Every user has one default LLM connection (llmDefault). Set during registration or via treeos llm add. This is the model that powers all AI modes for that user across all trees.
Tree owners can set a tree-level default (llmDefault on the root node) that overrides the user default for anyone working in that tree.
Extensions register additional LLM slots in metadata. The resolution chain: extension slot on tree, then tree default, then extension slot on user, then user default.
TreeOS is model-agnostic. Any OpenAI-compatible endpoint works (Ollama, vLLM, OpenRouter, Anthropic, OpenAI, local models).
The CLI works like a regular terminal. cd, ls, mkdir, rm, mv. Navigate trees like a filesystem. Add notes with note. Chat with chat.
Extension commands appear automatically. If the connected land has the solana extension, wallet shows up in help. If it does not, the command does not exist.
npm install -g treeos treeos connect https://treeos.ai treeos register treeos start
Lands connect through the Canopy protocol. Each land is sovereign. No central authority. Peer with other lands, browse their public trees, invite their users to collaborate on yours.
The directory service at dir.treeos.ai indexes lands, public trees, and the extension registry. It is optional. Lands can peer directly without it.
Lands advertise their loaded extensions. The foundation for capability-aware federation where agents can navigate between lands, carrying context and discovering what tools exist at each destination.
A land is a Node.js server with MongoDB. First boot walks you through setup: domain, name, extension selection from the registry.
git clone https://github.com/Tabors-Site/Tree && cd Tree npm run install:all npm land
Or connect to an existing land as a user:
treeos connect https://treeos.ai treeos register
Create a folder in extensions/. Add manifest.js and index.js. Restart. Your extension loads.
The manifest declares dependencies (models, services, other extensions) and what you provide (routes, tools, modes, orchestrator, hooks, jobs, CLI commands). The init(core) function receives only the services you declared.
Store data in node.metadata or user.metadata under your extension name. Use hooks to inject into AI context. Use the orchestrator registry to replace the conversation flow. Publish to the registry for others.
REST API at /api/v1/. Bearer token or API key auth. Every tree operation, note, value, and AI mode is accessible via HTTP. The /api/v1/protocol endpoint returns the land's capabilities, loaded extensions, and available CLI commands.