@layorixinc/axterm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Layorix Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# 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 daemon-owned PTY, 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  │────▶ PTY ──▶ agent (omp)
+    CLI    ◀────▶│         │────▶ PTY ──▶ agent (worktree: feat-a)
+                 └─────────┘────▶ PTY ──▶ agent (worktree: feat-b)
+```
+
+## What it does
+
+- **Sessions outlive your terminal.** The daemon 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.
+- **Resume.** A killed session — or one lost to a daemon restart — restarts with its conversation
+  intact and keeps the same Telegram topic.
+- **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](https://bun.sh) 1.3.14+, git 2.25+, and an agent CLI on `PATH`. No Node, and nothing to compile.
+[omp](https://github.com/can1357/oh-my-pi) is the fully integrated agent today.
+
+## Quick start
+
+```bash
+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.
+
+```bash
+axterm run                  # start an agent here and attach
+axterm list                 # what is running
+axterm resume <id>          # bring an exited session back
+```
+
+From a checkout instead — [Bun](https://bun.sh) runs the TypeScript directly, so there is no build
+step:
+
+```bash
+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:
+
+```bash
+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](https://t.me/BotFather), make a group, turn **Topics** on, add the bot
+as an administrator with the *Manage Topics* permission, then:
+
+```bash
+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
+
+```bash
+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`](docs/USAGE.md) | day-to-day guide |
+| [`AGENTS.md`](AGENTS.md) | architecture decisions and the list of traps found by measurement |
+| [`docs/design/`](docs/design/) | design notes per subsystem |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | how to build, test, and what this project expects of a change |
+| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1 |
+
+## Security
+
+Report vulnerabilities privately to **lordkeios@layorix.ai** — see
+[SECURITY.md](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](LICENSE).