Skip to main content

Getting Started with AgentBoot

AgentBoot is a harness engineering build tool that manages your AI agent behavior as source code — versioned, reviewed, tested, and deployed from a central personas repo to every project in your org. It compiles personas into platform-native formats. Official support targets the CLI surfaces of Claude Code, Codex, and GitHub Copilot, plus the universal AGENTS.md standard as an officially supported, advisory-enforcement output — the industry-standard cross-tool instruction file (advisory by nature: no hook mechanism, so blocking enforcement remains a Claude Code / Codex / Copilot capability). AgentBoot additionally emits for Cursor, Gemini, Windsurf, and JetBrains on a community-supported basis.

By the end of this guide you will have a personas hub deployed and /ab running in Claude Code — ready to answer questions, manage your setup, and deploy changes.

Beta notice: AgentBoot v0.21.0 is a public Beta. It's usable end to end, but breaking changes may occur without deprecation warnings before v1.0 GA. Release notes document all changes, and we do our best to minimize disruption — but stability is not guaranteed until v1.0. If you hit a rough edge, tell us.

Prerequisites​

Before you start, you need:

  1. Claude Code installed and configured. You should be able to run claude from the command line and have it connect to your account. → Install: code.claude.com/docs

  2. Node.js 22 or later. Check with node --version. If you need to upgrade, use nvm or download from nodejs.org.

  3. Git installed and configured. The personas hub is a git repository — the install wizard runs git init for you if the target directory isn't one yet, and detects your org from the git remote when one exists.

  4. GitHub account with permission to create repositories in your org (or your personal account for solo use). If you don't have permission yet, see Local evaluation below.

  5. One target repository that you want to deploy AgentBoot personas to. This is any existing codebase where you want consistent AI agent behavior. It must be a git repository, and you need write access.

Step 0: Install the AgentBoot CLI​

# Recommended
npm install -g agentboot

# Or via Homebrew (macOS Sequoia and earlier)
brew tap agentboot-dev/agentboot && brew install agentboot

# Or run without installing
npx agentboot --help

macOS Tahoe (macOS 26) users: Homebrew's sandbox is currently incompatible with macOS Tahoe. Use npm install -g agentboot instead. See Troubleshooting for details.

Verify:

agentboot --version

Step 1: Run the install wizard​

agentboot install

The wizard will:

  1. Ask where to create the personas repo (or use one you already have)
  2. Detect your org from git (you confirm)
  3. Ask which AI agent tools your team uses
  4. Scaffold the personas source code and configuration
  5. Build the personas automatically
  6. Offer to register your target repos (scans siblings, auto-discovers)
  7. Sync compiled personas to registered repos automatically

Target repo already has agent config? If a target repo has pre-existing hand-written instruction files (CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md), the first sync deliberately stops rather than replace them. You choose: run agentboot import first (recommended — it decomposes your existing content into hub artifacts so nothing is lost), or run agentboot sync --adopt-existing to replace them. With --adopt-existing, every pre-existing file the sync overwrites — including root-level artifacts — is archived to .claude/.agentboot-archive/ (with an archive manifest) before anything is written, so the originals remain recoverable.

The wizard generates agentboot.config.json. Edit it to customize — see Configuration.

The wizard registers repos interactively. Edit repos.json directly if needed — see Configuration.

You can also specify options explicitly:

agentboot install --hub --org acme        # Skip org detection

After Step 1 completes, restart Claude Code. The /ab skill is deployed during install — restarting Claude picks it up.

Alternative: GitHub template​

If you prefer to set up manually, the AgentBoot repo is a GitHub template:

gh repo create my-org/personas \
  --template agentboot-dev/agentboot \
  --private \
  --clone
cd personas
npm install

Or use the GitHub web UI: go to github.com/agentboot-dev/agentboot, click "Use this template", choose "Create a new repository", and clone the result.

Local evaluation (no GitHub repo required)​

If your org requires approval before creating new repositories, you can evaluate AgentBoot entirely locally. The personas repo is a standard git repo — it does not need a remote until you're ready to share it.

mkdir personas && cd personas
git init
agentboot install --hub

This gives you a fully functional personas repo on your local machine. Build, sync to a target repo, and prove value — all without touching GitHub. When the org approves, push it:

gh repo create my-org/personas --source . --private --push

Nothing changes about the repo structure. There is no "local mode" vs "production mode" — a personas repo without a remote is the same as one with a remote. Git handles this natively.

This is the recommended path for proof-of-concept evaluations in locked-down environments. The org can audit every file in the personas repo before it goes to GitHub, since it's all git-tracked source code.

Step 2: Verify /ab is working​

Restart Claude Code, then go to any registered repo (or the hub itself) and type:

/ab

Try a few interactions:

/ab how do I add a new persona?
/ab show me what's registered
/ab status

To verify the deployed personas work:

/review-code
/review-security src/auth/login.ts
/gen-tests src/services/user-service.ts

If any command is not recognized, check that the .claude/agents/ and .claude/skills/ directories were written correctly in the sync step and that the persona SKILL.md files are present.

Step 3: Add an org-wide instruction — and a guardrail​

Personas are who the agent is. Instructions are the always-on rules that apply regardless of which persona is active. They live in core/instructions/:

agentboot add instruction secret-read-deny

That scaffolds core/instructions/secret-read-deny.instructions.md:

---
description: "TODO — brief description of this instruction"
applyTo: "**"
# guardrail: hard
---

applyTo is a comma-separated glob list — "**" is always-on, "src/api/**" scopes it to a subtree. Keep the body short: it loads on every session and competes for context.

Scoping is not expressible everywhere. Cursor, Windsurf and JetBrains receive the exact scope (translated to their native globs: / trigger: glob keys), and Copilot reads applyTo directly. Claude Code, Skill, plugin, AGENTS.md, Codex and Gemini have no scoping mechanism at all — a rule reaches them always-on. Because that is the opposite of what a narrow applyTo asks for, the build fails when a narrowly-scoped instruction targets one of those platforms. If always-on delivery is genuinely what you want, say so on the artifact:

---
description: "API layer rules"
applyTo: "src/api/**"
scope-unsupported: acknowledged
---

The acknowledgement is not silence: the emitted file gains a Scope: preamble telling the agent which paths the rule is meant for, and every build reports the artifact. See the platform capability matrix for the per-platform table.

Making it non-overridable​

By default an instruction is a soft preference — a team may adapt it. To make it a rule a team cannot silently weaken, uncomment the guardrail line:

guardrail: hard

Then a lower scope shadowing it, downgrading it, or zeroing its weight is an error:

agentboot validate --strict

Run validate --strict and build in CI, in that order. They're separable commands — build can succeed on a config validate --strict rejects. Only running build will compile a guardrail violation and ship it.

On Claude Code, Codex CLI and Copilot CLI a HARD guardrail compiles to a blocking hook — with Copilot's ceiling stated: its exit-2 blocking is documented platform behaviour we have not yet verified end to end, and its command-hook timeouts fail open. On AGENTS.md and the community-tier platforms it is delivered as instruction text with no blocking mechanism — see Guardrails for the full picture and how to verify enforcement rather than assume it.

Step 4: Add your first team-level customization​

Team-level customization lets you add personas that apply only to repos in a specific team, without affecting the rest of the org.

First declare the scope in agentboot.config.json:

{
  "groups": {
    "platform": { "teams": ["api"] }
  }
}

Then create the team's persona under the scope tree in your personas repo:

nodes/
  platform/
    api/
      personas/
        api-contract-reviewer/
          persona.config.json   ← model, invocation, trait weights
          SKILL.md              ← a persona specific to the API team

(The nested groups/platform/teams/api/ and sibling teams/platform/api/ layouts are also accepted — nodes/ is the canonical form.)

Run /ab build then /ab sync (or agentboot build && agentboot sync from the terminal). Repos registered to the api team under platform will now receive the API contract reviewer persona, layered on top of the org defaults. Other repos are unaffected.

What compiles at team scope today: persona definitions and per-persona trait weights. Scope-level trait/instruction/gotcha content files (e.g. a team-only always-on instruction) are not compiled at team scope yet — the build warns loudly if it finds any, so they can't silently produce no output. Org-wide instructions live in core/instructions/.

Step 5: Configure your harness​

Your personas repo is a codebase. Treat it like one:

  1. Enable branch protection on main. Persona changes should go through code review — the same discipline you apply to application code.

  2. Add CI validation. Run agentboot validate --strict in your CI pipeline to catch errors before merge.

  3. Encourage contributions. Developers who use the personas daily are your best contributors. A low-friction PR workflow lets them propose improvements to the prompts they know best.

Step 6: Onboard your team​

Once you have a working deployment, tell your team:

  1. Claude Code reads .claude/ automatically. No install required on each developer's machine beyond having Claude Code. The personas and instructions are active the moment they clone the repo and open Claude Code.

  2. /ab is the day-to-day interface. Type /ab in any repo with deployed personas. It can answer questions, run builds, sync, import, and diagnose issues.

  3. Slash commands are ready to use. Share the invocation table from PERSONAS.md with your team. The most useful ones to start with:

    • /review-code — code review against your team's standards
    • /review-security — security-focused review
    • /gen-tests — generate unit and integration tests

  4. Changes to agent behavior go through the personas repo. If a developer wants to change how a persona behaves or add a new one, they open a PR against the personas repo, not against the target repo. This keeps governance centralized.

  5. The always-on instructions in .claude/CLAUDE.md apply automatically. Developers do not need to do anything to activate them. They are active on every Claude Code session in that repo.

Next steps​

  • Use /ab day-to-day. It's the primary interface for managing your personas setup. Ask it anything: /ab how do I add a persona?, /ab status, /ab sync.
  • Add more repos: Edit repos.json or have developers run agentboot install from their repos.
  • Add a domain layer: See docs/extending.md for how to build compliance or domain-specific personas on top of AgentBoot core.
  • Automate sync on merge: Set up the sync workflow so that every merge to main in your personas repo automatically opens a PR against each registered repo. See .github/workflows/validate.yml for the CI foundation you can extend.
  • Read the concepts doc: docs/concepts.md explains the trait system, scope hierarchy, and distribution model in depth.
  • Upgrading from an earlier version? See docs/migration.md for step-by-step upgrade instructions.

Advanced: Import existing prompt knowledge​

If your org already has hand-written .claude/ content, CLAUDE.md files, Copilot instructions, or Cursor rules scattered across repos, you can import them into your personas repo:

/ab import

Or from the terminal: agentboot import --path ~/work/

Import uses AI to scan and classify your existing prompt content into personas, traits, gotchas, and instructions. It never modifies or deletes your original files — it creates new files in the personas repo only. You review and merge the results.

This is an LLM-powered command that requires an active Claude Code session. See CLI Reference for details.

Advanced: Developer setup (connecting to an existing hub)​

If your org already has a personas repo and you want to connect your code repo to it, run agentboot install from your code repo:

cd /path/to/my-code-repo
agentboot install --connect

The wizard will:

  1. Find the personas repo (scans siblings, checks your GitHub org via gh)
  2. Register your repo in the hub's repos.json
  3. Create a branch and offer to open a PR against the personas repo
  4. Optionally sync compiled output to your repo immediately

You can also specify the hub path explicitly:

agentboot install --connect --hub-path ~/work/personas