# first-tree

> Shared Context for Agent Teams. A Git-native knowledge layer your team
> and your 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`.

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, claude-code, cli, codex, context-engineering,
context-tree, context-wiki, harness-engineering
Works with: Claude Code, OpenClaw, Codex, Cursor, Gemini CLI, GitHub, MCP

---

## What first-tree is

Humans and 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 "Your agent team, shipping." —
first-tree turns your team's GitHub inbox into shipped work. The right
agent picks each task up, reads what the team already decided, and ships.

---

## The three-namespace surface

```
+----------------------------------------------------------------------+
|                         first-tree (umbrella CLI)                    |
+---------------------------+---------------------------+--------------+
|           tree            |        github scan        |     hub      |
|      context layer        |   GitHub chief of staff   |   reserved   |
+---------------------------+---------------------------+--------------+
```

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 …` — reserved namespace (stub only; commands fail
  explicitly with an "unimplemented" message)

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 <subcommand>` | Skill maintenance: install, upgrade, list, doctor, link |

### Migration table (from the 2026-05-01 restructure)

| Old                                | New                                |
|------------------------------------|------------------------------------|
| `first-tree breeze <subcommand>`   | `first-tree github scan <subcommand>` |
| `first-tree skill <subcommand>`    | `first-tree tree skill <subcommand>`  |
| `first-tree gardener <subcommand>` | 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. It runs as
a local daemon backed by `packages/github-scan/`; state lives at
`~/.first-tree/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
<owner/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 daemon 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.

```
github-scan:new      — initial state; daemon 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, body > 20 chars, after the label
timestamp), the daemon flips the tag back to `github-scan:new` so the
loop can pick it up again. Without this, the only way out of `human` was
a manual label strip; that asymmetry is fixed by the auto-revert.

Note: the marketing page `/github-scan` describes "Three tags" (wip /
human / done) and omits `new`. The skill, README, and product behavior
are based on four tags. When in doubt, four tags is correct.

### 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=<handled|skipped|failed> route=<reply|human|sync|write> summary=<one-line>
```

---

## `first-tree hub` — reserved namespace

`hub` is reserved for the future hosted version of the same loop — same
agents, same coordination, no infrastructure. Today the namespace ships
with `start` / `stop` / `doctor` / `status` stubs that fail explicitly so
the surface area is documented. The website pillar reads "Coming soon"
and that matches reality.

---

## The macOS menu-bar tray

Status: not yet on `main`. Lives on branch `feat/tray` only. 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` daemon.
> 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 the
> daemon without dropping into a terminal. This is a thin client of the
> daemon — the same `127.0.0.1:7878/inbox` HTTP endpoint that powers the
> dashboard at `http://127.0.0.1:7878/`. Daemon is authoritative; the
> tray just renders state and proxies daemon-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 marketing page at /github-scan leads with the tray as the hero
image. That page is forward-marketing the upcoming experience; the tray
is currently in beta on `feat/tray` and not yet in the npm tarball.

---

## 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, daemon
running, agent templates in place." Five steps:

0. Inspect the current root and classify its role.
1. Choose a daemon mode (today, only local exists).
2. Import repos (no-op for single repos; `workspace sync` for workspaces).
3. Init or bind the tree.
4. Start the GitHub-Scan daemon.
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 daemon 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.** Binding metadata is
   moving out of `.first-tree/source.json` and into a managed block
   inside `AGENTS.md` / `CLAUDE.md`. PRs landed in this area: #371-#377,
   #387, #398-#401. The older `.first-tree/source.json` path remains as
   a legacy fallback during the transition.

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 macOS menu-bar tray (currently on `feat/tray`)
is being prepared as the upcoming hero feature.

---

## 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 repo's own short-form `llms.txt` (line 36) describes "two CLIs
  (`first-tree` and `first-tree-hub`)." Today there is one binary
  (`first-tree`); `hub` is a stubbed subcommand group.

- The `/github-scan` marketing page describes "Three tags" (wip / human
  / done). The actual lifecycle is four tags — it includes `new`. The
  homepage just markets the post-pickup states.

- The `/github-scan` page leads with the macOS menu-bar tray as the
  hero. The tray is on `feat/tray`, not `main`, and not yet in the npm
  tarball (issue #393).

- The homepage FAQ mentions "Agent Message System" as a primitive. There
  is no `apps/` or `packages/` entry on `main` for a chat / message
  system. The doc-tree at `agent-team-foundation/first-tree-doc`
  describes one as part of a future Hub effort, not as something
  shipped here.

- 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/
- GitHub Scan landing: https://first-tree.ai/github-scan
- 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 (mirrored from `first-tree-doc`): https://github.com/agent-team-foundation/first-tree-doc