Show HN: Relaymux, a tmux-based meta-harness for local coding agents

Notifications You must be signed in to change notification settings

Fork 0

Star 5

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

31 Commits

31 Commits

.github/workflows

.github/workflows

bin

bin

docs

docs

examples

examples

scripts

scripts

src

src

test

test

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

install.sh

install.sh

package-lock.json

package-lock.json

package.json

package.json

tsconfig.json

tsconfig.json

Repository files navigation

relaymux is a lightweight local metaharness for coding agents. Telegram is the remote control; tmux is where the actual agent work happens.

The background service listens for Telegram messages, but it does not hide agent runs in a black box. When relaymux launches an agent, it opens a visible tmux window on your machine so you can attach, watch, interrupt, or debug the run like any normal terminal session.

Telegram is the main supported interface. iMessage/SMS support exists, but it is beta.

Requirements

You need Node.js 20+, npm, tmux, and a local agent CLI such as pi, codex, or claude. The installer uses curl and tar by default; it only needs git as a fallback.

Install

curl -fsSL https://raw.githubusercontent.com/mupt-ai/relaymux/main/install.sh | bash

The installer downloads a source tarball, builds relaymux locally, and writes the CLI shim into a writable directory already on your PATH when possible. You do not need to clone the repo.

Set up Telegram

Create a bot with BotFather, copy the token, then run:

relaymux setup --telegram --telegram-bot-token ''

When prompted, open your bot in Telegram and send /start. relaymux stores the token in ~/.relaymux/secrets/telegram-bot-token, discovers your chat id, writes ~/.relaymux/config.json, and starts the background service.

Check it:

relaymux status

Use it

Send your Telegram bot a message like:

Open an agent in ~/code/my-app and inspect the failing tests.

relaymux passes the message to your configured local orchestrator. If the orchestrator launches an agent, that agent runs in tmux; the final reply comes back through Telegram.

Manual notification test:

relaymux notify --from test --reply-mode telegram --message "hello from relaymux"

tmux is the workspace

relaymux uses one shared tmux session named agents by default. Each launched agent gets its own tmux window. This is the core idea: Telegram starts and receives updates from work, but tmux keeps that work visible and recoverable locally.

Attach any time:

tmux attach -t agents

Detach with Ctrl-b d. Closing Telegram does not stop the tmux run.

Launch an agent manually

relaymux launch \ --repo ~/code/my-app \ --agent pi \ --name inspect-tests \ --prompt "Inspect the failing tests and summarize what is broken."

Then attach with:

tmux attach -t agents

iMessage/SMS beta

iMessage/SMS depends on a working local imsg command. The minimal setup is:

relaymux setup --imsg

relaymux will try to show recent chats. Pick one, then text that chat to use relaymux. If chat discovery does not work, pass the chat id directly:

relaymux setup --imsg --chat-id ''

Troubleshooting

relaymux doctor relaymux status-launch-agent relaymux status --history

Logs live in ~/.relaymux/logs. Config lives at ~/.relaymux/config.json.

About

lightweight, tmux-backed meta-harness for coding agents

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Custom properties

Stars

5 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

TypeScript 98.2%

Shell 1.7%

JavaScript 0.1%