axterm

Run CLI coding agents as managed background sessions, and drive them from a messenger.

An agent in a terminal tab dies when you close the tab, and you can only watch it while you are sitting in front of it. axterm keeps the agent in a background terminal host, mirrors it into a Telegram topic, and lets you approve tool calls, answer questions, and send new prompts from your phone. No cloud relay: each machine only makes outbound connections.

  Telegram ◀────▶ daemon ◀────▶ terminal host ───▶ PTY ───▶ agent (omp)
      CLI    ◀────┘                         ├────▶ PTY ───▶ agent (feat-a)
                                           └────▶ PTY ───▶ agent (feat-b)

What it does

• Sessions outlive your terminal and daemon. The terminal host owns the PTY; attach and detach with Ctrl+X Ctrl+X.
• Telegram as a control surface. One forum topic per session: streamed output, approval buttons, structured questions with multi-select and free text, and plain messages delivered as prompts.
• Parallel work on git worktrees. --worktree gives each session its own branch and checkout; fanout starts the same prompt on several branches; diff summarizes the result, untracked files included.
• Crash recovery and resume. The OS can restart a failed daemon and adopt the same live PTY. A killed agent can still resume with its conversation and Telegram topic intact.
• Several machines, one group. Address a specific PC with machine:project; each machine runs its own bot.
• English and Korean for every user-facing string.

Requirements

Bun 1.3.14+, git 2.25+, and an agent CLI on PATH. No Node, and nothing to compile. omp is the fully integrated agent today.

Quick start

bun install -g @layorixinc/axterm

The command is axterm; the package is scoped because npm refuses the bare name as too close to xterm. bunx @layorixinc/axterm works for a one-off, but a global install is what you want for real use: the daemon bakes its own path into the hook configs it writes, and a package cache is not a stable home for that.

axterm run                  # start an agent here and attach
axterm service install      # start at login and restart daemon failures
axterm list                 # what is running
axterm resume <id>          # bring an exited session back

From a checkout instead — Bun runs the TypeScript directly, so there is no build step:

git clone https://github.com/layorixinc/axterm && cd axterm
bun install

# convenience alias
alias axterm='bun "$PWD/packages/cli/src/index.ts"'            # bash/zsh
# function axterm { bun $PWD\packages\cli\src\index.ts @args }  # PowerShell

Or build a single self-contained executable — no runtime required to run it:

bun run build                # this platform, into dist/bin/
bun run build:all            # every platform (from Linux; see AGENTS.md §4.36)

Detach with Ctrl+X Ctrl+X; the session keeps running.

The first interactive run offers a short setup wizard — language, machine name, agent, and optionally Telegram. It never appears in a pipe or a CI job, --no-setup skips it, and axterm setup re-runs it at any time. axterm works with no configuration at all; only channels need settings.

Telegram (optional)

Create a bot with @BotFather, make a group, turn Topics on, add the bot as an administrator with the Manage Topics permission, then:

axterm config set channels.telegram.botToken   <token>
axterm config set channels.telegram.groupId    <group id>
axterm config set channels.telegram.allowUserIds <your user id>
axterm telegram doctor      # checks forum mode and bot permissions

Only the listed user ids are accepted; everything else is ignored. Tokens are stored in a 0600 secrets file, never in the shareable config.

Language

axterm config set locale ko    # persistent, applied without a restart
AXTERM_LANG=en axterm list     # one-shot override

Resolution order: AXTERM_LANG > config locale > LC_ALL/LANG > English.

Status

Used daily on Windows and Linux, and verified on macOS (Apple Silicon): the full suite passes on all three, with a live session, the documented file layout, and the 0600/0700 permissions checked on each. Interfaces are still moving, and the version number is honest: this is 0.1.x. Agents other than omp have profiles for titles and resume, but not yet the status hooks.

Documentation

| | | |---|---| | docs/USAGE.md | day-to-day guide | | AGENTS.md | architecture decisions and the list of traps found by measurement | | docs/design/ | design notes per subsystem | | CONTRIBUTING.md | how to build, test, and what this project expects of a change | | CODE_OF_CONDUCT.md | Contributor Covenant 2.1 |

Security

Report vulnerabilities privately to [email protected] — see SECURITY.md for the trust boundaries and what does not count (running arbitrary commands is the product, not a bug).

License

MIT © Layorix Inc. — see LICENSE.