landlord 🏠

Knows every tenant, every lease, every complaint.

The Problem

Your agent just got dropped into a codebase with 40 services, 12 teams, and a dependency graph that looks like a plate of spaghetti. It has no idea what exists, who owns what, or what'll break if it touches the wrong thing.

# Agent's inner monologue:
# "What services are there?"        → grep? find? pray?
# "Who owns auth-service?"          → git blame? Slack? Confluence?
# "What depends on payment-api?"    → trial and error? production outage?

There's a stale Confluence page somewhere. Nobody's updated it since the intern left.

Your agent deserves better.

What if agents could understand your infrastructure before touching it?

# What exists?
landlord service list
# ● checkout-api     EvoFg8sF  [production]
# ● payment-processor zSLMBKV6  [production]
# ● auth-service     k9Xm2wP1  [production]

# Who owns what?
landlord owner show platform-team
# platform-team  team  3GJ00QQO
#   Slack: #platform
#
#   Systems
#   ● payments  8RW4htFP
#
#   Services
#   ● checkout-api  EvoFg8sF
#   ● payment-processor  zSLMBKV6

# What breaks if I touch this?
landlord service show checkout-api
# checkout-api  EvoFg8sF
# Handles checkout flow
#
#   Owner:     platform-team
#   System:    payments
#   Lifecycle: production
#
#   APIs
#     Checkout REST API (rest) — Public checkout endpoints
#
#   Dependencies
#     → payment-processor (Stripe integration) — Sends payment requests

The agent knows what exists, who to ask, and what not to break. Before writing a single line of code.

landlord is the service catalog. Your agent is the tenant.

For Humans

You set up landlord once. Then your agent uses it every time.

Installation

npm install -g landlord-ai

Setup (one-time)

# Create the catalog in your repo
landlord init

# Register who owns things
landlord owner add --name platform-team --type team --slack "#platform"
landlord owner add --name auth-team --type team --email "[email protected]"

# Define your systems
landlord system add --name payments --owner platform-team --description "Everything money-related"
landlord system add --name identity --owner auth-team --description "Auth, users, permissions"

# Register your services
landlord service add --name checkout-api \
  --system payments \
  --owner platform-team \
  --lifecycle production \
  --description "Handles checkout flow" \
  --repo https://github.com/company/checkout-api

landlord service add --name auth-service \
  --system identity \
  --owner auth-team \
  --lifecycle production \
  --description "OAuth2 and session management"

# Add APIs
landlord service api-add checkout-api \
  --name "Checkout REST API" \
  --type rest \
  --spec ./openapi.yaml \
  --description "Public checkout endpoints"

# Add dependencies
landlord service dep-add checkout-api \
  --on payment-processor \
  --api "Stripe integration" \
  --description "Sends payment requests"

landlord service dep-add checkout-api \
  --on auth-service \
  --description "Validates OAuth tokens"

# Commit to git — this is your service catalog
git add .landlord/
git commit -m "Add service catalog"

Now onboard your agent:

landlord onboard

This adds landlord instructions to your CLAUDE.md, teaching your agent to check the catalog before making changes.

Managing the Catalog

# Services
landlord service add --name <name> [options]    # Register a service
landlord service list                           # List all services
landlord service show <id-or-name>              # Full service profile (with dependents)
landlord service rm <id-or-name>                # Remove a service
landlord service api-add <service> [options]    # Add an API to a service
landlord service dep-add <service> [options]    # Add a dependency

# Systems
landlord system add --name <name> [options]     # Create a system
landlord system list                            # List all systems
landlord system show <id-or-name>               # System details + services

# Owners
landlord owner add --name <name> --type <type>  # Register an owner
landlord owner list                             # List all owners
landlord owner show <id-or-name>                # Owner details + what they own

Dependencies

The most important question before modifying a service: what depends on me?

landlord deps checkout-api                      # Both directions
landlord deps checkout-api --direction up       # What depends on me (dependents)
landlord deps checkout-api --direction down     # What I depend on (dependencies)
landlord deps checkout-api --depth 3            # Limit transitive depth
landlord deps --orphans                         # Find isolated services

checkout-api

  ↑ Dependents (what depends on me)
    ├── storefront-ui (Checkout REST API)
    └── mobile-app (Checkout REST API)

  ↓ Dependencies (what I depend on)
    ├── payment-processor — Sends payment requests
    │   └── stripe-webhook
    └── auth-service (OAuth tokens)

Search

landlord search "authentication"                # Full-text across all entities
landlord search "grpc" --kind service           # Filter by entity kind
landlord search --unowned                       # Services with no owner
landlord search --unassigned                    # Services with no system
landlord search --lifecycle deprecated          # By lifecycle stage

Catalog Health

landlord lint                                   # Validate catalog integrity
landlord lint --json                            # Structured output for agents

Checks for: orphaned references, missing owners, circular dependencies, dangling deps, duplicate names, empty systems. Exit code 1 if errors found.

Auto-Discovery

Don't add services by hand — discover them automatically.

# Scan a local directory of repos
landlord discover --dir ~/Projects

# Scan a GitHub org
landlord discover --github-org mycompany

# Filter by topic or language
landlord discover --github-org mycompany --topic backend
landlord discover --github-org mycompany --language typescript

# Preview without making changes
landlord discover --dry-run

Discovery looks for catalog-info.yaml (or .landlord/catalog.yaml) in each repo. If none exists, it infers a service from the repo name and package.json description.

Catalog file format:

apiVersion: landlord/v1
kind: Service
metadata:
  name: checkout-api
  description: Handles checkout flow
spec:
  system: payments
  owner: platform-team
  lifecycle: production
  apis:
    - name: Checkout REST API
      type: rest
      spec: ./openapi.yaml
  dependsOn:
    - payment-processor
    - service: auth-service
      api: OAuth
      description: Token validation

Running discover is idempotent — it matches on service name, detects what's new vs updated, and never duplicates. Changed a description? It'll show up as an update.

Filtering

landlord service list --system payments         # Services in a system
landlord service list --owner platform-team     # Services by owner
landlord service list --lifecycle deprecated    # By lifecycle stage
landlord service list --tag backend             # By tag

Global Flags

All commands support:

--json                        # Structured JSON output (for agents)
-q, --quiet                   # Suppress output, use exit codes only

ID-or-Name Resolution

Every command accepts either an ID or a name. landlord checks for an exact ID match first, then searches by name (case-insensitive):

landlord service show EvoFg8sF           # by ID
landlord service show checkout-api       # by name — same result

For Agents

Check the catalog before you touch anything.

Understanding What Exists

# List all services (use --json for structured output)
landlord service list --json

# Get full details on a service
landlord service show checkout-api --json

# See what a team owns
landlord owner show platform-team --json

# See all services in a system
landlord system show payments --json

Before Modifying a Service

1. Check ownership — who owns this? Do you have context from them?
2. Check dependents — what depends on this service? Will your change break something?
3. Check lifecycle — is this production? deprecated? experimental?
4. Check APIs — does this expose APIs others rely on?

# Full profile: owner, system, APIs, dependencies, AND dependents
landlord service show checkout-api --json

# Dependency graph — what breaks if I touch this?
landlord deps checkout-api --json

# Search for related services
landlord search "payments" --json

Registering New Services

If you create a new service, register it:

landlord service add \
  --name my-new-service \
  --system payments \
  --owner platform-team \
  --lifecycle experimental \
  --description "Does the thing"

How It Works

┌──────────────────────────────────────────────────┐
│  Agent                                           │
│                                                  │
│  "I need to modify the checkout flow"            │
│  > landlord service show checkout-api --json     │
│                                                  │
│  → Owner: platform-team                          │
│  → System: payments                              │
│  → Depends on: payment-processor, auth-service   │
│  → API: Checkout REST API (rest)                 │
│  → Lifecycle: production                         │
│                                                  │
│  "OK, this is production, owned by platform,     │
│   and payment-processor depends on it.           │
│   I'll be careful."                              │
└──────────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│  .landlord/                                      │
│                                                  │
│  services/                                       │
│    EvoFg8sF.json    ← checkout-api               │
│    zSLMBKV6.json    ← payment-processor          │
│    k9Xm2wP1.json    ← auth-service              │
│  systems/                                        │
│    8RW4htFP.json    ← payments                   │
│  owners/                                         │
│    3GJ00QQO.json    ← platform-team              │
│  config.json                                     │
│                                                  │
│  Plain JSON. Committed to git. Diffable.         │
│  Your PR review IS your catalog review.          │
└──────────────────────────────────────────────────┘

Design principles:

• Git-native: Everything is JSON files in .landlord/, committed to your repo. git log .landlord/ is your audit trail.
• Agent-first: --json on every command. Structured output agents can parse without regex.
• Zero infrastructure: No database, no server, no Docker. Just files in a directory.
• ID-or-name: Every command accepts either. No looking up IDs before you can do anything.

Why Not Backstage?

Backstage is great. It's also a React app, a PostgreSQL database, a Node.js backend, a Docker deployment, and a full-time platform engineer to keep it running. It was designed for humans with browsers.

landlord was designed for agents with terminals.

| | Backstage | landlord | |---|---|---| | Primary user | Humans (browser UI) | AI agents (CLI + JSON) | | Infrastructure | PostgreSQL, Node.js, Docker, Kubernetes | None. JSON files in a directory. | | Setup time | Hours to days | npm install -g landlord-ai && landlord init | | Data storage | Database | Git. Your PR review is your catalog review. | | Team size | 50+ engineers with a platform team | 1-50 engineers, no dedicated platform team | | Plugin ecosystem | 100+ plugins | Focused scope. Not trying to be a platform. |

If your org already runs Backstage, landlord isn't a replacement. It's a CLI that could read from Backstage's API — giving your agents a way to query the catalog without a browser.

If your org doesn't run Backstage, landlord gives you 80% of the catalog value with 0% of the infrastructure overhead. Your agent can understand what exists, who owns it, and what depends on what — which is the part that actually matters when it's about to modify your code.

Multi-Repo Setup

In an org with many repos, the recommended pattern:

org-catalog/              ← central catalog repo
  .landlord/
    services/
    systems/
    owners/

checkout-api/             ← service repo (owns its own metadata)
  catalog-info.yaml

payment-processor/        ← service repo
  catalog-info.yaml

1. Each service repo has a catalog-info.yaml — the team that owns the service owns its metadata
2. One central catalog repo has .landlord/ — populated by landlord discover --github-org
3. Agents in any repo set LANDLORD_CATALOG to point at the central catalog (coming in v0.3)

# In the catalog repo, on a schedule:
landlord discover --github-org mycompany

# In any service repo, the agent queries the central catalog:
export LANDLORD_CATALOG=~/Projects/org-catalog/.landlord
landlord deps checkout-api --json

For single-repo setups or small teams, just put .landlord/ in your main repo. No ceremony needed.

Data Model

Service

The main entity. A deployable unit of software.

| Field | Type | Description | |-------|------|-------------| | name | string | Service name | | description | string | What it does | | system | ref | System it belongs to | | owner | ref | Team or person who owns it | | lifecycle | enum | experimental · production · deprecated · decommissioned | | repo | string | Repository URL | | tags | string[] | Freeform tags | | apis | Api[] | APIs this service exposes | | dependsOn | Dependency[] | Services this depends on |

System

A group of related services (e.g., "payments", "identity").

Owner

A team or person who owns services and systems.

API

An interface a service exposes: rest, grpc, graphql, event, or other.

Dependency

A link from one service to another, optionally specifying which API is consumed.

Roadmap

v0.2 — Trustworthy Catalog ✅

• [x] landlord lint — validate catalog integrity (orphaned refs, missing owners, circular deps)
• [x] landlord search — unified text search across all entities (MiniSearch, auto-reindexing)
• [x] landlord discover — auto-populate from GitHub org or local repos (catalog files + inference)
• [x] landlord deps — full dependency graph, both directions (up/down, transitive, orphans)
• [x] Relation stitching — bidirectional relations computed at query time

v0.3 — Agent Context

• [ ] Multi-repo support — LANDLORD_CATALOG env var for central catalog repo pattern
• [ ] landlord score — health scorecards per service (agents see trust level before modifying)
• [ ] landlord sync — continuous discovery via cron/9to5
• [ ] API spec rendering — parse and display OpenAPI/gRPC/GraphQL specs inline

Development

# Install dependencies
npm install

# Run locally
npm run dev -- --help

# Build for npm
npm run build

# Build native binary
bun run build:bun

# Run tests
bun test

# Format & lint
bun run check

License

MIT