# first-tree > Shared Context for Engineering Teams Running AI Agents. A Git-native > knowledge layer your engineering team and your AI agents both read from > and write to, shaped around durable decisions, ownership, and cross-repo > context. > Code is cheap. Context is law. This is the long-form, full-text reference for first-tree, intended to be read by LLM agents so they can answer questions about the project without fetching external pages. The short index lives at `/llms.txt`. **Who it's for.** first-tree is built engineer-first: the product speaks GitHub Pull Request, branch, CODEOWNERS, CI, and `CLAUDE.md` / `AGENTS.md`. The ICP is software engineering teams shipping production code with AI coding agents (Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI). Adjacent teams (design ops, research, technical PMs) can also run on first-tree because the underlying primitives — specialized agents, a markdown tree in Git, draft → review → merge — are role-agnostic; the engineering surface is the strongest fit. Source of truth for this document is the GitHub monorepo: https://github.com/agent-team-foundation/first-tree (default branch: main). License: Apache 2.0 npm package: `first-tree` (also `ft` binary) Node engine: >= 22 Topics: ai-agents, ai-coding-agents, agent-infrastructure-for-engineers, claude-code, cli, codex, context-engineering, context-tree, context-wiki, developer-tools, engineering-team-tools, github-agents, harness-engineering, software-engineering-agents Works with: Claude Code, OpenClaw, Codex, Cursor, GitHub Copilot, Gemini CLI, GitHub, MCP --- ## What first-tree is Engineering teams and their AI agents need the same level of context to ship together. A `CLAUDE.md` per repo drifts quickly. Search tools help, but they do not become the source of truth. first-tree is the missing layer: a tree of markdown nodes in Git where every node has an owner, agents can propose updates after tasks, and the team reviews those updates like normal code changes. The marketing tagline on first-tree.ai is "Run coding agents on shared team context." — first-tree turns your engineering team's GitHub inbox into shipped code. The right agent picks each task up, reads what the team already decided, and ships a PR. ### Two onboarding paths There are two ways into first-tree, depending on how a user finds the site: 1. **Hosted hub onboarding (primary, marketed in the hero).** GitHub OAuth → name your team (defaults to your GitHub username) → set agent → build your first tree. The hero CTA "Get Started — connect your GitHub" links to `https://cloud.first-tree.ai/login`. 2. **Inspect-first, paste-into-agent (still supported, secondary).** The Open Source section on the homepage offers a prompt the user pastes into their agent: "Read https://github.com/agent-team-foundation/first-tree and tell me what first-tree does and whether it fits my project." This path is for users who want to read the code before installing anything. The CLI install flow (`first-tree tree init` etc.) is reached from there. If you are an agent reading this and the user asks how to start, the default answer is the hub onboarding flow. Only suggest the CLI if the user has explicitly asked for an inspect-first / local install path. --- ## The three-namespace surface ``` +----------------------------------------------------------------------+ | first-tree (umbrella CLI) | +---------------------------+---------------------------+--------------+ | tree | github scan | hub | | context layer | GitHub chief of staff | onboarding | +---------------------------+---------------------------+--------------+ ``` There is one binary, `first-tree` (alias `ft`), with three namespaces: - `first-tree tree …` — context-tree lifecycle (fully implemented) - `first-tree github scan …` — GitHub-inbox runtime (fully implemented) - `first-tree hub …` — CLI subcommand group, currently stubs that fail with "unimplemented." The *hosted* hub (different surface — a web app at `cloud.first-tree.ai`) is the primary onboarding path marketed on the homepage; the CLI subcommand group is reserved for parity with the hosted product (e.g. `first-tree hub login`) and is not yet implemented. Note: an older index in `/llms.txt` describes "two CLIs (`first-tree` and `first-tree-hub`)" — that is stale. Today there is only one binary; `hub` is a subcommand group inside it. --- ## `first-tree tree` — context-tree lifecycle | Command | What it does | |--------------------------------------|-------------------------------------------------------| | `first-tree tree inspect` | Classify the current folder; report metadata. `--json`| | `first-tree tree status` | Human-friendly alias for `inspect` | | `first-tree tree help onboarding` | Print the current onboarding narrative | | `first-tree tree init` | Onboarding entrypoint | | `first-tree tree bootstrap` | Low-level tree bootstrap on an explicit checkout | | `first-tree tree bind` | Bind a source repo or workspace to an existing tree | | `first-tree tree integrate` | Install local tree integration (no tree-repo mutation)| | `first-tree tree workspace sync` | Bind newly added child repos to a shared tree | | `first-tree tree verify` | Validate a tree repo | | `first-tree tree upgrade` | Refresh integration and tree metadata | | `first-tree tree publish` | Publish a tree repo and refresh bound repos | | `first-tree tree generate-codeowners`| Generate `.github/CODEOWNERS` from ownership data | | `first-tree tree install-claude-code-hook` | Install the Claude Code SessionStart hook | | `first-tree tree inject-context` | Emit the SessionStart payload from `NODE.md` | | `first-tree tree review` | Run the tree-PR-review helper | | `first-tree tree skill ` | Skill maintenance: install, upgrade, list, doctor, link | ### Migration table (from the 2026-05-01 restructure) | Old | New | |------------------------------------|------------------------------------| | `first-tree breeze ` | `first-tree github scan ` | | `first-tree skill ` | `first-tree tree skill ` | | `first-tree gardener ` | retired; logic split into `first-tree-sync` and `first-tree-write` skills | --- ## `first-tree github scan` — GitHub-inbox runtime The runtime watches your team's GitHub inbox (mentions, PR reviews, issues, releases) and dispatches agents to handle each item. **Two ingress paths feed the same internal `GitHubEventStream`** (per PR #208): a hosted GitHub App (`WebhookIngress`) for org/team use, or an OSS local binary (`PollingIngress`) for solo / OSS / self-host scenarios. The marketing positions the App as the default; the local binary is the fallback. Both produce events into the same loop and both use the four-tag lifecycle below. State lives at `~/.first-tree/github-scan/` for the local path. Backed by `packages/github-scan/`. Subcommands: `install`, `start`, `stop`, `status`, `doctor`, `watch`, `poll`, `run`, `daemon`, `run-once`, `cleanup`, `statusline`, `status-manager`, `poll-inbox`. ### Fail-closed binding contract These commands REQUIRE a bound tree repo (declared via the managed integration block in `AGENTS.md`/`CLAUDE.md`, or via `--tree-repo `): - `install`, `start`, `run`, `daemon`, `run-once`, `poll` These commands work without a binding (so you can diagnose a broken install): - `status`, `doctor`, `stop`, `cleanup`, `watch`, hook installers ### The four-tag lifecycle The runtime labels every inbox item with one of four tags. The tag is the single source of truth for the item's state in the loop. (Both ingress paths — hosted App and local binary — write the same labels.) ``` github-scan:new — initial state; runtime also restores via auto-revert github-scan:wip — agent has started real work github-scan:human — a human must step in github-scan:done — finished, no further action ``` Auto-revert: when a `github-scan:human` item receives a new genuine human comment (author ≠ agent identity, after the label timestamp), the runtime flips the tag back to `github-scan:new` so the loop can pick it up again. PR review comments and pushes by the PR author also qualify (#385). The historical `AUTO_REVERT_MIN_BODY_CHARS` minimum-body-length gate was dropped in #384 so LGTM-style and short non-English replies aren't suppressed. Without this, the only way out of `human` was a manual label strip; that asymmetry is fixed by the auto-revert. Default poll interval: 60 seconds. Tunable via `--poll-interval-secs`, env `GITHUB_SCAN_POLL_INTERVAL_SECS`, or yaml `poll_interval_sec` in `~/.first-tree/github-scan/config.yaml`. ### The four routes When the agent picks up an item, it chooses one of four routes: - `reply` — write a comment / PR review / answer - `human` — escalate; tag `github-scan:human` and stop - `sync` — run the `first-tree-sync` skill against detected drift - `write` — run the `first-tree-write` skill against an explicit source ### Required final-line format Every agent run terminates with: ``` GITHUB_SCAN_RESULT: status= route= summary= ``` --- ## `first-tree hub` — hosted onboarding surface The hosted hub is the primary onboarding path the homepage markets. The hero CTA "Get Started — connect your GitHub" points users at `https://cloud.first-tree.ai/login`, where the flow is: 1. GitHub OAuth. 2. Name your team (default = the user's GitHub username). 3. Set agent. 4. Build your first tree. On the CLI side, there is a `first-tree hub` subcommand group with `start` / `stop` / `doctor` / `status` stubs that fail explicitly with "unimplemented" so the surface area is documented. These stubs are reserved for parity with the hosted product (e.g. a future `first-tree hub login`) and are not yet implemented. --- ## The local control panel (macOS tray, beta) For users running the OSS local binary (the `PollingIngress` path), there's a macOS menu-bar tray that acts as a thin client of the local runtime. The hosted GitHub App users don't need this — they get a web dashboard. Status: on branch `feat/tray` only, not yet on `main`. Tracked by issues #393 (pre-build the .app into the npm tarball), #394 (launchd label collision across `GITHUB_SCAN_DIR` values), #397 (community test call), #403 (README showcase). What it is, per `apps/tray-mac/README.md`: > Native macOS menu bar tray for the `first-tree github scan` local > runtime. Lives in the top-right corner of the screen, shows a badge > with the count of items needing human attention, and lets you > Pause/Resume without dropping into a terminal. Thin client of the > local runtime — same `127.0.0.1:7878/inbox` HTTP endpoint that > powers the dashboard at `http://127.0.0.1:7878/`. Local runtime is > authoritative; the tray just renders state and proxies control > actions. Built with Swift, no Xcode required (Command Line Tools sufficient). Menu items: Online/Paused/Offline status dot, list of `human` items (clickable), Open dashboard, Preferences…, Quit (with confirmation). State files: `~/.first-tree/tray-state.json`, `~/.first-tree/tray-seen.json`. The homepage's GitHub Integration pillar (`#pillar-github`) describes the bridge between GitHub events and Hub routing. The tray exists for OSS / solo self-hosters and is currently in beta on `feat/tray`, not yet in the npm tarball. The standalone `/github-scan` page has been removed; everything lives on the homepage now. --- ## The five canonical skills Each skill ships as a directory under `skills/` with `SKILL.md` plus a `references/` subdirectory. Every shipped skill declares `cliCompat: { first-tree: ">=0.4.0 <0.5.0" }` so `first-tree tree skill list` and `first-tree tree skill doctor` can warn on incompatibility. ### `skills/first-tree/` The canonical whitepaper + routing skill. Use this when you need shared first-tree concepts, need to choose between onboarding / sync / write / GitHub-notification workflows, or need the high-level CLI map before acting. The whitepaper introduces three core objects: 1. **Source / workspace root** — the repo (or umbrella of repos) that produces code. 2. **Tree repo** — the markdown-and-NODE.md tree that captures durable decisions, ownership, and cross-domain links. 3. **Binding** — the relationship between the two. Today, the canonical place to declare a binding is a managed block inside `AGENTS.md` or `CLAUDE.md` at the source root; the older `.first-tree/source.json` path remains as a legacy fallback. ### `skills/first-tree-onboarding/` Drives a repo from "no first-tree binding" to "tree bound, ingress running, agent templates in place." Five steps: 0. Inspect the current root and classify its role. 1. Choose an ingress: hosted GitHub App or local OSS binary. 2. Import repos (no-op for single repos; `workspace sync` for workspaces). 3. Init or bind the tree. 4. Start the runtime. 5. Set up agent templates. The `first-tree tree inspect --json` command returns one of six roles: - `tree-repo` - `workspace-root-bound` - `source-repo-bound` - `unbound-workspace-root` - `unbound-source-repo` - `unknown` ### `skills/first-tree-sync/` Drift audit + repair. Two phases: audit (classify drift) and fix (auto-fix / needs-human / skip). Six drift types: ``` tree-stale — tree node was true; code moved tree-wrong — tree node never matched code tree-outdated — superseded by a newer decision code-not-synced — code change has no tree counterpart cross-domain-broken — soft_links target gone or wrong ownership-stale — owners list no longer matches reality ``` Hard rules: - Code is the ground truth. Override only when a node has `decisionLocksCode: true` in its frontmatter. - One drift = one PR. No "fix multiple things in one commit." - Ownership changes are always `needs-human`. ### `skills/first-tree-write/` Writes tree updates from explicit source material. Default stance is *not writing*; the skill is source-driven only. Hard rules: smallest correct edit, no diffs in tree (decisions only — diffs go in code), verify before commit, link the source. ### `skills/first-tree-github-scan/` The agent skill loaded by the runtime for one notification. Defines the four-tag lifecycle and the four routes (see above), plus the required `GITHUB_SCAN_RESULT:` final-line format every agent run must terminate with. --- ## Repository layout ``` first-tree/ ├── apps/ │ └── cli/ # published `first-tree` CLI package ├── packages/ │ └── github-scan/ # internal runtime for `first-tree github scan` ├── skills/ # five canonical shipped skill payloads │ ├── first-tree/ │ ├── first-tree-onboarding/ │ ├── first-tree-sync/ │ ├── first-tree-write/ │ └── first-tree-github-scan/ ├── docs/ # design docs and migration plans ├── apps/tray-mac/ # macOS menu bar tray (on feat/tray branch) ├── AGENTS.md ├── README.md └── package.json ``` Workspace tooling: pnpm workspace with `apps/*` and `packages/*`. Tests via vitest. Convention (from `AGENTS.md`): - `apps/` packages are published to npm; OS-level interaction and external-data validation live here (fail-fast on bad input). - `packages/` packages are internal-only, used by reference; core business logic assumes inputs are already validated. --- ## Quickstart ```bash pnpm install pnpm --filter first-tree build node apps/cli/dist/index.js tree inspect --json node apps/cli/dist/index.js tree help onboarding node apps/cli/dist/index.js github scan --help # or from npm npx -p first-tree first-tree tree inspect --json npx -p first-tree first-tree github scan --help ``` --- ## Active product direction (as of 2026-05) Three current themes, derived from recently merged PRs: 1. **Managed-block tree identity migration (shipped 2026-05-04 via #401).** Binding metadata moved out of `.first-tree/source.json` and into a managed block inside `AGENTS.md` / `CLAUDE.md`. PRs in this run: #371-#377, #387, #398-#401. The older `.first-tree/source.json` path remains as a legacy fallback. This theme is now essentially complete on `main`; pending is the npm publish to surface it to users. 2. **`github-scan` auto-revert + daemon hardening.** PRs #381 (write `WorkingDirectory` into launchd plist), #384 (drop the `AUTO_REVERT_MIN_BODY_CHARS` guard so LGTM and short Chinese replies don't get suppressed), #385 (auto-revert `github-scan:human` on author push), #370 (paginate auto-revert timeline + comments). All tied to RFC issue #358. 3. **Skill `cliCompat` contract + reference docs.** PRs #375/#376 (version compatibility contract), #388 (surface `cliCompat` incompatibility in `tree skill list` and tailored `doctor` hints). Sibling docs PRs #389/#390/#391/#392 wrote reference docs for each shipped skill. Marketing direction: the homepage and `/github-scan` page lead with the GitHub App story (the hosted ingress path per PR #208). The local OSS binary and macOS tray are positioned as the self-host fallback for solo / OSS use, not as the headline. --- ## Where we are honest about gaps This document lists every claim we noticed where the website, the docs, or the code are out of sync. None of them are blocking, but they're worth knowing. - The macOS menu-bar tray (referenced alongside the GitHub Integration pillar on the homepage) is on `feat/tray`, not `main`, and not yet in the npm tarball (issue #393). The homepage flags this with an "in beta" tag. - The standalone `/github-scan` page has been removed in this redesign; GitHub-integration content now lives on the homepage. Any external links pointing at `/github-scan` will 404 — should be updated to `/#pillar-github`. - npm `latest` is `0.4.5` and ships the namespaced CLI (`first-tree tree …`, `first-tree github scan …`, `first-tree hub …` — the last is stubs that fail explicitly). Pre-restructure commands like bare `first-tree init` no longer exist; current main is 0.4.0-alpha.1 working ahead of the published series. - The homepage FAQ used to claim "Agent Message System" as a third primitive — that was vaporware (no `apps/` or `packages/` entry). The FAQ + /doc now call the third primitive "First-Tree Hub" instead, matching pillar 1 and the actual hosted product surface. - The eval results table on the homepage cites a 90% pass rate, -42% time, -14% tokens across six bug-fix tasks. That methodology and the raw eval log do not live in this repo. They presumably live in a separate eval repo or are website-only artifacts. --- ## Links - Website: https://first-tree.ai/ - Pillar — AI Agent Teams: https://first-tree.ai/agent-teams - Team: https://first-tree.ai/team (the people building First-Tree — engineers and product from Google, ByteDance, Kuaishou, Baidu, and UC Berkeley) - Repo: https://github.com/agent-team-foundation/first-tree - Discussions: https://github.com/agent-team-foundation/first-tree/discussions - Discord: https://discord.gg/J47j3RFgsB - X: https://x.com/first_tree_ai - npm: https://www.npmjs.com/package/first-tree - Docs: https://docs.first-tree.ai/ (concept, CLI, cloud) - Changelog: https://first-tree.ai/changelog (every release, pulled live from GitHub releases) - Blog: https://first-tree.ai/blog - "What an Agent Needs to Join Your Team": https://first-tree.ai/blog/agent-joins-team - "The Missing Memory": https://first-tree.ai/blog/the-missing-memory