CAMI Documentation

Core Concepts

Understanding CAMI's Architecture

CAMI is built around four core entities that work together to manage your AI agents. Understanding these concepts is key to using CAMI effectively.

The Four Core Entities

1. Agents

What they are: Markdown files with YAML frontmatter containing specialized instructions for Claude Code

Where they live in sources: ~/cami-workspace/sources/[source-name]/

Where they get deployed: .claude/agents/ in your projects

What they do: Provide expertise in specific domains (frontend, backend, QA, design, etc.)

Agent Classes: CAMI classifies agents into three types based on their purpose:

  1. Workflow Specialists (Task Automators): Execute specific, repeatable workflows
    • Examples: k8s-pod-checker, deployment-workflow, component-builder
    • Use when: You have a defined checklist or process to follow
  2. Technology Implementers (Feature Builders): Build complete features in specific domains
    • Examples: frontend, backend, database, auth-system
    • Use when: You need a full feature, screen, or API capability
  3. Strategic Planners (System Architects): Plan, research, and architect systems
    • Examples: architect, researcher, security, performance
    • Use when: You need high-level guidance, technology evaluation, or system design

Example agent file:

markdown
---
name: frontend
version: "1.1.0"
description: React 19+ and Next.js specialist for building user interfaces
class: technology-implementer         # REQUIRED: agent classification
specialty: react-development          # REQUIRED: domain expertise
tags: ["react", "nextjs", "frontend"] # OPTIONAL: searchable tags
use_cases: ["UI development", "SPA", "SSR"] # OPTIONAL: usage examples
color: blue                           # OPTIONAL: UI identifier
model: sonnet                         # OPTIONAL: recommended Claude model
---
# Frontend Agent
You are a specialized frontend development expert...

Learn more about working with agents

2. Sources

What they are: Collections of agents, typically Git repositories

Where they live: Cloned into ~/cami-workspace/sources/

What they do: Provide agents from different origins (official, team, personal)

Configuration: Defined in ~/cami-workspace/config.yaml

Example source configuration:

yaml
agent_sources:
  - name: official-agents
    type: local
    path: ~/cami-workspace/sources/official-agents
    priority: 100
    git:
      enabled: true
      remote: git@github.com:lando-labs/official-agents.git
  - name: my-agents
    type: local
    path: ~/cami-workspace/sources/my-agents
    priority: 10
    git:
      enabled: false

Learn more about sources

3. Projects

What they are: Your development projects where agents get deployed

Where they live: Anywhere on your filesystem (~/projects/my-app)

What they receive: Agent files copied to their .claude/agents/ directory

When you deploy agents to a project, CAMI:

  1. Copies agent files from source to .claude/agents/
  2. Creates/updates .claude/cami-manifest.yaml (project manifest)
  3. Updates CLAUDE.md with agent documentation
  4. Tracks deployment in ~/cami-workspace/deployments.yaml (central manifest)

Learn more about projects

4. Manifests

What they are: YAML files tracking agent deployments

Two types:

Project Manifest (.claude/cami-manifest.yaml):

yaml
version: "1"
agents:
  - name: frontend
    version: "1.1.0"
    source: official-agents
    hash: sha256:abc123...
    deployed_at: "2025-11-23T10:30:00Z"

Central Manifest (~/cami-workspace/deployments.yaml):

yaml
version: "1"
deploy_locations:
  - name: my-app
    path: /Users/you/projects/my-app
    agents:
      - name: frontend
        source: official-agents
        version: "1.1.0"

Learn more about manifests

How They Work Together

Here's the complete flow:

text
1. Sources provide agents
   ~/cami-workspace/sources/official-agents/frontend.md
2. CAMI deploys agents to projects
   ~/projects/my-app/.claude/agents/frontend.md
3. Manifests track what's deployed
   ~/projects/my-app/.claude/cami-manifest.yaml (project level)
   ~/cami-workspace/deployments.yaml (central tracking)
4. Claude Code reads agents
   Claude sees agents in .claude/agents/ and follows their instructions

Priority-Based Deduplication

When multiple sources provide the same agent, CAMI uses priority to decide which wins.

IMPORTANT: Lower priority number = higher precedence

yaml
agent_sources:
  - name: my-agents
    priority: 10         # HIGHEST priority (wins over everything)
  - name: team-agents
    priority: 50         # MEDIUM priority (default)
  - name: official-agents
    priority: 100        # LOWEST priority (fallback)

Example: If "frontend" agent exists in all three sources:

  • my-agents/frontend.md (priority 10) is used
  • team-agents/frontend.md (priority 50) is ignored
  • official-agents/frontend.md (priority 100) is ignored

This ensures:

  • Personal customizations override everything (priority 10)
  • Team standards override official defaults (priority 50)
  • Official agents are fallback defaults (priority 100)

Deep dive into priority system

Version Tracking

CAMI tracks agent versions everywhere:

  • Source versions: What's available in each source
  • Deployed versions: What's actually in projects (via manifests)
  • Update detection: Which projects need updates

Example:

bash
# Check deployment status across projects
cami scan ~/projects/my-app
# Or via natural language
cd ~/cami-workspace
claude
> "Which projects need agent updates?"
# Claude uses mcp__cami__scan_deployed_agents

The Natural Language Interface

You interact with CAMI through natural conversation with Claude:

bash
cd ~/cami-workspace
claude
You: "Show me available agents"
Claude: *uses mcp__cami__list_agents*
You: "Deploy frontend and backend to ~/projects/my-app"
Claude: *uses mcp__cami__deploy_agents*
You: "Which sources do I have?"
Claude: *uses mcp__cami__list_sources*

Claude has access to 19 MCP tools that power CAMI. You never call them directly - just ask in natural language.

Complete MCP Tools API reference

Normalization

CAMI can normalize sources and projects to ensure they're properly configured:

Source Normalization (mcp__cami__normalize_source):

  • Ensures agents have valid frontmatter
  • Validates version numbers
  • Checks for STRATEGIES.yaml (optional tech stack guidance)
  • Creates backups before changes

Project Normalization (mcp__cami__normalize_project):

  • Creates .claude/ directory structure
  • Sets up manifest files (.claude/cami-manifest.yaml)
  • Links deployed agents to their sources
  • Updates central tracking

Learn about normalization

The CAMI Workspace

Everything lives in ~/cami-workspace/:

text
~/cami-workspace/
├── CLAUDE.md                    # CAMI documentation and Claude context
├── README.md                    # Quick start guide
├── .mcp.json                    # MCP server configuration (local)
├── .gitignore                   # Git ignore rules
├── config.yaml                  # CAMI configuration
├── .claude/
│   └── agents/                  # CAMI's own agents (agent-architect, etc.)
├── sources/                     # All agent sources
│   ├── official-agents/        # (if added)
│   ├── team-agents/            # (if added)
│   └── my-agents/              # Your custom agents

This single directory is your command center for all agent management.

Global MCP Setup (Optional)

By default, CAMI's MCP server is configured locally in ~/cami-workspace/.mcp.json.

To use CAMI from any Claude Code session:

Add to ~/.claude/settings.json:

json
{
  "mcpServers": {
    "cami": {
      "command": "cami",
      "args": ["--mcp"]
    }
  }
}

This makes CAMI's MCP tools available globally while still using sources configured in ~/cami-workspace/.

Next Steps

Now that you understand the concepts: