Skip to main content

Contributing

Thank you for your interest in contributing to the AgentOS Extensions ecosystem!

Getting Started​

  1. Fork the repository: https://github.com/framersai/agentos-extensions
  2. Clone your fork: 
    git clone https://github.com/yourusername/agentos-extensions
    cd agentos-extensions
    pnpm install
  3. Create a feature branch: 
    git checkout -b feat/my-extension

Creating a New Extension​

  1. Use the scaffolding script or copy a template:

    pnpm run create-extension
    # or
    cp -r templates/basic-tool registry/curated/category/my-extension

  2. Configure your extension:

    • Update package.json:
      • Set "name" to @framers/agentos-ext-{name}
      • Set "private": false
      • Add "publishConfig": { "access": "public" }
    • Update manifest.json with proper metadata
    • Implement tools in src/tools/

  3. Add to the workspace:

    • Add your package path to pnpm-workspace.yaml

  4. Follow the standards:

    • Use TypeScript with strict mode
    • Implement the ITool interface correctly
    • Include comprehensive tests (>80% coverage)
    • MIT license

Package Naming​

All extensions use the @framers/agentos-ext-{name} pattern:

PackageName
Auth@framers/agentos-ext-auth
Web Search@framers/agentos-ext-web-search
Web Browser@framers/agentos-ext-web-browser
Telegram@framers/agentos-ext-telegram
CLI Executor@framers/agentos-ext-cli-executor

Development​

Code Quality​

  • Linting: pnpm run lint
  • Type checking: pnpm run build
  • Testing: pnpm run test (maintain >80% coverage)
  • Documentation: Update README with examples

Testing Locally​

cd registry/curated/category/my-extension
pnpm test

Integration with AgentOS​

import { AgentOS } from '@framers/agentos';
import myExtension from '@framers/agentos-ext-my-extension';

const agentos = new AgentOS();
await agentos.initialize({
  extensionManifest: {
    packs: [{
      factory: () => myExtension({ /* options */ })
    }]
  }
});

Pull Request Process​

  1. Ensure all checks pass:

    pnpm test
    pnpm run lint
    pnpm run build

  2. Add a changeset describing your changes:

    pnpm changeset

    Select your package, choose the bump type (patch/minor/major), and describe the change.

  3. Create pull request with:

    • Title: feat: add [extension-name] extension
    • What the extension does
    • Configuration required
    • Example usage

  4. Automated CI checks will:

    • Validate extension structure
    • Run linting and tests on Node 18 & 20
    • Check test coverage
    • Build the extension
    • Security scanning

After Your PR is Merged​

Once merged to master:

  1. The Release workflow detects pending changesets
  2. A "chore: version packages" PR is auto-created with version bumps
  3. When that PR is merged, packages are published to npm
  4. GitHub releases are created with changelogs
  5. registry.json is updated

See RELEASING.md for the full publishing workflow.

Extension Guidelines​

Security​

  • Never hardcode API keys or secrets
  • Use environment variables for sensitive data
  • Validate all inputs
  • Handle errors gracefully

Performance​

  • Keep bundle size minimal
  • Use async/await properly
  • Implement timeouts for external calls
  • Cache results when appropriate

Compatibility​

  • Specify minimum AgentOS version in peerDependencies
  • Handle missing configuration gracefully
  • Provide sensible defaults

Getting Help​

License​

By contributing, you agree that your contributions will be licensed under the MIT License.