Guide

Choose a Scope

Commands are global by default, even inside a repository. Global config lives under ~/.agents/ and applies across projects.

Use --project on every command that should read or change repository-local state. Project commands use the Git root and never fall back to global config.

Global Setup

Initialize global config and choose which agent tools to configure:

npx @sentry/dotagents init

By default, init declares the dotagents skill from getsentry/dotagents so agent tools can discover CLI guidance. It then runs install best-effort.

Add skills or plugins:

# Add a skill
dotagents add getsentry/skills find-bugs

# Add a plugin
dotagents add getsentry/agent-plugins review-tools

# Add all skills from a repo
dotagents add getsentry/skills --all

Git and local sources are checked for plugins first. If no plugin is found, dotagents discovers skills. See the CLI reference for all source formats.

Run install whenever you want to fetch or refresh all declared dependencies:

dotagents install

There is no separate update command.

Project Setup

Keep --project on every repository-local command:

# Initialize this repository
dotagents --project init

# Add a repository dependency
dotagents --project add getsentry/skills find-bugs

# Install after cloning or pulling
dotagents --project install

Commit agents.toml. Collaborators use the project-scoped install command to recreate managed local state.

What Gets Gitignored

In project scope, dotagents keeps two generated files out of version control:

• agents.lock tracks managed skills, subagents, and plugins.
• .agents/.gitignore excludes managed dependency files under .agents/.

Custom skills and project-authored plugin sources are tracked normally when they are not managed installed dependencies. Global commands never change a repository’s Git ignore files.

Trust Policies

By default, any source is allowed. For teams, add a [trust] section to restrict skill, subagent, and plugin sources. Trust is validated before any network operations.

# Trust a GitHub org
dotagents --project trust add getsentry

# Trust a specific repo
dotagents --project trust add external-org/specific-repo

# Trust a self-hosted git server
dotagents --project trust add git.corp.example.com

See the Security page for the full trust configuration reference.

Auto-install with Git Hooks

Since managed .agents/ files are gitignored, run dotagents --project install after pulling. A post-merge hook automates this:

.git/hooks/post-merge

#!/bin/sh
npx --yes @sentry/dotagents --project install || echo "dotagents install failed"

Make it executable:

chmod +x .git/hooks/post-merge

Git hooks are not shared through git. Tools like lefthook or husky can set them up for the whole team.

Keeping Things in Sync

Use dotagents --project sync for offline project repair. It does not fetch anything from the network. Instead, it:

• Adopts local orphaned skills, meaning installed skills that are not declared.
• Prunes stale managed skills, subagents, and plugins removed from config.
• Regenerates .agents/.gitignore.
• Repairs broken symlinks.
• Fixes MCP and hook configs.
• Repairs generated subagent and plugin runtime files.

Diagnosing Issues

Use dotagents --project doctor to check project health. It identifies configuration issues and can fix them automatically.

dotagents --project doctor        # check for issues
dotagents --project doctor --fix  # auto-fix what it can

Checks for missing gitignore entries, legacy config fields, missing skills and plugins, and broken symlinks. Use dotagents --project sync to repair generated runtime config drift. Doctor is especially useful when migrating from an older version.

Global Paths

Global config, skills, plugins, and the lockfile live under ~/.agents/. Plugin outputs are written to the global Claude, Cursor, Codex, Grok, OpenCode, and Pi locations. Override the dotagents root with DOTAGENTS_HOME.

--global selects global scope explicitly. --user remains a compatibility alias.

Full Configuration Example

agents.toml with skills, wildcards, plugins, MCP servers, hooks, and subagents:

version = 1
agents = ["claude", "cursor", "codex", "opencode"]
minimum_release_age = 60
minimum_release_age_exclude = ["getsentry/*"]

[trust]
github_orgs = ["getsentry"]

# Individual skill
[[skills]]
name = "find-bugs"
source = "getsentry/skills"

# Pinned to a ref
[[skills]]
name = "warden-skill"
source = "getsentry/warden@v1.0.0"

# Well-known HTTPS source
[[skills]]
name = "error-tracking"
source = "https://cli.sentry.dev"

# Wildcard: all skills under one repo subdirectory
[[skills]]
name = "*"
source = "myorg/skills"
path = "skills/engineering"
exclude = ["deprecated-skill"]

# MCP server (stdio)
[[mcp]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = ["GITHUB_TOKEN"]

# MCP server (HTTP with OAuth)
[[mcp]]
name = "remote-api"
url = "https://mcp.example.com/sse"

# Hooks
[[hooks]]
event = "PreToolUse"
matcher = "Bash"
command = "my-lint-check"

# Custom subagent
[[subagents]]
name = "code-reviewer"
source = "getsentry/agent-pack"
targets = ["claude", "codex", "opencode"]

# Plugin bundle
[[plugins]]
name = "review-tools"
source = "getsentry/agent-pack"
targets = ["claude", "cursor", "codex", "opencode"]

See the CLI reference for all fields and options.