> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charmos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a Custom Adapter

Adapters connect agent frameworks to Charm's runner protocol (`invoke`, streaming, tools, errors).

> **Building a third-party plugin without forking Charm?** See [Custom Adapters](/guides/custom-adapters) (entry points + custom image). This page is for **core contributors** adding official adapters to the `charmos` package.

## When to add an adapter to core

Add to the SDK when the framework is widely used and should ship with official runner images and first-class docs. Niche or experimental integrations should stay as **entry-point plugins** in separate packages.

## Community plugin path (preferred for most authors)

1. Publish a pip package with `[project.entry-points."charm.adapters"]`
2. Ship a Docker image with that package installed
3. Set `runtime.custom_image` + `runtime.adapter.type` in `charm.yaml`

No changes to the Charm GitHub repo required.

## Core contributor path

1. Study the closest adapter in `src/charm/adapters/`
2. Implement `BaseAdapter`
3. Register in `pyproject.toml` under `[project.entry-points."charm.adapters"]`
4. Add/update Dockerfile if a dedicated runner image is needed
5. Add tests and adapter docs under `docs/adapters/`
6. Update `charm-community-plugin/templates/registry.json` if a new starter template is warranted

## Testing

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate path/to/example
charm run path/to/example --input "Hello"
charm run path/to/example --docker --input "Hello"
```

## Related

* [Extensibility Overview](/guides/extensibility)
* [Custom Adapters](/guides/custom-adapters)
* [Adapter overview](/adapters/overview)