Module map

This page is a high-level map of Untether’s internal modules: what they do and how they fit together.

Entry points

Module	Responsibility
cli.py	Typer CLI entry point; loads settings, selects engine/transport, runs the transport backend.
telegram/backend.py	Telegram transport backend: validates config, runs onboarding, builds and runs the Telegram bridge.

Orchestration and routing

Module	Responsibility
runner_bridge.py	Transport-agnostic orchestration: per-message handler, progress updates, final render, cancellation, resume coordination.
router.py	Auto-router: resolves resume tokens by polling runners; selects a runner for a message.
scheduler.py	Per-thread FIFO job queueing with serialization.
transport_runtime.py	Facade used by transports and commands to resolve messages and runners without importing internal router/project types.

Domain model and events

Module	Responsibility
model.py	Domain types: resume tokens, events, actions, run results.
runner.py	Runner protocol and event queue utilities.
events.py	Event factory helpers for building Untether events consistently.

Rendering and progress

Module	Responsibility
progress.py	Progress tracking: reduces untether events into progress snapshots.
markdown.py	Markdown formatting for progress/final messages; includes helpers like elapsed formatting.
presenter.py	Presenter protocol: converts ProgressState into transport-specific messages.
transport.py	Transport protocol: send/edit/delete abstractions and message reference types.

Telegram implementation

Module	Responsibility
telegram/bridge.py	Telegram bridge loop: polls updates, filters messages, dispatches handlers, coordinates cancellation.
telegram/client.py	Telegram API wrapper with retry/outbox semantics.
telegram/render.py	Telegram markdown rendering and trimming.
telegram/onboarding.py	Interactive setup and setup validation UX.
telegram/commands/*	In-chat command handlers (/agent, /file, /topic, /ctx, /new, …).

Plugins

Module	Responsibility
plugins.py	Entrypoint discovery and lazy loading (capture load errors, filter by enabled list).
engines.py	Engine backend discovery and loading via entrypoints.
transports.py	Transport backend discovery and loading via entrypoints.
commands.py	Command backend discovery and loading via entrypoints; command execution helpers.
ids.py	Shared ID regex and collision checks for plugin ids and Telegram command names.
api.py	Public plugin API boundary (untether.api re-exports).

Runners and schemas

Module	Responsibility
runners/*	Engine runner implementations (Codex, Claude Code, OpenCode, Pi).
schemas/*	msgspec schemas / decoders for engine JSONL streams.

Configuration and persistence

Module	Responsibility
settings.py	Loads untether.toml (TOML + env), validates with pydantic-settings.
config_store.py	Raw TOML read/write (merge/update without clobbering extra sections).
config_migrations.py	One-time edits to on-disk config (e.g. legacy Telegram key migration).

Utilities

Module	Responsibility
utils/paths.py	Path/command relativization helpers.
utils/streams.py	Async stream helpers (iter_bytes_lines, stderr draining).
utils/subprocess.py	Subprocess management helpers (terminate/kill best-effort).