← first-tree.ai

First Tree

Shared context for agent teams. A tree-structured knowledge substrate that gives AI agent teams persistent, owned, versioned context. Works with Claude Code, Codex, OpenClaw, and any agent.

Quick Start

Paste this into your agent (Claude Code, Codex, or any coding agent):

The agent will:

1. Install the first-tree skill from the first-tree repo
2. Run first-tree init to scaffold the framework
3. Read the onboarding guide and task list
4. Analyze your codebase to populate domains, owners, and members
5. Run first-tree verify to confirm everything passes

What is a Context Tree?

A Context Tree is a Git repository where every directory is a domain and every file is a node. Each node captures decisions, designs, and cross-domain relationships — the knowledge that would otherwise scatter across PRs, documents, and people's heads.

• Nodes are markdown files. Each directory has a NODE.md that describes the domain. Leaf .md files capture specific decisions or designs.
• Every node has an owner. Declared in YAML frontmatter. Owners approve changes to their nodes.
• Organized by concern, not by repo or team. An agent working on "add SSO" finds all auth context in one place — not split across 4 repos.
• The tree is never a snapshot — it's the current state. When decisions change, the tree updates. Stale nodes are bugs.

What Belongs in the Tree

Information an agent needs to decide on an approach — not to execute it.

Yes: "Auth spans 4 repos: backend issues JWTs, frontend uses Better Auth, extension uses OAuth popup, desktop uses localhost callback."

No: The function signature of auth_service.verify() — that's in the code.

Four Principles

1. Source of truth for decisions, not execution. The tree captures the what and why. Execution details stay in source systems.
2. Agents are first-class participants. The tree is designed for agents to navigate and update.
3. Transparency by default. Reading is open to all. Writing requires owner approval.
4. Git-native. Nodes are files, domains are directories. History, ownership, and review follow Git conventions.

Tree Structure

my-org-tree/
├── NODE.md              # root — lists all domains
├── engineering/
│   └── NODE.md          # decisions about architecture, infra, tooling
├── product/
│   └── NODE.md          # strategy, roadmap, user research
├── marketing/
│   └── NODE.md          # positioning, campaigns
└── members/
    ├── NODE.md          # team members and agents
    ├── alice/
    │   └── NODE.md      # individual member node
    └── agent-a/
        └── NODE.md      # AI agent member node

Frontmatter Format

---
title: "Auth Architecture"
owners: [alice, bob]
soft_links: [/infrastructure/deployments]
---

Field	Required	Description
title	Yes	Display name for the node
owners	Yes	Who can approve changes. [] inherits from parent. [*] means anyone.
soft_links	No	Cross-references to related nodes in other domains
type	Members only	human, personal_assistant, or autonomous_agent
role	Members only	Role in the organization (e.g., "Engineer", "Growth")
domains	Members only	Broad areas of responsibility

Three Primitives

1. Context Tree

A Git repo of .md nodes. Org memory that any agent reads before acting. Structure is the interface — no APIs, no schemas, no infra.

2. Git Automation

GitHub is the hub. PRs, issues, CODEOWNERS — all driven by tree ownership. Agents triage at scale, merge what's ready, reject what doesn't belong.

3. Agent Message System

Inbox-based agent-to-agent communication. Messages are .md files in the tree. Owned, versioned, and auditable. No separate broker, no event queue, no extra infra.

CLI Reference

The npm package is first-tree. Use npx first-tree for one-off runs, or npm install -g first-tree to add the first-tree command to your PATH.

Command	Description
first-tree init	Bootstrap a new tree. Creates NODE.md, AGENTS.md, CLAUDE.md, and members/NODE.md. Generates task list in .first-tree/progress.md.
first-tree verify	Check progress for unchecked items + run deterministic validation (valid frontmatter, node structure, member nodes exist).
first-tree upgrade	Compare local framework version to upstream, generate upgrade task list.
first-tree publish	Push tree repo to GitHub. Creates the remote if needed.
first-tree generate-codeowners	Generate .github/CODEOWNERS from tree ownership frontmatter.
first-tree help onboarding	Print the full onboarding guide.

Onboarding Steps

1. Initialize: mkdir my-tree && cd my-tree && git init && first-tree init
2. Work through tasks: Read .first-tree/progress.md — it contains a checklist tailored to your repo.
3. Fill in NODE.md: Organization name, owners, and domains.
4. Add members: Create member nodes under members/ from git history and CODEOWNERS. Use --seed-members contributors to auto-draft from git history.
5. Design domains: Create top-level directories for your organization's primary concerns.
6. Populate: Extract knowledge from existing repos, docs, and systems into the tree.
7. Verify: first-tree verify — confirms all checks pass.

Or just paste the quick start prompt into your agent — it does all of this automatically.

Links