Quick Start

Choose the path that matches your situation.

New project

1. Scaffold the canonical directory

   agentsmesh init

   This creates:

   • agentsmesh.yaml — project configuration
   • agentsmesh.local.yaml — local overrides (gitignored)
   • .agentsmesh/rules/_root.md — starter root rule
   • Updates .gitignore to exclude agentsmesh.local.yaml, .agentsmeshcache, .agentsmesh/.lock.tmp, and .agentsmesh/packs/ (see What to commit)

2. Edit your root rule

   # Open the root rule in your editor
   vi .agentsmesh/rules/_root.md

   Example root rule:

   ---
   root: true
   ---
   
   # Project Guidelines
   
   - Write tests before implementation.
   - Max 200 lines per file.
   - Use TypeScript strict mode.
   - Prefer pure functions over classes.

3. Configure your targets

   Open agentsmesh.yaml and set the tools your team uses:

   version: 1
   targets:
     - claude-code
     - cursor
   features:
     - rules
     - commands
     - mcp

4. Generate

   agentsmesh generate

   Output files are written to each tool’s native directory (.claude/, .cursor/, etc.).

Existing project with tool configs

1. Initialize

   agentsmesh init

   AgentsMesh scans for existing configs from every supported AI coding tool and prompts you to import each one found.

   To auto-import everything without prompts:

   agentsmesh init --yes

   That imports native configs into .agentsmesh/ and still drops example commands/, agents/, and skills/ stubs anywhere import did not already create files in those areas.

2. Review the canonical files

   ls .agentsmesh/rules/
   ls .agentsmesh/commands/
   cat .agentsmesh/permissions.yaml

3. Generate for all targets

   agentsmesh generate

4. Verify nothing unexpected changed

   agentsmesh diff

   If the diff looks clean, commit both .agentsmesh/ and the generated files.

Tip

After init, .agentsmesh/ is the only thing you should edit. Generated files in .claude/, .cursor/, etc. are artifacts — regenerate them, don’t edit them directly.

What to commit and what to gitignore

agentsmesh init writes the recommended .gitignore entries. The defaults are deliberate:

Path	In git?	Why
.agentsmesh/ (canonical)	commit	The source of truth — must be in git.
.agentsmesh/.lock	commit	Drift detection contract. agentsmesh check compares against this.
.agentsmesh/packs/	gitignore	Materialized from installs.yaml. Same model as node_modules — agentsmesh install --sync reproduces them deterministically post-clone.
agentsmesh.local.yaml	gitignore	Per-developer overrides.
.agentsmesh/.lock.tmp	gitignore	Transient.
.agentsmeshcache	gitignore	Remote-extends cache.
Generated tool folders (.claude/, .cursor/, .github/, .gemini/, CLAUDE.md, AGENTS.md, etc.)	commit	AI tools read these at runtime. Committing means a fresh clone has working AI configs without a build step. agentsmesh check in CI catches drift.

Note

Why generated configs stay committed: same reason package-lock.json does. They’re deterministic build output that downstream consumers (in this case, the AI tool itself) read directly. Gitignoring them breaks fresh-clone UX and makes agentsmesh check meaningless. PR reviewers also benefit from seeing the projected diff in the format Claude/Cursor/Copilot will actually consume.

If your team has a strong reason to gitignore generated configs (monorepo size, regenerate-on-checkout hooks), add the target-specific entries manually — but expect to wire agentsmesh generate into your post-checkout flow.

What’s next

• Add rules, commands, agents, and skills
• Set up CI drift detection
• Share config across repositories with extends
• Browse the full CLI reference