soulsteads-agent-messaging

Your coding agent. Your chat app. Easy setup. No BS.
Talk to Claude Code, Codex, OpenCode, or Pi from the messaging app you already use.

Why this bridge?

The bridge runs on your machine and connects your messages to the agent you
choose, using your own chat account and the agent you already have signed in.

What works with it?

[!NOTE]
Only Telegram has a guided setup, for Claude Code or Codex on Linux.
Other platforms and agents need manual configuration. Connectors are included,
not preconfigured; each needs its own credentials. This is an early 0.2.0
release, not a promise that every combination has been tested live.

Get started

The easy way: ask your agent

Setting this up is a conversation, not a project. Open Claude Code, Codex,
OpenCode, Pi, or any agent that can run commands, paste the prompt below, and
answer its questions. Your agent builds the bridge, writes the configuration and
installs the service; you only supply the bot token, in a private file.

Set up Soulsteads Agent Messaging so I can talk to you from my chat app.

1. Clone https://github.com/soulsteads/soulsteads-agent-messaging (branch
   `release`) unless you are already inside it.
2. Read README.md and docs/SETUP.md, and use the setup-soulsteads-messaging
   skill if you have it.
3. Ask me which chat app to use (Telegram has a guided setup) and which agent
   to connect.
4. Build it, configure it, and install it as a service. Ask me before you start
   the service or change anything outside the checkout.
5. Never ask me to paste a token into chat. Tell me where to save it in a
   private file, then read it from there.
6. Finish by telling me what to send from my chat app to check it works.

Your agent still needs permission to run commands, and only Telegram can be set
up this way end to end. For the other platforms it follows the manual steps in
the setup guide.

Or set it up yourself

Setup for every platform is in the setup guide.

Credentials go in an environment file; .env.example lists every
variable the bridge reads.

Use a preconfigured agent directory

If your agent already has a working directory with its normal instructions and
configuration, select a runtime and set acp.agentHome to that existing absolute
or ~/… path. New sessions run there directly instead of receiving copied profile
files:

{
  "acp": {
    "defaultBackend": "codex",
    "agentHome": "~/.soulsteads/agents/helper"
  }
}

See the setup guide for backend
overrides, validation, and migration behavior.

Know before you connect

[!CAUTION]
Your agent keeps its machine permissions. This bridge is not a sandbox. Use
an account and workspace you are comfortable giving the agent access to.

Development checks

Run cargo build --locked and cargo test --locked for the self-contained Rust
build and test suite used by public CI. Tests that execute the historical
TypeScript implementation require a separately supplied reference and Bun;
see reference conformance tests for the explicit
reference-conformance opt-in. No private reference checkout is needed for the
default tests.

For the optional in-process agent-request API and its test coverage and
limitations, see API qualification.

Connector implementations live under src/connectors/; Matrix-specific modules
are grouped under src/connectors/matrix/. Connector unit-test bodies live under
tests/connectors/ and are included as test-only modules so they can exercise
private helpers without expanding the production API. They run with cargo test --locked --lib; the other root-level test files remain integration tests.

More documentation

Run ./target/release/soulsteads-messaging --help for command-line options.

License

Licensed under the Apache License 2.0.