Struct Manifest 

pub struct Manifest {

    pub sources: HashMap<String, String>,
    pub tools: Option<ToolsConfig>,
    pub agents: HashMap<String, ResourceDependency>,
    pub snippets: HashMap<String, ResourceDependency>,
    pub commands: HashMap<String, ResourceDependency>,
    pub mcp_servers: HashMap<String, ResourceDependency>,
    pub scripts: HashMap<String, ResourceDependency>,
    pub hooks: HashMap<String, ResourceDependency>,
    pub skills: HashMap<String, ResourceDependency>,
    pub patches: ManifestPatches,
    pub project_patches: ManifestPatches,
    pub private_patches: ManifestPatches,
    pub default_tools: HashMap<String, String>,
    pub project: Option<ProjectConfig>,
    pub manifest_dir: Option<PathBuf>,
    pub private_dependency_names: HashSet<(String, String)>,
    pub token_warning_threshold: Option<u64>,
    pub gitignore: bool,
}

Fields

sources: HashMap<String, String>

Named source repositories mapped to their Git URLs.

Keys are short, convenient names used in dependency specifications. Values are Git repository URLs (HTTPS, SSH, or local file:// URLs).

Security Note: Never include authentication tokens in these URLs. Use SSH keys or configure authentication in the global config file.

tools: Option<ToolsConfig>

Tool type configurations for multi-tool support.

Maps tool type names (claude-code, opencode, agpm, custom) to their installation configurations. This replaces the old target field and enables support for multiple tools and custom tool types.

See ToolsConfig for details on configuration format.

agents: HashMap<String, ResourceDependency>

Agent dependencies mapping names to their specifications.

Agents are typically AI model definitions, prompts, or behavioral specifications stored as Markdown files. Each dependency can be either local (filesystem path) or remote (from a Git source).

See ResourceDependency for specification format details.

snippets: HashMap<String, ResourceDependency>

Snippet dependencies mapping names to their specifications.

Snippets are typically reusable code templates, examples, or documentation stored as Markdown files. They follow the same dependency format as agents.

See ResourceDependency for specification format details.

commands: HashMap<String, ResourceDependency>

Command dependencies mapping names to their specifications.

Commands are Claude Code slash commands that provide custom functionality and automation within the Claude Code interface. They follow the same dependency format as agents and snippets.

See ResourceDependency for specification format details.

mcp_servers: HashMap<String, ResourceDependency>

MCP server configurations mapping names to their specifications.

MCP servers provide integrations with external systems and services, allowing Claude Code to connect to databases, APIs, and other tools. MCP servers are JSON configuration files that get installed to .mcp.json (no separate directory - configurations are merged into the JSON file).

See ResourceDependency for specification format details.

scripts: HashMap<String, ResourceDependency>

Script dependencies mapping names to their specifications.

Scripts are executable files (.sh, .js, .py, etc.) that can be run by hooks or independently. They are installed to .claude/scripts/ and can be referenced by hook configurations.

See ResourceDependency for specification format details.

hooks: HashMap<String, ResourceDependency>

Hook dependencies mapping names to their specifications.

Hooks are JSON configuration files that define event-based automation in Claude Code. They specify when to run scripts based on tool usage, prompts, and other events. Hook configurations are merged into settings.local.json.

See ResourceDependency for specification format details.

skills: HashMap<String, ResourceDependency>

Skill dependencies mapping names to their specifications.

Skills are directory-based resources (unlike single-file agents/snippets) that contain a SKILL.md file plus supporting files (scripts, templates, examples). They are installed to .claude/skills/<name>/ as complete directory structures.

See ResourceDependency for specification format details.

patches: ManifestPatches

Patches for overriding resource metadata.

Patches allow overriding YAML frontmatter fields (like model) in resources without forking upstream repositories. They are keyed by resource type and manifest alias.

project_patches: ManifestPatches

Project-level patches (from agpm.toml).

This field is not serialized - it’s populated during loading to track which patches came from the project manifest vs private config.

private_patches: ManifestPatches

Private patches (from agpm.private.toml).

This field is not serialized - it’s populated during loading to track which patches came from private config. These are kept separate from project patches to maintain deterministic lockfiles.

default_tools: HashMap<String, String>

Default tool overrides for resource types.

Allows users to override which tool is used by default when a dependency doesn’t explicitly specify a tool. Keys are resource type names (agents, snippets, commands, scripts, hooks, mcp-servers), values are tool names (claude-code, opencode, agpm, or custom tool names).

project: Option<ProjectConfig>

Project-specific template variables.

Custom project configuration that can be referenced in resource templates via Tera template syntax. This allows teams to define project-specific values like paths, standards, and conventions that are then available throughout all installed resources.

Template access: {{ agpm.project.name }}, {{ agpm.project.paths.style_guide }}

manifest_dir: Option<PathBuf>

Directory containing the manifest file (for resolving relative paths).

This field is populated when loading the manifest and is used to resolve relative paths in dependencies, particularly for path-only dependencies and their transitive dependencies.

This field is not serialized and only exists at runtime.

private_dependency_names: HashSet<(String, String)>

Names of dependencies that came from agpm.private.toml.

These dependencies will be installed to {resource_path}/private/ subdirectory and tracked in agpm.private.lock instead of agpm.lock.

This field is populated by load_with_private() when merging private dependencies. The HashSet contains (resource_type, name) pairs where resource_type is one of “agents”, “snippets”, “commands”, “scripts”, “hooks”, “mcp-servers”.

token_warning_threshold: Option<u64>

Token count warning threshold (project-level override).

Overrides the global token_warning_threshold for this project. When set, resources exceeding this threshold will emit a warning during installation.

Example:

token_warning_threshold = 50000  # 50k tokens

gitignore: bool

Whether to enable gitignore validation.

When true (default), AGPM validates that required .gitignore entries exist and warns if they’re missing. Set to false for private/personal setups where you don’t want gitignore management.

Example:

gitignore = false  # Disable gitignore validation

Implementations

impl Manifest

pub fn validate(&self) -> Result<()>

Validate the manifest structure and enforce business rules.

This method performs comprehensive validation of the manifest to ensure logical consistency, security best practices, and correct dependency relationships. It’s automatically called during Self::load but can also be used independently to validate programmatically constructed manifests.

Validation Rules

Source Validation

• All source URLs must use supported protocols (HTTPS, SSH, git://, file://)
• No plain directory paths allowed as sources (must use file:// URLs)
• No authentication tokens embedded in URLs (security check)
• Environment variable expansion is validated for syntax

Dependency Validation

• All dependency paths must be non-empty
• Remote dependencies must reference existing sources
• Remote dependencies must specify version constraints
• Local dependencies cannot have version constraints
• No version conflicts between dependencies with the same name within each resource type

Path Validation

• Local dependency paths are checked for proper format
• Remote dependency paths are validated as repository-relative
• Path traversal attempts are detected and rejected

Error Types

Returns specific error types for different validation failures:

• crate::core::AgpmError::SourceNotFound: Referenced source doesn’t exist
• crate::core::AgpmError::ManifestValidationError: General validation failures
• Context errors for specific issues with actionable suggestions

Examples

use agpm_cli::manifest::{Manifest, ResourceDependency};

let mut manifest = Manifest::new();
manifest.add_dependency(
    "local".to_string(),
    ResourceDependency::Simple("../local/helper.md".to_string()),
    true
);
assert!(manifest.validate().is_ok());

Security

Enforces: no credential leakage in URLs, no path traversal, valid URL schemes.

impl Manifest

A resource dependency specification supporting multiple formats.

Dependencies can be specified in two main formats to balance simplicity with flexibility. The enum uses Serde’s untagged attribute to automatically deserialize the correct variant based on the TOML structure.

Variants

Simple Dependencies

For local file dependencies, just specify the path directly:

Remote dependency with version

code-reviewer = { source = “official”, path = “agents/reviewer.md”, version = “v1.0.0” }

Remote dependency with git reference

experimental = { source = “community”, path = “agents/new.md”, git = “develop” }

Local dependency with explicit path (equivalent to simple form)

local-tool = { path = “../tools/agent.md” }

Validation Rules

• Local dependencies (no source): Cannot have version constraints
• Remote dependencies (with source): Must have either version or git field
• Path field: Required and cannot be empty
• Source field: Must reference an existing source in the [sources] section

Type Safety

The enum ensures type safety at compile time while providing runtime validation through the Manifest::validate method.

pub fn new() -> Self

Create a new empty manifest with default configuration.

The new manifest will have:

• No sources defined
• Default target directories (.claude/agents and .agpm/snippets)
• No dependencies

This is typically used when programmatically building a manifest or as a starting point for adding dependencies.

pub fn load(path: &Path) -> Result<Self>

Load and parse a manifest from a TOML file.

This method reads the specified file, parses it as TOML, deserializes it into a Manifest struct, and validates the result. The entire operation is atomic - either the manifest loads successfully or an error is returned.

Validation

After parsing, the manifest is automatically validated to ensure:

• All dependency sources reference valid entries in the [sources] section
• Required fields are present and non-empty
• Version constraints are properly specified for remote dependencies
• Source URLs use supported protocols
• No version conflicts exist between dependencies

Error Handling

Returns detailed errors for common problems:

• File I/O errors: File not found, permission denied, etc.
• TOML syntax errors: Invalid TOML format with helpful suggestions
• Validation errors: Logical inconsistencies in the manifest
• Security errors: Unsafe URL patterns or credential leakage

All errors include contextual information and actionable suggestions.

Ok::<(), anyhow::Error>(())

File Format

Expects a valid TOML file following the AGPM manifest format. See the module-level documentation for complete format specification.

pub fn load_with_private(path: &Path) -> Result<(Self, Vec<PatchConflict>)>

Load manifest with private config merged.

Loads the project manifest from agpm.toml and then attempts to load agpm.private.toml from the same directory. If a private config exists:

• Sources are merged (private sources can use same names, which shadows project sources)
• Dependencies are merged (private deps tracked via private_dependency_names)
• Patches are merged (private patches take precedence)

Any conflicts (same field defined in both files with different values) are returned for informational purposes only. Private patches always override project patches without raising an error.

Arguments

• path - Path to the project manifest file (agpm.toml)

Returns

A manifest with merged sources, dependencies, patches, and a list of any patch conflicts detected (for informational/debugging purposes).

pub fn get_default_tool(&self, resource_type: ResourceType) -> String

Get the default tool for a resource type.

Checks the [default-tools] configuration first, then falls back to the built-in defaults:

• snippets → "agpm" (shared infrastructure)
• All other resource types → "claude-code"

Arguments

• resource_type - The resource type to get the default tool for

Returns

The default tool name as a string.

pub fn save(&self, path: &Path) -> Result<()>

Save the manifest to a TOML file with pretty formatting.

This method serializes the manifest to TOML format and writes it to the specified file path. The output is pretty-printed for human readability and follows TOML best practices.

Formatting

The generated TOML file will:

• Use consistent indentation and spacing
• Omit empty sections for cleaner output
• Order sections logically (sources, target, agents, snippets)
• Include inline tables for detailed dependencies

Atomic Operation

The save operation is atomic - the file is either completely written or left unchanged. This prevents corruption if the operation fails partway through.

Error Handling

Returns detailed errors for common problems:

• Permission denied: Insufficient write permissions
• Directory doesn’t exist: Parent directory missing
• Disk full: Insufficient storage space
• File locked: Another process has the file open

use tempfile::tempdir;

let temp_dir = tempdir()?;

let manifest_path = temp_dir.path().join(“agpm.toml”);

manifest.save(&manifest_path)?;

Ok::<(), anyhow::Error>(())

Output Format

The generated file will follow this structure:

pub fn get_dependencies( &self, resource_type: ResourceType, ) -> Option<&HashMap<String, ResourceDependency>>

Get all dependencies from both agents and snippets sections.

Returns a vector of tuples containing dependency names and their specifications. This is useful for iteration over all dependencies without needing to handle agents and snippets separately.

Return Value

Each tuple contains:

• &str: The dependency name (key from TOML)
• &ResourceDependency: The dependency specification

Order

Dependencies are returned in the order they appear in the underlying HashMaps (agents first, then snippets, then commands), which means the order is not guaranteed to be stable across runs. Get dependencies for a specific resource type

Returns the HashMap of dependencies for the specified resource type. Note: MCP servers return None as they use a different dependency type.

pub fn get_dependencies_mut( &mut self, resource_type: ResourceType, ) -> Option<&mut HashMap<String, ResourceDependency>>

Get mutable dependencies for a specific resource type

Returns a mutable reference to the HashMap of dependencies for the specified resource type.

pub fn get_tools_config(&self) -> &ToolsConfig

Get the tools configuration, returning default if not specified.

This method provides access to the tool configurations which define where resources are installed for different tools (claude-code, opencode, agpm).

Returns the configured tools or the default configuration if not specified.

pub fn get_tool_config(&self, tool: &str) -> Option<&ArtifactTypeConfig>

Get configuration for a specific tool type.

Returns None if the tool is not configured.

pub fn get_artifact_resource_path( &self, tool: &str, resource_type: ResourceType, ) -> Option<PathBuf>

Get the installation path for a resource within a tool.

Returns the full installation directory path by combining:

• Tool’s base directory (e.g., “.claude”, “.opencode”)
• Resource type’s subdirectory (e.g., “agents”, “command”)

Returns None if:

• The tool is not configured
• The resource type is not supported by this tool
• The resource has no configured path (special handling like MCP merge)

pub fn get_merge_target( &self, tool: &str, resource_type: ResourceType, ) -> Option<PathBuf>

Get the merge target configuration file path for a resource type.

Returns the path to the configuration file where resources of this type should be merged (e.g., hooks, MCP servers). Returns None if the resource type doesn’t use merge targets or if the tool doesn’t support this resource type.

Arguments

• tool - The tool name (e.g., “claude-code”, “opencode”)
• resource_type - The resource type to look up

Returns

The merge target path if configured, otherwise None.

pub fn is_resource_supported( &self, tool: &str, resource_type: ResourceType, ) -> bool

Check if a resource type is supported by a tool.

A resource type is considered supported if it has either:

• A configured installation path (for file-based resources)
• A configured merge target (for resources that merge into config files)

Returns true if the tool has valid configuration for the given resource type.

pub fn all_dependencies(&self) -> Vec<(&str, &ResourceDependency)>

Returns all dependencies from all resource types.

This method collects dependencies from agents, snippets, commands, scripts, hooks, and MCP servers into a single vector. It’s commonly used for:

• Manifest validation across all dependency types
• Dependency resolution operations
• Generating reports of all configured dependencies
• Bulk operations on all dependencies

Returns

A vector of tuples containing the dependency name and its configuration. Each tuple is (name, dependency) where:

• name: The dependency name as specified in the manifest
• dependency: Reference to the ResourceDependency configuration

The order follows the resource type order defined in crate::core::ResourceType::all().

use agpm_cli::manifest::Manifest;

let manifest = Manifest::new();

for (name, dep) in manifest.all_dependencies() { println!(“Dependency: {} -> {}”, name, dep.get_path()); if let Some(source) = dep.get_source() { println!(“ Source: {}“, source); } }

pub fn all_dependencies_with_mcp( &self, ) -> Vec<(&str, Cow<'_, ResourceDependency>)>

Get all dependencies including MCP servers.

All resource types now use standard ResourceDependency, so no conversion needed.

pub fn all_dependencies_with_types( &self, ) -> Vec<(&str, Cow<'_, ResourceDependency>, ResourceType)>

Get all dependencies with their resource types.

Returns a vector of tuples containing the dependency name, dependency details, and the resource type. This preserves type information that is lost in all_dependencies_with_mcp().

This is used by the resolver to correctly type transitive dependencies without falling back to manifest section order lookups.

Dependencies for disabled tools are automatically filtered out.

pub fn has_dependency(&self, name: &str) -> bool

Check if a dependency with the given name exists in any section.

Searches the [agents], [snippets], and [commands] sections for a dependency with the specified name. This is useful for avoiding duplicate names across different resource types.

Performance

This method performs up to three HashMap lookups, so it’s O(1) on average.

Examples

let manifest = Manifest::new();
if manifest.has_dependency("my-agent") {
    println!("Dependency exists!");
}

pub fn get_dependency(&self, name: &str) -> Option<&ResourceDependency>

Get a dependency by name from any section.

Searches the [agents], [snippets], and [commands] sections for a dependency with the specified name, returning the first match found.

Search Order

Dependencies are searched in this order:

1. [agents] section
2. [snippets] section
3. [commands] section

If the same name exists in multiple sections, the first match is returned.

Examples

let manifest = Manifest::new();
if let Some(dep) = manifest.get_dependency("my-agent") {
    println!("Found dependency!");
}

pub fn find_dependency(&self, name: &str) -> Option<&ResourceDependency>

Find a dependency by name from any section (alias for get_dependency).

Searches the [agents], [snippets], and [commands] sections for a dependency with the specified name, returning the first match found.

Examples

let manifest = Manifest::new();
if let Some(dep) = manifest.find_dependency("my-agent") {
    println!("Found dependency!");
}

pub fn add_source(&mut self, name: String, url: String)

Add or update a source repository in the [sources] section.

Sources map convenient names to Git repository URLs. These names can then be referenced in dependency specifications to avoid repeating long URLs throughout the manifest.

Parameters

• name: Short, convenient name for the source (e.g., “official”, “community”)
• url: Git repository URL (HTTPS, SSH, or file:// protocol)

URL Validation

The URL is not validated when added - validation occurs during Self::validate. Supported URL formats:

• https://github.com/owner/repo.git
• git@github.com:owner/repo.git
• file:///absolute/path/to/repo
• file:///path/to/local/repo

Security Note

Never include authentication tokens in the URL. Use SSH keys or configure authentication globally in ~/.agpm/config.toml.

pub fn add_dependency( &mut self, name: String, dep: ResourceDependency, is_agent: bool, )

Add or update a dependency in the appropriate section.

Adds the dependency to either the [agents] or [snippets] section based on the is_agent parameter. If a dependency with the same name already exists in the target section, it will be replaced.

For commands and other resource types, use Self::add_typed_dependency which provides explicit control over resource types.

Parameters

• name: Unique name for the dependency within its section
• dep: The dependency specification (Simple or Detailed)
• is_agent: If true, adds to [agents]; if false, adds to [snippets]

Validation

The dependency is not validated when added - validation occurs during Self::validate. This allows for building manifests incrementally before all sources are defined.

Name Conflicts

This method allows the same dependency name to exist in both the [agents] and [snippets] sections. However, some operations like Self::get_dependency will prefer agents over snippets when searching by name.

pub fn add_typed_dependency( &mut self, name: String, dep: ResourceDependency, resource_type: ResourceType, )

Add or update a dependency with specific resource type.

This is the preferred method for adding dependencies as it explicitly specifies the resource type using the ResourceType enum.

use agpm_cli::manifest::{Manifest, ResourceDependency};
use agpm_cli::core::ResourceType;

let mut manifest = Manifest::new();

pub fn get_resources( &self, resource_type: &ResourceType, ) -> &HashMap<String, ResourceDependency>

Get resource dependencies by type.

Returns a reference to the HashMap of dependencies for the specified resource type. This provides a unified interface for accessing different resource collections, similar to LockFile::get_resources().

use agpm_cli::manifest::Manifest;
use agpm_cli::core::ResourceType;

pub fn all_resources(&self) -> Vec<(ResourceType, &str, &ResourceDependency)>

Get all resource dependencies across all types.

Returns a vector of tuples containing the resource type, manifest key (name), and the dependency specification. This provides a unified way to iterate over all resources regardless of type.

Returns

A vector of (ResourceType, &str, &ResourceDependency) tuples where:

• The first element is the type of resource (Agent, Snippet, etc.)
• The second element is the manifest key (the name in the TOML file)
• The third element is the resource dependency specification

pub fn add_mcp_server(&mut self, name: String, dependency: ResourceDependency)

Add or update an MCP server configuration.

MCP servers now use standard ResourceDependency format, pointing to JSON configuration files in source repositories.

use agpm_cli::manifest::{Manifest, ResourceDependency};

let mut manifest = Manifest::new();

pub fn compute_dependency_hash(&self) -> String

Compute a hash of all manifest dependency specifications.

This hash is used for fast path detection during subsequent installs. If the hash matches the one stored in the lockfile, and there are no mutable dependencies, we can skip resolution entirely.

The hash includes:

• All source definitions (name + URL)
• All dependency specifications (serialized to canonical JSON)
• Patch configurations
• Tools configuration

Returns

A SHA-256 hash string in “sha256:hex” format

Determinism

Direct serde_json::to_string() on structs with HashMaps produces non-deterministic output because HashMap iteration order varies between runs. We use the two-step to_value() then to_string() approach because serde_json::Map (used internally by Value) is backed by BTreeMap when preserve_order is disabled (our default), which keeps keys sorted. See: https://docs.rs/serde_json/latest/serde_json/struct.Map.html

Stability

The hash format is stable across AGPM versions within the same major version. Changes to hash computation require a lockfile format version bump and migration strategy to ensure existing lockfiles continue to work correctly.

pub fn has_mutable_dependencies(&self) -> bool

Check if any dependencies are mutable (local files or branches).

Mutable dependencies can change between installs without manifest changes:

• Local sources: Files on disk can change at any time
• Branch references: Git branches can be updated

When mutable dependencies exist, the fast path cannot be used because we must re-validate that the content hasn’t changed.

Returns

• true if any dependency uses a local source or branch reference
• false if all dependencies use immutable references (semver tags, pinned SHAs)

pub fn is_private_dependency(&self, resource_type: &str, name: &str) -> bool

Check if a dependency is from the private manifest (agpm.private.toml).

Private dependencies:

• Install to {resource_path}/private/ subdirectory
• Are tracked in agpm.private.lock instead of agpm.lock
• Don’t affect team lockfile consistency

Arguments

• resource_type - The resource type (accepts both singular “agent” and plural “agents”)
• name - The dependency name as specified in the manifest

Returns

true if the dependency came from agpm.private.toml, false otherwise.

Trait Implementations

impl Clone for Manifest

fn clone(&self) -> Manifest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Manifest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Manifest

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Manifest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Manifest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.