Module install

agpm_cli::cli

Module install 

Source
Expand description

Install Claude Code resources from manifest dependencies.

This module provides the install command which reads dependencies from the agpm.toml manifest file, resolves them, and installs the resource files to the project directory. The command supports both fresh installations and updates to existing installations with advanced parallel processing capabilities.

§Features

  • Dependency Resolution: Resolves all dependencies defined in the manifest
  • Transitive Dependencies: Automatically discovers and installs dependencies declared in resource files
  • Lockfile Management: Generates and maintains agpm.lock for reproducible builds
  • Worktree-Based Parallel Installation: Uses Git worktrees for safe concurrent resource installation
  • Multi-Phase Progress Tracking: Shows detailed progress with phase transitions and real-time updates
  • Resource Validation: Validates markdown files and content during installation
  • Cache Support: Advanced cache with instance-level optimizations and worktree management
  • Concurrency Control: User-configurable parallelism via --max-parallel flag
  • Cycle Detection: Prevents circular dependency loops in transitive dependency graphs

§Examples

Install all dependencies from manifest:

agpm install

Force reinstall all dependencies:

agpm install --force

Install without creating lockfile:

agpm install --no-lock

Use frozen lockfile (CI/production):

agpm install --frozen

Disable cache and clone fresh:

agpm install --no-cache

Install only direct dependencies (skip transitive):

agpm install --no-transitive

Preview installation without making changes:

agpm install --dry-run

§Installation Process

  1. Manifest Loading: Reads agpm.toml to understand dependencies
  2. Source Synchronization: Clones/fetches Git repositories for all sources
  3. Dependency Resolution: Resolves versions and creates dependency graph
  4. Transitive Discovery: Extracts dependencies from resource files (YAML/JSON metadata)
  5. Cycle Detection: Validates dependency graph for circular references
  6. Worktree Preparation: Pre-creates Git worktrees for optimal parallel access
  7. Parallel Resource Installation: Installs resources concurrently using isolated worktrees
  8. Progress Coordination: Updates multi-phase progress tracking throughout installation
  9. Configuration Updates: Updates hooks and MCP server configurations as needed
  10. Lockfile Generation: Creates or updates agpm.lock with checksums and metadata
  11. Artifact Cleanup: Removes old artifacts from removed or relocated dependencies

§Error Conditions

  • No manifest file found in project
  • Invalid manifest syntax or structure
  • Dependency resolution conflicts
  • Circular dependency loops detected
  • Invalid transitive dependency metadata (malformed YAML/JSON)
  • Network or Git access issues
  • File system permissions or disk space issues
  • Invalid resource file format

§Performance

The install command is optimized for maximum performance:

  • Worktree-based parallelism: Each dependency gets its own isolated Git worktree
  • Instance-level caching: Optimized worktree reuse within command execution
  • Configurable concurrency: --max-parallel flag controls dependency-level parallelism
  • Pre-warming strategy: Creates all needed worktrees upfront for optimal parallel access
  • Atomic file operations: Safe, corruption-resistant file installation
  • Multi-phase progress: Real-time progress updates with phase transitions

§Optimization Tiers

The install command uses a tiered optimization strategy for repeated installations:

  1. Fast Path (skip resolution): When the manifest hash matches and all dependencies are immutable (Git-based with tags/SHAs), the entire resolution phase is skipped. The lockfile is used directly as the installation plan.

    • Triggered by: manifest_hash match + has_mutable_deps = false + valid resource_count
    • Saves: Network fetches, version resolution, transitive dependency discovery

  2. Ultra-Fast Path (skip checksum computation): For each resource being installed, if all content-affecting inputs match the previous lockfile entry (commit, path, patches, template vars) and the file exists, skip reading and hashing the file.

    • Triggered by: trust_lockfile_checksums = true + all inputs match old entry
    • Saves: File I/O, SHA-256 computation (significant for large files)

  3. Trust Mode: Within ultra-fast path, when a resource’s inputs match exactly, the previous checksum is reused without verification. This is safe because immutable Git dependencies (tags/SHAs) guarantee identical content.

§Security Considerations

Trust mode assumes:

  • Upstream repositories have not been compromised (tag force-push attacks)
  • The local cache (~/.agpm/cache/) has not been tampered with

For security-sensitive environments, consider:

  • Using --no-cache to always fetch fresh content
  • Modifying the manifest to force re-resolution (e.g., bumping version)
  • Regularly auditing installed resources against known-good checksums

Structs§

InstallCommand
Command to install Claude Code resources from manifest dependencies.