Contributing¶

Amplifier is an experimental platform with a multi-repository ecosystem. Contributing typically means creating your own repositories rather than submitting PRs to a monolithic codebase.

Understanding the Ecosystem¶

Amplifier's architecture is modular by design:

Core kernel (amplifier-core) - Small, stable, boring. High bar for changes.
CLI application (amplifier-app-cli) - Reference CLI for building and validating new capabilities. Not user-focused.
Reference implementations - Canonical examples for each module type and application pattern
Community ecosystem - Your own modules, tools, apps, and collections

Reference vs. Official

Current modules and apps are reference implementations, not "official" requirements. You can build alternatives, improvements, or entirely new capabilities. Users choose what to install based on their needs.

See the Showcase for examples of what the community has built.

Choose Your Contribution Type¶

Applications¶

Full CLI applications built on Amplifier's kernel and libraries.

Getting Started:

Browse the Showcase for application examples
Clone a reference app closest to your idea
Study the structure and patterns
Create your own repo: amplifier-app-yourname
Build your application
Publish and add back to the Showcase

Learn More: Developer Guide

Modules¶

Extend Amplifier's runtime capabilities. Modules are loaded dynamically based on profile configuration.

Providers¶

LLM backend integrations.

Reference Implementations: - provider-anthropic - provider-openai - provider-mock - Minimal testing reference

Contract: Provider Contract | Examples: Showcase

Tools¶

Agent capabilities for interacting with systems and data.

Reference Implementations: - tool-filesystem - tool-bash - tool-web

Contract: Tool Contract | Examples: Showcase

Orchestrators¶

Control execution flow and conversation loops.

Reference Implementations: - orchestrator-loop-basic - orchestrator-loop-streaming - orchestrator-loop-events

Contract: Orchestrator Contract | Examples: Showcase

Contexts¶

Manage conversation memory and state.

Reference Implementations: - context-simple - context-persistent

Contract: Context Contract | Examples: Showcase

Hooks¶

Observe, guide, and control agent behavior.

Reference Implementations: - hook-logging - hook-approval - hook-redaction

Contract: Hook Contract | Examples: Showcase

Collections¶

Package agents, context files, and philosophy documents for specific workflows.

Reference Implementations: - collection-toolkit - collection-design-intelligence - collection-recipes

Learn More: Collections Guide | Examples: Showcase

The Contribution Process¶

1. Choose What to Build¶

Pick an application, module type, or collection that interests you.

2. Find Your Starting Point¶

Look at reference implementations or community examples closest to your idea. Clone or fork as a starting point.

Reference Implementations

Some module types have special reference implementations designed for learning:

provider-mock - Minimal provider for testing
Most official modules serve as production-ready references

3. Create Your Repository¶

Follow naming conventions:

Applications: amplifier-app-{name}
Modules: amplifier-module-{type}-{name}
Collections: amplifier-collection-{name}

4. Build Following Contracts¶

Each module type has a contract defining the interface. Follow it so your module works with the kernel.

See: Developer Contracts

5. Test Thoroughly¶

Test with current Amplifier versions
Ensure your module works in isolation
Verify integration with other modules
Document any dependencies

6. Publish to GitHub¶

Make your code publicly reviewable. Include:

Comprehensive README
Installation instructions
Usage examples
Tests
License (typically MIT)

7. Add to Showcase¶

Submit a PR to add your project to the Showcase catalog.

What NOT to Contribute To¶

❌ amplifier-core (The Kernel)¶

The kernel has an extremely high bar for changes:

Must be backward compatible
Requires ≥2 modules to justify new features
Needs spec-first design
Complete test coverage required
If you think you need to change the kernel, you probably don't

Instead: Build a module that works within existing contracts.

⚠️ amplifier-app-cli¶

The reference CLI is used by the core team to build and validate new capabilities. It changes frequently to adopt new features, stays lean to adapt quickly, and is not focused on user experience. Not a good place for easy first issues or incremental improvements.

Instead: Build your own application, use hooks to modify behavior, or package workflows as collections.

Security Considerations¶

Critical Security Warning

Modules and applications execute arbitrary code with full system access. Users must review code before installation. Build with security in mind:

Validate all inputs
Handle credentials safely
Document security implications
Never include hardcoded secrets