spectrum-ts

About Photon

Photon builds infrastructure for AI agents that operate over real communication channels.

Spectrum is Photon’s open-source multi-channel agent framework, enabling AI agents to communicate through interfaces people already use—such as iMessage, SMS, email, Slack, Discord, and voice—instead of being confined to web chat.

Learn more at https://photon.codes.

Getting Started

The fastest way to ship is with Spectrum Cloud — hosted infrastructure for platforms like iMessage, with credentials ready in minutes.

1. Sign up at app.photon.codes to get your project ID and secret.

2. Install the SDK (spectrum-ts is batteries-included — the runtime plus the standard provider set):

   bun add spectrum-ts
   

3. Start your app:

   import { Spectrum } from "spectrum-ts";
   import { imessage } from "spectrum-ts/providers/imessage";
   
   const app = await Spectrum({
     projectId: process.env.PROJECT_ID,
     projectSecret: process.env.PROJECT_SECRET,
     providers: [imessage.config()],
   });
   
   for await (const [space, message] of app.messages) {
     await space.responding(async () => {
       await message.reply("Hello from Spectrum.");
     });
   }
   

Spectrum also runs fully standalone — you can connect to a local iMessage database with the separate @spectrum-ts/imessage-local package, bring your own gRPC endpoints, or build your own platform provider. See the docs for self-hosted setups.

Documentation

Visit docs.photon.codes to view the full documentation.

Platforms

bun add spectrum-ts is batteries-included (the standard provider set; local iMessage is an explicit install). For a smaller install, depend on the runtime plus only the providers you use — bun add @spectrum-ts/core @spectrum-ts/telegram — and import from the scoped packages directly. Either way the spectrum-ts/providers/ import paths work as long as the matching provider package is installed; if it isn't, the import fails at build/startup naming the exact package to add.

Issues

Found a bug or have a feature request? Please open an issue on GitHub. Before filing, search existing issues to avoid duplicates.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

MIT © Photon