Quickstart

You need Node 22.18 or later and a git repo for the knowledge base (KB). It can be a new, empty repo; your code stays where it is.

Run setup

git clone git@github.com:your-org/team-kb.git && cd team-kb   # or git@bitbucket.org:your-workspace/team-kb.git
npx --yes homeostat@0.5.16 setup

Cloning a Bitbucket repo over HTTPS? Your account password won’t work: use an API token as the password, with the username x-bitbucket-api-token-auth (details).

setup walks a checklist and checks each step as it goes. Each question shows an example answer and its default; secrets are pasted at a prompt that shows nothing while you paste.

• the KB repo and host
• a git-host token (your own works; which one), verified and stored as the CI variable HOMEOSTAT_GIT_TOKEN
• your code repos and their areas
• the team and reviewers
• the model credential
• Slack
• the schedules
• CODEOWNERS
• one commit
• a first base

Run it again at any time: it asks only for what is missing or broken. homeostat setup --check prints where things stand. Each teammate then runs npx --yes homeostat@0.5.16 setup --join once in their own clone. Every step, and why the optional ones are optional.

Before you invite the team, run homeostat doctor --security.

By hand

The rest of this page is what setup does for you, step by step, for when you want to do it yourself or need to know where something lives.

1. Create the knowledge base

git clone git@github.com:your-org/team-kb.git && cd team-kb   # or git@bitbucket.org:your-workspace/team-kb.git
npx --yes homeostat@0.5.16 init --member your-id --handle @your-user

A handle is your GitHub login or, on Bitbucket, your Bitbucket nickname (Personal settings > Account). Bitbucket nicknames often hold spaces and accents; write them as they are, quoted in YAML: handle: "@Ana Ruiz". Case does not matter.

init writes homeostat.yaml, knowledge/core/, and CI jobs for your git host (GitHub Actions or Bitbucket Pipelines):

• validation on every PR
• the daily run and the weekly deep dive
• the weekly digest

It also prints which tokens to create and how to protect the branch.

2. Describe your team

Edit homeostat.yaml (all keys: configuration):

team:
  members:
    - { id: dana, handle: "@dana", role: senior, areas: [integrations] }
    - { id: lee, handle: "@lee", role: member, areas: [frontend] }
areas:
  integrations: ["services/integrations/**"]
  frontend: ["apps/web/**"]
sources:
  host: github            # or bitbucket
  kbRepo: your-org/team-kb
  repos: [your-org/api, your-org/web]

When the team owns several repos and wants each repo’s rules kept apart, list them under repos instead, each with its own areas; a session then gets only its own repo’s rules plus the shared ones in knowledge/core/:

repos:
  api:
    source: your-org/api
    areas:
      integrations: ["services/integrations/**"]
  web:
    source: your-org/web
    areas:
      frontend: ["apps/web/**"]
sources:
  host: github
  kbRepo: your-org/team-kb

Member areas are then written api/integrations. To group rules into a few files by subject rather than one file each, add a topics list (details).

Then generate CODEOWNERS, so each area’s owners review its changes (on Bitbucket it goes in .bitbucket/CODEOWNERS, where Bitbucket reads it):

npx --yes homeostat@0.5.16 codeowners
npx --yes homeostat@0.5.16 validate

3. Build a first base

With your code repos checked out next to the KB:

npx --yes homeostat@0.5.16 bootstrap --dry-run

It lists every file it would read from each repo (existing docs, schemas and migrations, charts and pipelines) and what the model calls would cost. Run it without --dry-run to import the docs and draft the rest; you get one PR per repo to correct and merge (details).

4. Write a first rule

npx --yes homeostat@0.5.16 learn --area integrations \
  --title "Use the shared retry helper for partner calls" \
  --rule "Wrap every outbound partner call in withRetry() from @acme/http-client." \
  --why "Hand-rolled retries skipped the request-id header partners ask for."

Or capture it from a review comment: homeostat learn <comment URL>. Commit on a branch, open a PR, and once it is approved the rule is live.

5. Get it to your agents

• Claude Code: install the plugin and point it at your KB checkout (details):

  claude plugin marketplace add ysugarmen/homeostat
  claude plugin install homeostat@homeostat

• Cursor, Copilot, AGENTS.md: from a code repo, run homeostat export --kb ../team-kb.

• Any MCP client: run homeostat mcp.

6. Turn on the daily run

Add the secrets init printed: a git-host token as HOMEOSTAT_GIT_TOKEN (on Bitbucket, with HOMEOSTAT_GIT_EMAIL for an Atlassian API token; which token) and a Claude credential, or use your cloud account (runtimes). Run homeostat curate --show-prompts once to see exactly what would be sent, and homeostat daily --dry-run to see what it would decide. From then on, each morning, every developer’s lessons and what their reviewers taught them arrive in one PR per developer. Confident lessons merge themselves; only the uncertain ones wait for a reviewer (how it decides). Developers need nothing beyond the plugin: their sessions sync in the background.

Before you invite the team, run homeostat doctor --security.