help="shelldeck: project-first multi-terminal. Run with no arguments to open the app.",

no_args_is_help=False,

add_completion=False,

"""http, or https when the server on this port was started with --cert."""

try:

info = json.loads((db.config_dir() / "server.json").read_text(encoding="utf-8"))

return info["scheme"] if info.get("port") == CFG["port"] else "http"

except (OSError, ValueError, KeyError):

"""Call the local server. Exits with a readable message on failure."""

data = None if payload is None else json.dumps(payload).encode()

headers = {"Content-Type": "application/json", "X-Shelldeck-Token": auth.read_cli_token()}

req = urllib.request.Request(_url(path), data=data, method=method, headers=headers)

try:

with _open_url(req, timeout) as r:

return json.loads(r.read().decode() or "{}")

except urllib.error.HTTPError as e:

try:

body = json.loads(e.read().decode())

code = body.get("error", e.reason) + (f": {body['detail']}" if body.get("detail") else "")

except ValueError:

code = e.reason

if code in ("locked", "setup_required"):

code = "the CLI token was rejected; restart shelldeck (`sd stop`, then `sd`)"

typer.echo(f"error: {str(code).replace('_', ' ')}", err=True)

raise typer.Exit(1) from None

except OSError:

typer.echo(f"shelldeck is not running on port {CFG['port']} (start it with `shelldeck`)", err=True)

"""'ok' if shelldeck answers, 'other' if something else holds the port, None if free."""

try:

with _open_url(urllib.request.Request(_url("/api/health")), 1.5) as r:

return "ok" if json.loads(r.read().decode()).get("app") == "shelldeck" else "other"

except urllib.error.HTTPError:

return "other"

except (OSError, ValueError):

state = _health()

if state == "ok":

return

if state == "other":

typer.echo(f"port {CFG['port']} is used by another program; try `shelldeck --port 5456`", err=True)

raise typer.Exit(1)

if _supervisor_alive(): # sd-ui is restarting (port briefly down): a second server would split the shells

for _ in range(120):

time.sleep(0.25)

if _health() == "ok":

return

typer.echo(f"shelldeck is running but not answering; see {db.config_dir() / 'shelldeck.log'}", err=True)

raise typer.Exit(1)

# a hidden console of its own, not DETACHED_PROCESS: venv python.exe is a launcher that starts the real

# python, and a console-less parent makes Windows open a new (visible) terminal window for that child

detach = (

{"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW}

if sys.platform == "win32"

else {"start_new_session": True}

)

# the venv's shelldeck.exe launcher, so Task Manager groups the server (and its shells) under shelldeck, not Python

exe = Path(sys.executable).with_name("shelldeck.exe")

cmd = [str(exe)] if sys.platform == "win32" and exe.exists() else [sys.executable, "-m", "shelldeck"]

subprocess.Popen(

[*cmd, "--port", str(CFG["port"]), "serve"],

stdin=subprocess.DEVNULL,

stdout=subprocess.DEVNULL,

stderr=subprocess.DEVNULL,

close_fds=True,

**detach,

)

for _ in range(60):

time.sleep(0.25)

if _health() == "ok":

return

typer.echo(f"server did not start; see {db.config_dir() / 'shelldeck.log'}", err=True)

"""Edge or Chrome, for a chromeless --app window."""

candidates = []

for env in ("PROGRAMFILES(X86)", "PROGRAMFILES", "LOCALAPPDATA"):

base = os.environ.get(env)

if base:

candidates += [

Path(base) / "Microsoft/Edge/Application/msedge.exe",

Path(base) / "Google/Chrome/Application/chrome.exe",

]

found = next((str(p) for p in candidates if p.exists()), None)

names = ("msedge", "chrome", "microsoft-edge", "google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "brave-browser")

url = _url(path)

exe = _browser() if CFG.get("app") else None

if not exe:

webbrowser.open(url)

return

# default browser profile: a fresh --user-data-dir triggers Edge sign-in/sync prompts

subprocess.Popen(

[exe, f"--app={url}"],

stdin=subprocess.DEVNULL,

stdout=subprocess.DEVNULL,

stderr=subprocess.DEVNULL,

close_fds=True,

ctx: typer.Context,

port: int = typer.Option(CFG["port"], "--port", "-p", envvar="SHELLDECK_PORT", help="Server port."),

no_window: bool = typer.Option(False, "--no-window", help="Print the URL instead of opening the browser."),

app_window: bool = typer.Option(False, "--app", help="Open a chromeless Edge/Chrome app window instead of a browser tab."),

):

CFG["port"] = port

CFG["no_window"] = no_window

CFG["app"] = app_window

if ctx.invoked_subcommand is None:

"""Start the server if needed and open shelldeck in the browser (same as no arguments)."""

started = _health() is None

ensure_server()

_banner(_server_host(), "started" if started else "already running")

_show("/")

if _own_console():

try:

input(" Press Enter to close this window (shelldeck keeps running)")

except (EOFError, KeyboardInterrupt):

"""True when Windows opened a console just for us (Win+R, Start menu, a shortcut): it closes when we exit."""

if sys.platform != "win32" or not sys.stdin.isatty():

return False

import ctypes

import psutil

pids = (ctypes.c_uint * 64)()

attached = set(pids[: ctypes.windll.kernel32.GetConsoleProcessList(pids, 64)])

# climb our ancestors that share this console; the topmost one created it (a shell, or our own launcher)

top = psutil.Process()

while (parent := top.parent()) and parent.pid in attached:

top = parent

r" _ _ _ _ _",

r" ___ | |__ ___ | || | __| | ___ ___ | | __",

r"/ __|| '_ \ / _ \| || | / _` | / _ \ / __|| |/ /",

r"\__ \| | | || __/| || || (_| || __/| (__ | <",

r"|___/|_| |_| \___||_||_| \__,_| \___| \___||_|\_\ ",

from importlib.metadata import PackageNotFoundError, version

try:

return version("shelldeck")

except PackageNotFoundError:

"""Bind address of the running server, from server.json (the detached server is always loopback)."""

try:

info = json.loads((db.config_dir() / "server.json").read_text(encoding="utf-8"))

return info.get("host", HOST) if info.get("port") == CFG["port"] else HOST

except (OSError, ValueError):

"""This machine's LAN address: the source address of the default route (a UDP connect sends nothing)."""

import socket

with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:

try:

s.connect(("10.255.255.255", 1))

return s.getsockname()[0]

except OSError:

"""Logo, version and URLs. rich drops the colors when the output isn't an ANSI terminal (or NO_COLOR is set)."""

console.print()

for line, color in zip(LOGO, LOGO_COLORS, strict=True):

console.print(f" {line}", style=f"bold {color}", highlight=False, markup=False)

console.print(f"\n [bold]v{_version()}[/] [dim]project-first multi-terminal - {status}[/]\n", highlight=False)

scheme, port = scheme or _scheme(), CFG["port"]

console.print(f" [green]>[/] [bold]Local:[/] [cyan]{scheme}://127.0.0.1:{port}[/]", highlight=False)

if host in LOOPBACK_HOSTS:

console.print(" [dim]> Network: off (share: sd serve --host 0.0.0.0 --cert C --key K)[/]", highlight=False)

else:

net = _lan_ip() if host in ("0.0.0.0", "::") else host

console.print(f" [green]>[/] [bold]Network:[/] [cyan]{scheme}://{net or host}:{port}[/]", highlight=False)

if CFG.get("no_window"):

typer.echo(_url(path))

else:

host: str = typer.Option("127.0.0.1", "--host", help="Bind address. Keep 127.0.0.1 unless you know why."),

cert: Path = typer.Option(None, "--cert", exists=True, dir_okay=False, help="TLS certificate (PEM) for HTTPS."),

key: Path = typer.Option(None, "--key", exists=True, dir_okay=False, help="TLS private key (PEM)."),

insecure_http: bool = typer.Option(False, "--insecure-http", help="Allow plain HTTP on a non-local address (trusted network only)."),

):

"""Run the server in the foreground: sd-pty (the shells) and sd-ui (the web app)."""

if bool(cert) != bool(key):

typer.echo("error: --cert and --key go together", err=True)

raise typer.Exit(2)

if host not in LOOPBACK_HOSTS and not cert and not insecure_http:

typer.echo(

f"error: refusing to serve plain HTTP on {host}: passwords and terminal traffic would cross the network unencrypted.\n"

" Safest: keep the default 127.0.0.1 and use an SSH tunnel: ssh -L 5455:127.0.0.1:5455 you@vm\n"

" Or serve HTTPS: --cert cert.pem --key key.pem (or add --insecure-http on a trusted network)",

err=True,

)

raise typer.Exit(2)

_proc_name("shelldeck")

db.init_db()

_banner(host, "foreground, Ctrl+C stops", "https" if cert else "http")

ui_args = ["--host", host] + (["--cert", str(cert), "--key", str(key)] if cert else []) + (["--insecure-http"] if insecure_http else [])

"""Linux: show as `name`, not python3, in top and system monitors (Windows gets it from the exe's name)."""

if sys.platform.startswith("linux"):

import ctypes

"""The program to start as sd-pty / sd-ui: the exe of that name (frozen build or installed script, so Task

exe = (folder or Path(sys.executable).parent) / (role + (".exe" if sys.platform == "win32" else ""))

"""Is a `serve` supervisor for this port still running (sd-ui may be between restarts)?"""

import psutil

try:

pid = int(_supervisor_file().read_text(encoding="utf-8"))

return "serve" in psutil.Process(pid).cmdline()

except (OSError, ValueError, psutil.Error):

f = _supervisor_file()

f.write_text(str(os.getpid()), encoding="utf-8")

try:

return _supervise_loop(ui_args)

finally:

if f.exists() and f.read_text(encoding="utf-8") == str(os.getpid()):

"""shelldeck = sd-pty (owns the shells, long-lived) + sd-ui (web server and app, restartable).

import secrets

from . import frozen, ptyhost, update

if r := frozen.root(): # standalone: `sd` in the terminals (and agent hooks) runs the current version

frozen.ensure_shims()

os.environ["PATH"] = str(r) + os.pathsep + os.environ.get("PATH", "")

# the shells (in sd-pty) inherit these, so `sd` inside them reaches this server and its data folder

os.environ["SHELLDECK_PORT"] = str(CFG["port"])

if "SHELLDECK_HOME" in os.environ:

os.environ["SHELLDECK_HOME"] = str(db.config_dir().resolve())

# its own process group: a Ctrl+C in this console stops sd-ui, never the shells' host

group = {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} if sys.platform == "win32" else {"start_new_session": True}

while True:

token = secrets.token_urlsafe(32)

host = subprocess.Popen([*_role_argv("sd-pty"), "ptyhost"], stdin=subprocess.PIPE, stdout=subprocess.PIPE,

env=os.environ | {ptyhost.TOKEN_ENV: token}, **group)

try:

env = os.environ | {ptyhost.ADDR_ENV: f"127.0.0.1:{ptyhost.read_port(host)}", ptyhost.TOKEN_ENV: token}

while True:

ui = subprocess.Popen([*_role_argv("sd-ui", update.app_dir()), "--port", str(CFG["port"]), "ui", *ui_args], env=env)

try:

code = ui.wait()

except KeyboardInterrupt: # the console's Ctrl+C reached sd-ui too; let it shut down

code = ui.wait()

if code != ptyhost.RESTART_UI:

break

finally:

host.stdin.close() # sd-pty saves scrollback and closes its shells

try:

host.wait(15)

except subprocess.TimeoutExpired:

host.kill()

if code != ptyhost.RESTART_ALL:

"""sd-pty: the long-lived process that owns the shells (started by `serve`)."""

import logging

from logging.handlers import RotatingFileHandler

from . import ptyhost

_proc_name("sd-pty")

handler = RotatingFileHandler(db.config_dir() / "sd-pty.log", maxBytes=1_000_000, backupCount=1, encoding="utf-8")

handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))

logging.getLogger().addHandler(handler)

logging.getLogger().setLevel(logging.INFO)

host: str = typer.Option("127.0.0.1", "--host"),

cert: Path = typer.Option(None, "--cert"),

key: Path = typer.Option(None, "--key"),

insecure_http: bool = typer.Option(False, "--insecure-http"),

):

"""sd-ui: the web server and app (started by `serve`; restarts on an update)."""

from .server import run

_proc_name("sd-ui")

"""EMERGENCY, on the host only: forget the password and sign out every browser."""

if not yes and not typer.confirm("Forget the shelldeck password and sign out every browser?"):

raise typer.Exit(1)

db.init_db()

code = auth.reset()

typer.echo("Password removed and every login ended. Open shelldeck to create a new password.")

"""EMERGENCY, on the host only: print a one-time URL (5 minutes) that logs a browser in."""

ensure_server()

path = _api("/api/auth/login-link", "POST", {})["path"]

typer.echo(_url(path))

import segno

url = state["link"]["url"]

if sys.stdout.isatty():

segno.make(url, error="l").terminal(compact=(sys.stdout.encoding or "").lower().startswith("utf"))

typer.echo(f"\n {url}\n")

typer.echo(" Open it on the other device within 10 minutes. It works once; allow the device here or in shelldeck,")

"""Ask here before a device that opened the link gets in (a host browser may answer first),

asks: queue.Queue = queue.Queue()

asked: set[str] = set()

answered: set[str] = set() # answered at this prompt

def poll() -> None:

while True:

try:

state = _api("/api/share")

except typer.Exit:

state = None # server busy or restarting; try again

if state is not None:

if not state["sharing"]:

stopped.set()

return

ids = {p["id"] for p in state["pending"]}

for p in state["pending"]:

if p["id"] not in asked:

asked.add(p["id"])

asks.put(p)

for gone in asked - ids - answered:

answered.add(gone)

typer.echo(f"\n device {gone} was answered in the browser (or expired)")

time.sleep(3)

def ask() -> None:

while True:

p = asks.get()

if p["id"] in answered:

continue

typer.echo(f"\n A device opened the link: {p['ip']}\n {p['agent'][:100]}")

if p.get("code"):

typer.echo(f" It shows the code {p['code']}. Allow only if that is the code on your device.")

allow = input(" Allow it? [y/N] ").strip().lower() in ("y", "yes")

if p["id"] in answered:

typer.echo(" already answered")

continue

answered.add(p["id"])

try:

_api("/api/share/decide", "POST", {"id": p["id"], "allow": allow})

typer.echo(" allowed; it can log in with your password now" if allow else " denied")

except typer.Exit:

typer.echo(" that request was already answered or expired")

for target in (poll, ask):

action: str = typer.Argument(None, help="`stop` ends the running share."),

new_link: bool = typer.Option(False, "--new-link", help="Print a fresh one-use link for the running share."),

):

"""Reach this shelldeck from another device: HTTPS Cloudflare quick tunnel, one-use QR link, host approval, then your password."""

if action not in (None, "stop"):

typer.echo(f"unknown action {action!r}; try `sd share` or `sd share stop`", err=True)

raise typer.Exit(2)

ensure_server()

state = _api("/api/share")

if action == "stop":

_api("/api/share", "DELETE")

typer.echo("sharing stopped" if state["sharing"] else "not sharing")

return

if new_link:

if not state["sharing"]:

typer.echo("not sharing; start with `sd share`", err=True)

raise typer.Exit(1)

_show_share(_api("/api/share/link", "POST", {}))

return

if not _api("/api/auth/status").get("has_password"):

typer.echo("Set a password first: open shelldeck on this machine (`sd`), then run `sd share` again.", err=True)

raise typer.Exit(1)

if not state["strong_password"]:

typer.echo(

f"Sharing puts the login page on the internet, so it needs a password of {auth.SHARE_MIN_PASSWORD}+ characters.\n"

"Change it in Settings (or, if it is already that long, log in once), then run `sd share` again.",

err=True,

)

raise typer.Exit(1)

if not state["terms_accepted"]:

typer.echo("\nBefore you share:\n")

for line in state["terms"]:

typer.echo(f" - {line}")

try:

ok = input("\nDo you accept these terms and share at your own risk? [y/N] ").strip().lower() in ("y", "yes")

except EOFError:

ok = False

if not ok:

typer.echo("not sharing: the terms were not accepted", err=True)

raise typer.Exit(1)

_api("/api/share/terms", "POST", {"accept": True})

if not state["cloudflared"]:

typer.echo(f"cloudflared is not installed ({share_mod.HINT})", err=True)

raise typer.Exit(1)

started = not state["sharing"]

if started:

typer.echo(" starting the tunnel...")

state = _api("/api/share", "POST", {}, timeout=40)

if not state["link"]: # attached to a running share whose link was used or expired

state = _api("/api/share/link", "POST", {})

_show_share(state)

typer.echo(" Ctrl+C " + ("stops sharing and signs them out." if started else "leaves this share running (started elsewhere)."))

stopped = threading.Event()

try:

_watch_share(stopped)

while not stopped.wait(1):

pass

typer.echo("sharing was stopped")

return

except KeyboardInterrupt:

pass

if started and _health() == "ok":

_api("/api/share", "DELETE")

"""Stop the background server (closes all terminals)."""

if _health() != "ok":

typer.echo("shelldeck is not running")

return

_api("/api/shutdown", "POST", {})

"""Restart the web app (sd-ui) only; terminals keep running. Picks up updated code."""

if _health() != "ok":

typer.echo("shelldeck is not running")

raise typer.Exit(1)

_api("/api/restart", "POST", {})

down = False

for _ in range(80):

time.sleep(0.25)

up = _health() == "ok"

down = down or not up # the old sd-ui answers until it has stopped

if down and up:

typer.echo("restarted")

return

typer.echo(f"the web app did not come back; see {db.config_dir() / 'shelldeck.log'}", err=True)

path: str = typer.Argument(".", help="Project folder."),

shell: str = typer.Option("", "--shell", "-s", help="Shell kind, e.g. pwsh, cmd, wsl, bash, zsh (default from settings)."),

):

"""Add a folder as a project and open a terminal in it. A .code-workspace file adds every folder in it."""

folder = str(Path(path).resolve())

ensure_server()

if folder.lower().endswith(".code-workspace"):

r = _api("/api/workspaces/import", "POST", {"path": folder})

typer.echo(f"{r['workspace']}: {', '.join(p['name'] for p in r['projects'])}")

project = r["projects"][0]

else:

project = _api("/api/projects", "POST", {"path": folder})

session = _api("/api/sessions", "POST", {"project_id": project["id"], "shell": shell})

"""List terminals grouped by project."""

projects = _api("/api/projects")["projects"]

if not projects:

typer.echo("no projects")

return

table = Table(box=None)

for col in ("Project", "Terminal", "Shell", "ID", "Running"):

table.add_column(col)

for p in projects:

if not p["sessions"]:

table.add_row(p["name"], "-", "", "", "")

for s in p["sessions"]:

table.add_row(p["name"], s.get("name") or "", s.get("shell") or "default", s["id"], "yes" if s["alive"] else "no")

"""Show details about the shelldeck terminal you are in."""

sid = os.environ.get("SHELLDECK_SESSION_ID")

if not sid:

typer.echo("not inside a shelldeck terminal", err=True)

raise typer.Exit(1)

s = _api(f"/api/sessions/{sid}")["session"]

p = s.get("project") or {}

table = Table(show_header=False, box=None)

table.add_column(style="dim")

table.add_column()

for k, v in (

("Session", s.get("id", sid)),

("Name", s.get("name") or ""),

("Nick", s.get("nick") or ""),

("Parent", s.get("parent") or ""),

("Project", p.get("name", "")),

("Project path", p.get("path", "")),

("Working dir", s.get("cwd", "")),

("Shell", s.get("shell") or "default"),

("Size", f"{s.get('cols', 0)}x{s.get('rows', 0)}"),

("Created", s.get("created_at", "")),

):

table.add_row(k, str(v))

"""A terminal by id, nick, name (case-insensitive) or id prefix."""

sessions = _api("/api/sessions")["sessions"]

t = target.casefold()

hits = ([x for x in sessions if x["id"] == target] or [x for x in sessions if (x.get("nick") or "").casefold() == t]

or [x for x in sessions if (x.get("name") or "").casefold() == t] or [x for x in sessions if x["id"].startswith(target)])

if len(hits) != 1:

typer.echo(f"error: {'no' if not hits else 'more than one'} terminal matches {target!r} (see `sd agents --all`)", err=True)

raise typer.Exit(1)

"""AI agents running in shelldeck terminals (peers you can `sd peek` and `sd tell`)."""

me = os.environ.get("SHELLDECK_SESSION_ID")

data = _api("/api/agents")

running = data["running"]

if me and not all_:

mine = next((r["project_id"] for r in _api("/api/sessions")["sessions"] if r["id"] == me), None)

running = [r for r in running if r["project_id"] == mine]

if not running:

typer.echo("no AI agents running" + ("" if all_ or not me else " in this project (try --all)"))

for r in running:

you = " (you)" if r["session_id"] == me else ""

typer.echo(f"{r['nick'] or '-'} {r['session_id']} {r['label']} model={r['model'] or '?'} project={r['project']} cwd={r['cwd']}{you}")

if all_ and data.get("outside"):

typer.echo("\noutside shelldeck:")

for a in data["outside"]:

typer.echo(f"pid {a['pid']} {a['label']} model={a['model'] or '?'} cwd={a['cwd']} started by {a['host'] or '?'}")

if all_:

"""List built-in integration coverage and lifecycle/resume capabilities."""

rows = _api("/api/integrations")["integrations"]

if json_:

typer.echo(json.dumps(rows, indent=2))

return

table = Table("Agent", "Tier", "Method", "Lifecycle", "Resume", "CLI", "Integration", "Notes")

for item in rows:

table.add_row(item["agent"], item["tier"], item["kind"], "yes" if item["lifecycle"] else "screen/fallback",

"yes" if item["session_restore"] else "no", "found" if item["available"] else "not found",

item["status"].replace("_", " "), item["notes"])

rows = [r for r in _api("/api/integrations")["integrations"] if r.get("installable")]

if agent and not any(r["agent"] == agent for r in rows):

typer.echo(f"error: no installable integration for {agent!r} (have: {', '.join(r['agent'] for r in rows)})", err=True)

raise typer.Exit(1)

agents_: list[str] = typer.Argument(None, metavar="[AGENT]...", help="Agents (default: Claude, Codex, Gemini and Devin when found)."),

all_: bool = typer.Option(False, "--all", help="Also the preview integrations (installed agents only)."),

):

"""Add shelldeck's lifecycle hook/plugin to agents' configs (merged; other hooks stay; a backup is kept)."""

targets = agents_ or [r["agent"] for r in _integration_rows() if r["config_found"] and (all_ or r["tier"] == "priority")]

if not targets:

typer.echo("no supported agent CLI found; name one: sd integration install claude")

failed = False

for a in targets:

try:

_integration_rows(a)

r = _api(f"/api/integrations/{a}", "POST")

except typer.Exit: # the error is printed; carry on with the rest

failed = True

continue

typer.echo(f"{a}: {r['status'].replace('_', ' ')} ({r['file']})" + ("; restart OpenCode to load it" if a == "opencode" else ""))

if failed:

"""Remove only shelldeck's hook/plugin from agents' configs."""

for a in agents_:

_integration_rows(a)

r = _api(f"/api/integrations/{a}", "DELETE")

target: str = typer.Argument(..., help="Terminal nick, id, id prefix or name."),

lines: int = typer.Option(40, "--lines", "-n", help="How many of the last lines."),

):

"""Print the last lines of another terminal (e.g. to check another agent's progress)."""

sys.stdout.reconfigure(errors="replace") # TUI box drawing on a cp1252 console

target: str = typer.Argument(..., help="Terminal nick, id, id prefix or name."),

message: str = typer.Argument(..., help="Text to type into it."),

raw: bool = typer.Option(False, "--raw", help="Send the text as is: no sender tag, no Enter."),

):

"""Type a message into another terminal and press Enter (agent-to-agent messaging)."""

s = _session(target)

me = os.environ.get("SHELLDECK_NICK") or os.environ.get("SHELLDECK_SESSION_ID")

if not raw and me:

message = f"[message from {me}; reply with: sd tell {me} \"...\"] {message}"

_api(f"/api/sessions/{s['id']}/input", "POST", {"text": message, "enter": not raw})

target: str = typer.Argument(..., help="Terminal nick, id or name (e.g. your sub-agent)."),

keys: list[str] = typer.Argument(..., help="Keys to press in order: text, or enter, esc, tab, up, down, left, right, space."),

):

"""Press keys in another terminal, e.g. to answer a sub-agent's approval menu: sd answer Maya 1."""

s = _session(target)

for k in keys:

_api(f"/api/sessions/{s['id']}/input", "POST", {"text": KEYS.get(k.lower(), k), "enter": False})

time.sleep(0.15) # one key at a time: TUIs read a burst as a paste

target: str = typer.Argument(..., help="Terminal nick, id or name, e.g. a sub-agent whose work is finished."),

force: bool = typer.Option(False, "--force", help="Close it even though a hand-off to it is still open."),

):

"""Close a terminal and whatever runs in it. Agents: only your own sub-agents, and only once the user agreed."""

s = _session(target)

me = os.environ.get("SHELLDECK_SESSION_ID")

name = s.get("nick") or s["id"]

if s["id"] == me:

typer.echo("error: that is your own terminal", err=True)

raise typer.Exit(1)

if me and s.get("parent") != me: # an agent may not close the user's (or another agent's) terminals

typer.echo(f"error: {name} is not your sub-agent; ask the user to close it", err=True)

raise typer.Exit(1)

still = [h["id"] for h in _api(f"/api/handoffs?to={s['id']}&status=open")["handoffs"]]

if still and not force:

typer.echo(f"error: {name} still has hand-off {', '.join(still)} open (it runs sd done when finished); --force closes it anyway", err=True)

raise typer.Exit(1)

_api(f"/api/sessions/{s['id']}", "DELETE")

me = os.environ.get("SHELLDECK_SESSION_ID")

if not me:

typer.echo("error: run this inside a shelldeck terminal", err=True)

raise typer.Exit(1)

task: str = typer.Argument(..., help="The task, self-contained: files, expected result, how to check it."),

agent: str = typer.Option("", "--agent", "-a", help="claude, codex, devin, gemini, qwen or opencode (default: the one you run)."),

model: str = typer.Option("auto", "--model", "-m", help="small, medium, large, auto (by the task) or a model name."),

):

"""Start a sub-agent in a new terminal of this project and hand it a task."""

if os.environ.get("SHELLDECK_PARENT"):

typer.echo("error: sub-agents cannot spawn agents; ask your parent (sd tell)", err=True)

raise typer.Exit(1)

r = _api("/api/spawn", "POST", {"parent": _me(), "task": task, "agent": agent, "model": model})

started = r["command"].split(' "')[0] # the agent and model, without the long kickoff prompt

typer.echo(f"spawned {r['session']['nick']} ({r['session']['id']}): {started}")

target: str = typer.Argument(..., help="Terminal nick, id or name with an agent running."),

task: str = typer.Argument(..., help="The task."),

):

"""Hand a task to an agent already running in another terminal (tracked in .shelldeck/handoff.md)."""

s = _session(target)