tetherly 0.1.0__tar.gz

tetherly-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 changhyeon363
+
+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.

tetherly-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: tetherly
+Version: 0.1.0
+Summary: Discord to tmux session bridge for agent-driven workflows.
+Author-email: changhyeon363 <changhyeon363@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: discord.py<3,>=2.5
+Provides-Extra: docs
+Requires-Dist: zensical<1,>=0.0.37; extra == "docs"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/images/tetherly-icon.png" alt="tetherly icon" width="96" height="96">
+</p>
+
+# tetherly
+
+Discord channel ↔ tmux session bridge.
+
+> 📖 **Documentation is in [docs/](docs/) — split into [user docs](docs/user/) (setup, commands, troubleshooting) and [contributing docs](docs/contributing/) (internals).** This README is a quick start.
+
+## Features
+
+- `/bind session:<name>`: bind the current Discord channel to a tmux session
+- `/config auto_send:<true|false>`: enable or disable plain-text auto-send for the current bound channel
+- `/send text:<message>`: send text plus Enter into the bound tmux session
+- `/key key:<Enter|Escape|Ctrl-C|Ctrl-D|Tab|Up|Down|Left|Right>`: send a special key into the bound tmux session
+- `/tail lines:<n>`: fetch recent tmux output
+- `/status`: inspect the current binding and tmux session status
+- `tetherly discord-send --message <text>`: let an agent inside a bound tmux session send a reply back to Discord
+- `tetherly codex-stop` / `tetherly codex-permission-request`: Codex hook handlers that forward messages to the bound Discord channel
+
+## Requirements
+
+- Python 3.11+
+- `tmux` installed
+- A Discord bot token (Message Content Intent enabled if you want plain-text auto-send)
+
+## Setup
+
+Install once on your machine:
+
+```bash
+pipx install tetherly
+tetherly init
+```
+
+`tetherly init` is interactive. It writes `~/.tetherly/.env` and asks where to install Codex hooks:
+
+- **Global** — writes `~/.codex/hooks.json` once. Hooks fire in every project automatically; nothing per-project.
+- **Project** — skip global hooks and run `tetherly install-hooks` inside each project where you want them.
+- **Skip** — don't touch Codex hooks.
+
+Then start the bot:
+
+```bash
+tetherly
+```
+
+That's it. State lives at `~/.tetherly/state.json` so a single bot can serve every project.
+
+### Per-project usage
+
+For each project you want to drive from Discord:
+
+```bash
+tmux new -s <session-name>
+# inside the bound channel on Discord:
+#   /bind session:<session-name>
+#   /config auto_send:true
+```
+
+If you chose **Project** mode during init, also run once per project:
+
+```bash
+cd <project>
+tetherly install-hooks
+```
+
+`install-hooks` accepts `--global` to (re)install user-level hooks instead.
+
+### Sending from inside a session
+
+```bash
+tetherly discord-send --message "작업 끝났습니다"
+cat result.txt | tetherly discord-send --stdin
+tetherly discord-send --session t1 --message "..."   # explicit session
+```
+
+## Configuration
+
+`tetherly init` writes everything you need. Advanced overrides live in `~/.tetherly/.env` or shell env:
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `DISCORD_BOT_TOKEN` | (required) | Bot token |
+| `TETHERLY_ALLOWED_USER_IDS` | (required) | Comma-separated user IDs |
+| `TETHERLY_ALLOWED_GUILD_IDS` | — | Restrict commands to these guilds |
+| `TETHERLY_ALLOWED_ROLE_IDS` | — | Allow members holding any of these roles |
+| `TETHERLY_TEST_GUILD_ID` | — | Dev guild for instant slash-command sync |
+| `TETHERLY_STATE_PATH` | `~/.tetherly/state.json` | Where bindings are persisted |
+| `TETHERLY_DEFAULT_TAIL_LINES` | `40` | Default `/tail` line count |
+| `TETHERLY_MAX_TAIL_LINES` | `200` | Cap for `/tail` |
+| `TETHERLY_LOG_LEVEL` | `INFO` | Logger verbosity |
+
+A `.env` in the current working directory still overrides `~/.tetherly/.env`.
+
+## Codex hooks
+
+Both hooks only fire when the active tmux session has `TETHERLY_NOTIFY_ON_FINISH=1` — `/bind` sets that flag automatically, so projects without a binding stay silent even when global hooks are installed.
+
+- `Stop` → `tetherly codex-stop` forwards `last_assistant_message` to the bound channel.
+- `PermissionRequest` → `tetherly codex-permission-request` forwards the tool/command/reason. It does not return an `allow`/`deny` decision, so Codex's normal approval prompt still appears.

tetherly-0.1.0/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img src="docs/assets/images/tetherly-icon.png" alt="tetherly icon" width="96" height="96">
+</p>
+
+# tetherly
+
+Discord channel ↔ tmux session bridge.
+
+> 📖 **Documentation is in [docs/](docs/) — split into [user docs](docs/user/) (setup, commands, troubleshooting) and [contributing docs](docs/contributing/) (internals).** This README is a quick start.
+
+## Features
+
+- `/bind session:<name>`: bind the current Discord channel to a tmux session
+- `/config auto_send:<true|false>`: enable or disable plain-text auto-send for the current bound channel
+- `/send text:<message>`: send text plus Enter into the bound tmux session
+- `/key key:<Enter|Escape|Ctrl-C|Ctrl-D|Tab|Up|Down|Left|Right>`: send a special key into the bound tmux session
+- `/tail lines:<n>`: fetch recent tmux output
+- `/status`: inspect the current binding and tmux session status
+- `tetherly discord-send --message <text>`: let an agent inside a bound tmux session send a reply back to Discord
+- `tetherly codex-stop` / `tetherly codex-permission-request`: Codex hook handlers that forward messages to the bound Discord channel
+
+## Requirements
+
+- Python 3.11+
+- `tmux` installed
+- A Discord bot token (Message Content Intent enabled if you want plain-text auto-send)
+
+## Setup
+
+Install once on your machine:
+
+```bash
+pipx install tetherly
+tetherly init
+```
+
+`tetherly init` is interactive. It writes `~/.tetherly/.env` and asks where to install Codex hooks:
+
+- **Global** — writes `~/.codex/hooks.json` once. Hooks fire in every project automatically; nothing per-project.
+- **Project** — skip global hooks and run `tetherly install-hooks` inside each project where you want them.
+- **Skip** — don't touch Codex hooks.
+
+Then start the bot:
+
+```bash
+tetherly
+```
+
+That's it. State lives at `~/.tetherly/state.json` so a single bot can serve every project.
+
+### Per-project usage
+
+For each project you want to drive from Discord:
+
+```bash
+tmux new -s <session-name>
+# inside the bound channel on Discord:
+#   /bind session:<session-name>
+#   /config auto_send:true
+```
+
+If you chose **Project** mode during init, also run once per project:
+
+```bash
+cd <project>
+tetherly install-hooks
+```
+
+`install-hooks` accepts `--global` to (re)install user-level hooks instead.
+
+### Sending from inside a session
+
+```bash
+tetherly discord-send --message "작업 끝났습니다"
+cat result.txt | tetherly discord-send --stdin
+tetherly discord-send --session t1 --message "..."   # explicit session
+```
+
+## Configuration
+
+`tetherly init` writes everything you need. Advanced overrides live in `~/.tetherly/.env` or shell env:
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `DISCORD_BOT_TOKEN` | (required) | Bot token |
+| `TETHERLY_ALLOWED_USER_IDS` | (required) | Comma-separated user IDs |
+| `TETHERLY_ALLOWED_GUILD_IDS` | — | Restrict commands to these guilds |
+| `TETHERLY_ALLOWED_ROLE_IDS` | — | Allow members holding any of these roles |
+| `TETHERLY_TEST_GUILD_ID` | — | Dev guild for instant slash-command sync |
+| `TETHERLY_STATE_PATH` | `~/.tetherly/state.json` | Where bindings are persisted |
+| `TETHERLY_DEFAULT_TAIL_LINES` | `40` | Default `/tail` line count |
+| `TETHERLY_MAX_TAIL_LINES` | `200` | Cap for `/tail` |
+| `TETHERLY_LOG_LEVEL` | `INFO` | Logger verbosity |
+
+A `.env` in the current working directory still overrides `~/.tetherly/.env`.
+
+## Codex hooks
+
+Both hooks only fire when the active tmux session has `TETHERLY_NOTIFY_ON_FINISH=1` — `/bind` sets that flag automatically, so projects without a binding stay silent even when global hooks are installed.
+
+- `Stop` → `tetherly codex-stop` forwards `last_assistant_message` to the bound channel.
+- `PermissionRequest` → `tetherly codex-permission-request` forwards the tool/command/reason. It does not return an `allow`/`deny` decision, so Codex's normal approval prompt still appears.

tetherly-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tetherly"
+version = "0.1.0"
+description = "Discord to tmux session bridge for agent-driven workflows."
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+  {name = "changhyeon363", email = "changhyeon363@gmail.com"},
+]
+dependencies = [
+  "discord.py>=2.5,<3",
+]
+
+[project.optional-dependencies]
+docs = [
+  "zensical>=0.0.37,<1",
+]
+
+[project.scripts]
+tetherly = "tetherly.main:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

tetherly-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tetherly-0.1.0/src/tetherly/__init__.py

@@ -0,0 +1 @@
+"""tetherly package."""

tetherly-0.1.0/src/tetherly/authz.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import discord
+
+
+@dataclass(frozen=True)
+class AccessController:
+    allowed_guild_ids: set[int]
+    allowed_role_ids: set[int]
+    allowed_user_ids: set[int]
+
+    def is_allowed_user(self, guild_id: int | None, user: object) -> bool:
+        if self.allowed_guild_ids and guild_id not in self.allowed_guild_ids:
+            return False
+        user_id = getattr(user, "id", None)
+        if user_id in self.allowed_user_ids:
+            return True
+        if not self.allowed_role_ids:
+            return user_id in self.allowed_user_ids
+        if isinstance(user, discord.Member):
+            role_ids = {role.id for role in user.roles}
+            return bool(role_ids & self.allowed_role_ids)
+        return False
+
+    def is_allowed(self, interaction: discord.Interaction) -> bool:
+        return self.is_allowed_user(interaction.guild_id, interaction.user)
+
+    async def assert_allowed(self, interaction: discord.Interaction) -> bool:
+        if self.is_allowed(interaction):
+            return True
+        await interaction.response.send_message(
+            "You are not allowed to use this command.",
+            ephemeral=True,
+        )
+        return False

tetherly-0.1.0/src/tetherly/config.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+USER_CONFIG_DIR = Path.home() / ".tetherly"
+USER_ENV_PATH = USER_CONFIG_DIR / ".env"
+USER_STATE_PATH = USER_CONFIG_DIR / "state.json"
+
+
+def _load_env_file(path: Path) -> None:
+    if not path.exists():
+        return
+    for raw_line in path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :]
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip("'").strip('"')
+        os.environ.setdefault(key, value)
+
+
+def load_dotenv(path: str = ".env") -> None:
+    _load_env_file(Path(path))
+    _load_env_file(USER_ENV_PATH)
+
+
+def _parse_id_set(raw: str | None) -> set[int]:
+    if not raw:
+        return set()
+    values: set[int] = set()
+    for chunk in raw.split(","):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        values.add(int(chunk))
+    return values
+
+
+@dataclass(frozen=True)
+class Config:
+    discord_bot_token: str
+    state_path: Path
+    allowed_guild_ids: set[int]
+    allowed_role_ids: set[int]
+    allowed_user_ids: set[int]
+    test_guild_id: int | None = None
+    default_tail_lines: int = 40
+    max_tail_lines: int = 200
+    log_level: str = "INFO"
+    command_prefix: str = "/"
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        token = os.environ["DISCORD_BOT_TOKEN"].strip()
+        state_path = Path(os.environ.get("TETHERLY_STATE_PATH", str(USER_STATE_PATH)))
+        return cls(
+            discord_bot_token=token,
+            state_path=state_path,
+            allowed_guild_ids=_parse_id_set(os.environ.get("TETHERLY_ALLOWED_GUILD_IDS")),
+            allowed_role_ids=_parse_id_set(os.environ.get("TETHERLY_ALLOWED_ROLE_IDS")),
+            allowed_user_ids=_parse_id_set(os.environ.get("TETHERLY_ALLOWED_USER_IDS")),
+            test_guild_id=int(os.environ["TETHERLY_TEST_GUILD_ID"])
+            if os.environ.get("TETHERLY_TEST_GUILD_ID")
+            else None,
+            default_tail_lines=int(os.environ.get("TETHERLY_DEFAULT_TAIL_LINES", "40")),
+            max_tail_lines=int(os.environ.get("TETHERLY_MAX_TAIL_LINES", "200")),
+            log_level=os.environ.get("TETHERLY_LOG_LEVEL", "INFO").upper(),
+        )
+
+    def configure_logging(self) -> None:
+        logging.basicConfig(
+            level=getattr(logging, self.log_level, logging.INFO),
+            format="%(asctime)s %(levelname)s %(name)s %(message)s",
+        )

tetherly-0.1.0/src/tetherly/discord_bot.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import logging
+
+import discord
+from discord import app_commands
+
+from tetherly.authz import AccessController
+from tetherly.config import Config
+from tetherly.session_registry import SessionRegistry, SessionRegistryError
+from tetherly.tmux_service import TmuxError, TmuxService, normalize_session_name
+
+LOGGER = logging.getLogger(__name__)
+AUTO_SEND_MAX_LENGTH = 4000
+
+
+def _render_code_block(text: str) -> str:
+    stripped = text.strip()
+    if not stripped:
+        return "```text\n<empty>\n```"
+    return f"```text\n{stripped[:1800]}\n```"
+
+
+def _extract_auto_send_text(message: discord.Message) -> str | None:
+    if message.author.bot or message.webhook_id is not None:
+        return None
+    if message.guild is None or isinstance(message.channel, discord.Thread):
+        return None
+    if message.type is not discord.MessageType.default:
+        return None
+    if message.reference is not None or message.attachments:
+        return None
+    content = message.content.strip()
+    if not content or content.startswith("/") or len(content) > AUTO_SEND_MAX_LENGTH:
+        return None
+    return content
+
+
+class TetherlyBot(discord.Client):
+    def __init__(
+        self,
+        *,
+        config: Config,
+        registry: SessionRegistry,
+        tmux_service: TmuxService,
+        access_controller: AccessController,
+    ) -> None:
+        intents = discord.Intents.default()
+        intents.message_content = True
+        super().__init__(intents=intents)
+        self.config = config
+        self.registry = registry
+        self.tmux_service = tmux_service
+        self.access_controller = access_controller
+        self.tree = app_commands.CommandTree(self)
+
+    async def setup_hook(self) -> None:
+        self._register_commands()
+        if self.config.test_guild_id is not None:
+            guild = discord.Object(id=self.config.test_guild_id)
+            self.tree.copy_global_to(guild=guild)
+            await self.tree.sync(guild=guild)
+            LOGGER.info("synced commands to guild %s", self.config.test_guild_id)
+            return
+        await self.tree.sync()
+
+    async def on_ready(self) -> None:
+        LOGGER.info("bot ready as %s", self.user)
+
+    async def on_message(self, message: discord.Message) -> None:
+        if message.guild is None:
+            return
+        binding = self.registry.get(message.channel.id)
+        if binding is None or not binding.auto_send:
+            return
+        if not self.access_controller.is_allowed_user(message.guild.id, message.author):
+            return
+        content = _extract_auto_send_text(message)
+        if content is None:
+            return
+        try:
+            self.tmux_service.send_text(binding.session_name, content, press_enter=True)
+        except TmuxError as exc:
+            LOGGER.warning(
+                "auto-send failed for channel %s session %s: %s",
+                binding.channel_id,
+                binding.session_name,
+                exc,
+            )
+            return
+        self.registry.touch(binding.channel_id)
+
+    def _register_commands(self) -> None:
+        @self.tree.command(name="bind", description="Bind this Discord channel to a tmux session.")
+        @app_commands.describe(session="tmux session name")
+        async def bind(interaction: discord.Interaction, session: str) -> None:
+            if not await self.access_controller.assert_allowed(interaction):
+                return
+            if interaction.guild_id is None or interaction.channel_id is None:
+                await interaction.response.send_message(
+                    "This command can only be used inside a guild channel.",
+                    ephemeral=True,
+                )
+                return
+            try:
+                session_name = normalize_session_name(session)
+            except ValueError as exc:
+                await interaction.response.send_message(str(exc), ephemeral=True)
+                return
+            created = self.tmux_service.ensure_session(session_name)
+            self.tmux_service.set_session_environment(
+                session_name,
+                "TETHERLY_SESSION",
+                session_name,
+            )
+            self.tmux_service.set_session_environment(
+                session_name,
+                "TETHERLY_NOTIFY_ON_FINISH",
+                "1",
+            )
+            try:
+                binding = self.registry.bind(
+                    guild_id=interaction.guild_id,
+                    channel_id=interaction.channel_id,
+                    session_name=session_name,
+                    bound_by=interaction.user.id,
+                )
+            except SessionRegistryError as exc:
+                await interaction.response.send_message(str(exc), ephemeral=True)
+                return
+            verb = "Created and bound" if created else "Bound"
+            await interaction.response.send_message(
+                f"{verb} channel <#{binding.channel_id}> to tmux session `{binding.session_name}`.",
+                ephemeral=True,
+            )
+
+        @self.tree.command(
+            name="config",
+            description="Configure channel behavior for the bound tmux session.",
+        )
+        @app_commands.describe(auto_send="forward plain text messages without using /send")
+        async def config(interaction: discord.Interaction, auto_send: bool) -> None:
+            if not await self.access_controller.assert_allowed(interaction):
+                return
+            binding = self.registry.get(interaction.channel_id)
+            if binding is None:
+                await interaction.response.send_message(
+                    "This channel is not bound. Run `/bind session:<name>` first.",
+                    ephemeral=True,
+                )
+                return
+            updated = self.registry.set_auto_send(interaction.channel_id, auto_send)
+            status = "enabled" if auto_send else "disabled"
+            await interaction.response.send_message(
+                f"Auto-send {status} for `{updated.session_name}`.",
+                ephemeral=True,
+            )
+
+        @self.tree.command(name="send", description="Send text into the bound tmux session and press Enter.")
+        @app_commands.describe(text="text to send")
+        async def send(interaction: discord.Interaction, text: str) -> None:
+            if not await self.access_controller.assert_allowed(interaction):
+                return
+            binding = self.registry.get(interaction.channel_id)
+            if binding is None:
+                await interaction.response.send_message(
+                    "This channel is not bound. Run `/bind session:<name>` first.",
+                    ephemeral=True,
+                )
+                return
+            try:
+                self.tmux_service.send_text(binding.session_name, text, press_enter=True)
+            except TmuxError as exc:
+                await interaction.response.send_message(
+                    f"Failed to send to `{binding.session_name}`: {exc}",
+                    ephemeral=True,
+                )
+                return
+            self.registry.touch(interaction.channel_id)
+            await interaction.response.send_message(
+                f"Sent to `{binding.session_name}`.",
+                ephemeral=True,
+            )
+
+        @self.tree.command(name="key", description="Send a special key into the bound tmux session.")
+        @app_commands.describe(key="special key to send")
+        @app_commands.choices(
+            key=[
+                app_commands.Choice(name="Enter", value="enter"),
+                app_commands.Choice(name="Escape", value="esc"),
+                app_commands.Choice(name="Ctrl-C", value="ctrl-c"),
+                app_commands.Choice(name="Ctrl-D", value="ctrl-d"),
+                app_commands.Choice(name="Tab", value="tab"),
+                app_commands.Choice(name="Up", value="up"),
+                app_commands.Choice(name="Down", value="down"),
+                app_commands.Choice(name="Left", value="left"),
+                app_commands.Choice(name="Right", value="right"),
+            ]
+        )
+        async def key(interaction: discord.Interaction, key: app_commands.Choice[str]) -> None:
+            if not await self.access_controller.assert_allowed(interaction):
+                return
+            binding = self.registry.get(interaction.channel_id)
+            if binding is None:
+                await interaction.response.send_message(
+                    "This channel is not bound. Run `/bind session:<name>` first.",
+                    ephemeral=True,
+                )
+                return
+            try:
+                self.tmux_service.send_key(binding.session_name, key.value)
+            except TmuxError as exc:
+                await interaction.response.send_message(
+                    f"Failed to send `{key.name}` to `{binding.session_name}`: {exc}",
+                    ephemeral=True,
+                )
+                return
+            self.registry.touch(interaction.channel_id)
+            await interaction.response.send_message(
+                f"Sent `{key.name}` to `{binding.session_name}`.",
+                ephemeral=True,
+            )
+
+        @self.tree.command(name="tail", description="Show recent output from the bound tmux session.")
+        @app_commands.describe(lines="number of lines to fetch")
+        async def tail(interaction: discord.Interaction, lines: int | None = None) -> None:
+            if not await self.access_controller.assert_allowed(interaction):
+                return
+            binding = self.registry.get(interaction.channel_id)
+            if binding is None:
+                await interaction.response.send_message(
+                    "This channel is not bound. Run `/bind session:<name>` first.",
+                    ephemeral=True,
+                )
+                return
+            requested = lines or self.config.default_tail_lines
+            capped = min(max(1, requested), self.config.max_tail_lines)
+            try:
+                output = self.tmux_service.capture_tail(binding.session_name, capped)
+            except TmuxError as exc:
+                await interaction.response.send_message(
+                    f"Failed to capture `{binding.session_name}`: {exc}",
+                    ephemeral=True,
+                )
+                return
+            self.registry.touch(interaction.channel_id)
+            await interaction.response.send_message(
+                f"Recent output from `{binding.session_name}` ({capped} lines max)\n{_render_code_block(output)}",
+                ephemeral=True,
+            )
+
+        @self.tree.command(name="status", description="Show binding and tmux session status for this channel.")
+        async def status(interaction: discord.Interaction) -> None:
+            if not await self.access_controller.assert_allowed(interaction):
+                return
+            binding = self.registry.get(interaction.channel_id)
+            if binding is None:
+                await interaction.response.send_message(
+                    "This channel is not bound.",
+                    ephemeral=True,
+                )
+                return
+            tmux_status = self.tmux_service.get_status(binding.session_name)
+            if tmux_status.exists:
+                headline = f"🟢 Active — tmux session `{binding.session_name}` is alive"
+            else:
+                headline = (
+                    f"🔴 tmux session `{binding.session_name}` is GONE — "
+                    "run `/bind session:<name>` to reconnect"
+                )
+            await interaction.response.send_message(
+                "\n".join(
+                    [
+                        headline,
+                        f"Channel: <#{binding.channel_id}>",
+                        f"Auto-send: `{binding.auto_send}`",
+                        f"Bound by: <@{binding.bound_by}>",
+                        f"Bound at: `{binding.bound_at}`",
+                        f"Last used at: `{binding.last_used_at}`",
+                    ]
+                ),
+                ephemeral=True,
+            )