Module map¶

This page is a high-level map of Takopi’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.

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.

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 Takopi events consistently.

Module	Responsibility
`progress.py`	Progress tracking: reduces takopi 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.

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`, …).

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 (`takopi.api` re-exports).

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

Module	Responsibility
`settings.py`	Loads `takopi.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).

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).