Share agent environments with gandalf.toml

Gandalf’s team manifest lets you declare a shared AI agent environment as code. Commit a gandalf.toml at the repository root, and teammates get a repeatable Codex and Claude Code setup with drift detection and non-destructive apply.

Initialize the manifest

Create the manifest and skills directory. Use --from-current to scaffold from your local setup.

gandalf init --name my-team-project
gandalf init --from-current

This writes gandalf.toml and .gandalf/skills/. Use -f to overwrite an existing manifest.

Edit gandalf.toml

Declare MCP servers, skills, hooks, and an env template. ${ENV_VAR} interpolation is supported.

gandalf.toml

version = "1.0"
name = "my-team-project"
description = "Standardized AI agent environment"
agents = ["claude-code", "codex"]

[mcp_servers.postgres-db]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
required_env = ["DATABASE_URL"]
description = "Shared staging database MCP server"

[hooks.pre-save-lint]
event = "before_save"
command = "./scripts/lint.sh"

[env_template]
DATABASE_URL = "postgres://user:password@localhost:5432/db"

See the manifest reference for the full field list.

Commit the manifest to git

Commit gandalf.toml and .gandalf/skills/ so teammates get the same setup on checkout.

Check for drift

Compare the manifest to each local agent. Add --ci to exit non-zero on drift for use in CI.

gandalf check
gandalf check --ci

Output lists missing MCP servers, skills, or hooks per agent, with target file paths.

Apply the manifest

Preview, then apply. Apply runs Smart Merge (non-destructive) and creates a pre-apply safety snapshot.

gandalf apply --dry-run
gandalf apply --yes

On success, Gandalf prints the safety snapshot name so you can roll back:

gandalf restore --snapshot <backup> --apply --experimental

Smart Merge only adds or updates entries declared in the manifest. It does not delete or modify unrelated personal user settings.

Get Started

Concepts

Guides

Reference

Share agent environments with gandalf.toml

​Related

Related