Struct DetailedDependency 

pub struct DetailedDependency {

    pub source: Option<String>,
    pub path: String,
    pub version: Option<String>,
    pub branch: Option<String>,
    pub rev: Option<String>,
    pub command: Option<String>,
    pub args: Option<Vec<String>>,
    pub target: Option<String>,
    pub filename: Option<String>,
    pub dependencies: Option<HashMap<String, Vec<DependencySpec>>>,
    pub tool: Option<String>,
    pub flatten: Option<bool>,
    pub install: Option<bool>,
    pub template_vars: Option<Value>,
}

Detailed dependency specification with full control over source resolution.

This struct provides fine-grained control over dependency specification, supporting both local filesystem paths and remote Git repository resources with flexible version constraints and Git reference handling.

Field Relationships

The fields work together with specific validation rules:

• If source is specified: Must have either version or git
• If source is omitted: Dependency is local, version and git are ignored
• path is always required and cannot be empty

Examples

Remote Dependencies

[agents]
# Semantic version constraint
stable = { source = "official", path = "agents/stable.md", version = "v1.0.0" }

# Latest version (not recommended for production)
latest = { source = "community", path = "agents/utils.md", version = "latest" }

# Specific Git branch
cutting-edge = { source = "official", path = "agents/new.md", git = "develop" }

# Specific commit SHA (maximum reproducibility)
pinned = { source = "community", path = "agents/tool.md", git = "a1b2c3d4e5f6..." }

# Git tag
release = { source = "official", path = "agents/release.md", git = "v2.0-release" }

Local Dependencies

[agents]
# Local file (version/git fields ignored if present)
local-helper = { path = "../shared/helper.md" }
custom = { path = "./local/custom.md" }

Version Resolution Priority

When both version and git are specified, git takes precedence:

# This will use the "develop" branch, not "v1.0.0"
conflicted = { source = "repo", path = "file.md", version = "v1.0.0", git = "develop" }

Path Format

Paths are interpreted differently based on context:

• Remote dependencies: Path within the Git repository
• Local dependencies: Filesystem path relative to manifest directory

Fields

source: Option<String>

Source repository name referencing the [sources] section.

When specified, this dependency will be resolved from a Git repository. The name must exactly match a key in the manifest’s [sources] table.

Omit this field to create a local filesystem dependency.

Examples

# References this source definition:
[sources]
official = "https://github.com/org/repo.git"

[agents]
remote-agent = { source = "official", path = "agents/tool.md", version = "v1.0.0" }
local-agent = { path = "../local/tool.md" }  # No source = local dependency

path: String

Path to the resource file or glob pattern for multiple resources.

For remote dependencies: Path within the Git repository
For local dependencies: Filesystem path relative to manifest directory
For pattern dependencies: Glob pattern to match multiple resources

This field supports both individual file paths and glob patterns:

• Individual file: "agents/helper.md"
• Pattern matching: "agents/*.md", "**/*.md", "agents/[a-z]*.md"

Pattern dependencies are detected by the presence of glob characters (*, ?, [) in the path. When a pattern is detected, AGPM will expand it to match all resources in the source repository.

Examples

# Remote: single file in git repo
remote = { source = "repo", path = "agents/helper.md", version = "v1.0.0" }

# Local: filesystem path
local = { path = "../shared/helper.md" }

# Pattern: all agents in AI folder
ai_agents = { source = "repo", path = "agents/ai/*.md", version = "v1.0.0" }

# Pattern: all agents recursively
all_agents = { source = "repo", path = "agents/**/*.md", version = "v1.0.0" }

version: Option<String>

Version constraint for Git tag resolution.

Specifies which version of the resource to use when resolving from a Git repository. This field is ignored for local dependencies.

Note: If both version and git are specified, git takes precedence.

Supported Formats

• "v1.0.0" - Exact semantic version tag
• "1.0.0" - Exact version (v prefix optional)
• "^1.0.0" - Semantic version constraint (highest compatible 1.x.x)
• "latest" - Git tag or branch named “latest” (not special - just a name)
• "main" - Use main/master branch HEAD

Examples

[agents]
stable = { source = "repo", path = "agent.md", version = "v1.0.0" }
flexible = { source = "repo", path = "agent.md", version = "^1.0.0" }
latest-tag = { source = "repo", path = "agent.md", version = "latest" }  # If repo has a "latest" tag
main = { source = "repo", path = "agent.md", version = "main" }

branch: Option<String>

Git branch to track.

Specifies a Git branch to use when resolving the dependency. Branch references are mutable and will update to the latest commit on each update. This field is ignored for local dependencies.

Examples

[agents]
# Track the main branch
dev = { source = "repo", path = "agent.md", branch = "main" }

# Track a feature branch
experimental = { source = "repo", path = "agent.md", branch = "feature/new-capability" }

rev: Option<String>

Git commit hash (revision).

Specifies an exact Git commit to use when resolving the dependency. Provides maximum reproducibility as commits are immutable. This field is ignored for local dependencies.

Examples

[agents]
# Pin to exact commit (full hash)
pinned = { source = "repo", path = "agent.md", rev = "a1b2c3d4e5f67890abcdef1234567890abcdef12" }

# Pin to exact commit (abbreviated)
stable = { source = "repo", path = "agent.md", rev = "abc123def" }

command: Option<String>

Command to execute for MCP servers.

This field is specific to MCP server dependencies and specifies the command that will be executed to run the MCP server. Only used for entries in the [mcp-servers] section.

Examples

[mcp-servers]
github = { source = "repo", path = "mcp/github.toml", version = "v1.0.0", command = "npx" }
sqlite = { path = "./local/sqlite.toml", command = "uvx" }

args: Option<Vec<String>>

Arguments to pass to the MCP server command.

This field is specific to MCP server dependencies and provides the arguments that will be passed to the command when starting the MCP server. Only used for entries in the [mcp-servers] section.

Examples

[mcp-servers]
github = {
    source = "repo",
    path = "mcp/github.toml",
    version = "v1.0.0",
    command = "npx",
    args = ["-y", "@modelcontextprotocol/server-github"]
}
sqlite = {
    path = "./local/sqlite.toml",
    command = "uvx",
    args = ["mcp-server-sqlite", "--db", "./data/local.db"]
}

target: Option<String>

Custom target directory for this dependency.

Overrides the default installation directory for this specific dependency. The path is relative to the .claude directory for consistency and security. If not specified, the dependency will be installed to the default location based on its resource type.

Examples

[agents]
# Install to .claude/custom/tools/ instead of default .claude/agents/
special-agent = {
    source = "repo",
    path = "agent.md",
    version = "v1.0.0",
    target = "custom/tools"
}

# Install to .claude/integrations/ai/
integration = {
    source = "repo",
    path = "integration.md",
    version = "v2.0.0",
    target = "integrations/ai"
}

filename: Option<String>

Custom filename for this dependency.

Overrides the default filename (which is based on the dependency key). The filename should include the desired file extension. If not specified, the dependency will be installed using the key name with an automatically determined extension based on the resource type.

Examples

[agents]
# Install as "ai-assistant.md" instead of "my-ai.md"
my-ai = {
    source = "repo",
    path = "agent.md",
    version = "v1.0.0",
    filename = "ai-assistant.md"
}

# Install with a different extension
doc-agent = {
    source = "repo",
    path = "documentation.md",
    version = "v2.0.0",
    filename = "docs-helper.txt"
}

[scripts]
# Rename a script during installation
analyzer = {
    source = "repo",
    path = "scripts/data-analyzer-v3.py",
    version = "v1.0.0",
    filename = "analyze.py"
}

dependencies: Option<HashMap<String, Vec<DependencySpec>>>

Transitive dependencies on other resources.

This field is populated from metadata extracted from the resource file itself (YAML frontmatter in .md files or JSON fields in .json files). Maps resource type to list of dependency specifications.

Example:

# This would be extracted from the file's frontmatter/JSON, not specified in agpm.toml
# { "agents": [{"path": "agents/helper.md", "version": "v1.0.0"}] }

tool: Option<String>

Tool type (claude-code, opencode, agpm, or custom).

Specifies which target AI coding assistant tool this resource is for. This determines where the resource is installed and how it’s configured.

When None, defaults are applied based on resource type:

• Snippets default to “agpm” (shared infrastructure)
• All other resources default to “claude-code”

Omitted from TOML serialization when not specified.

flatten: Option<bool>

Control directory structure preservation during installation.

When true, only the filename is used for installation (e.g., nested/dir/file.md → file.md). When false, the full relative path is preserved (e.g., nested/dir/file.md → nested/dir/file.md).

Default values by resource type (from tool configuration):

• agents: true (flatten by default - no nested directories)
• commands: true (flatten by default - no nested directories)
• All others: false (preserve directory structure)

Examples

[agents]
# Default behavior (flatten=true) - installs as "helper.md"
agent1 = { source = "repo", path = "agents/subdir/helper.md", version = "v1.0.0" }

# Preserve structure - installs as "subdir/helper.md"
agent2 = { source = "repo", path = "agents/subdir/helper.md", version = "v1.0.0", flatten = false }

[snippets]
# Default behavior (flatten=false) - installs as "utils/helper.md"
snippet1 = { source = "repo", path = "snippets/utils/helper.md", version = "v1.0.0" }

# Flatten - installs as "helper.md"
snippet2 = { source = "repo", path = "snippets/utils/helper.md", version = "v1.0.0", flatten = true }

install: Option<bool>

Control whether the dependency should be installed to disk.

When false, the dependency is resolved, fetched, and tracked in the lockfile, but the file is not written to the project directory. Instead, its content is made available in template context via agpm.deps.<type>.<name>.content.

This is useful for snippet embedding use cases where you want to include content inline rather than as a separate file.

Defaults to true (install the file).

Examples

[snippets]
# Embed content directly without creating a file
best_practices = {
    source = "repo",
    path = "snippets/rust-best-practices.md",
    version = "v1.0.0",
    install = false
}

Then use in template:

{{ agpm.deps.snippets.best_practices.content }}

template_vars: Option<Value>

Template variable overrides for this specific resource.

Allows specializing generic resources for different use cases by overriding template variables. These variables are merged with (and take precedence over) the global [project] configuration when rendering this resource and resolving its transitive dependencies.

This enables creating multiple variants of the same resource without duplication. For example, a single backend-engineer.md agent can be specialized for different languages by providing different template_vars for each variant.

The structure matches the template namespace hierarchy (e.g., { "project": { "language": "golang" } }).

Examples

[agents]
# Generic backend engineer agent specialized for different languages
backend-engineer-golang = {
    source = "community",
    path = "agents/backend-engineer.md",
    version = "v1.0.0",
    filename = "backend-engineer-golang.md",
    template_vars = { project = { language = "golang" } }
}

backend-engineer-python = {
    source = "community",
    path = "agents/backend-engineer.md",
    version = "v1.0.0",
    filename = "backend-engineer-python.md",
    template_vars = { project = { language = "python", framework = "fastapi" } }
}

The agent at agents/backend-engineer.md can use templates like:

# Backend Engineer for {{ agpm.project.language }}

---
dependencies:
  snippets:
    - path: ../best-practices/{{ agpm.project.language }}-best-practices.md
---

Each variant will resolve its transitive dependencies using its specific template_vars, so the golang variant resolves golang-best-practices.md while python resolves python-best-practices.md.

Trait Implementations

impl Clone for DetailedDependency

fn clone(&self) -> DetailedDependency

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DetailedDependency

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for DetailedDependency

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for DetailedDependency

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

where __S: Serializer,

Serialize this value into the given Serde serializer.