takopi

Technical Briefing – takopi Concise, consultant‑grade; all file paths and counts come from the repository’s static analysis.

The Problem

Engineers who use LLMs (Codex, Claude, OpenAI, Pi) need a single entry point that can run agents across many git worktrees, stream progress back to a Telegram chat, and resume sessions later without losing state. takopi fills that gap, but its internal structure and CI hygiene need scrutiny before production adoption.

What This Does

takopi is a Telegram‑bridged runner that lets you start, monitor, and resume agent sessions from chat. Key components live under src/takopi/:

• src/takopi/telegram/loop.py – 50 functions/10 classes; the main message‑poller and dispatch loop.
• src/takopi/config.py – 9 functions/3 classes; reads/writes the persistent config (via read_config, load_or_init_config).
• src/takopi/runner.py – 39 functions/7 classes; orchestrates run_with_resume_lock and worktree management.
• src/takopi/telegram/bridge.py – 17 importers, 15 exports; bridges Telegram updates to the internal command pipeline.

The repo also ships scripts/ (5 files) for release/onboarding helpers and a pyproject.toml that pins the tool as a uv‑installed package.

How It Is Wired

Entry points (from the internal call graph):

Control flow typically starts at handle → run_one → _run_engine → resolve_run_cwd → ensure_worktree (filesystem). The longest shortest path to an out‑of‑process effect is handle → run_one → _run_engine → resolve_run_cwd → ensure_worktree (worktree creation).

Hub & cycle costs – src/takopi/logging.py is imported by 33 modules (instability 0), making changes ripple widely. A 19‑module import cycle involves src/takopi/telegram/bridge.py, topics.py, and commands/reply.py; any modification risks breaking the circular dependency unless shared types are extracted.

What the code touches outside itself – 90 functions read/write files; 2 make outbound network calls (Telegram API); 1 performs crypto/secret generation; 1 runs external commands. The shortest path from handle to a filesystem write goes through ensure_worktree (worktree directory creation).

How To Use It

• Setup – Install with the documented command: ``sh uv tool install -U takopi ` Then run the setup wizard (takopi`) to create a BotFather token, pick a workflow (assistant/workspace/handoff), and connect your chat.

• Configuration – The wizard writes a config file (see src/takopi/config.py). Environment variables for engine binaries (codex, claude, opencode, pi) must be on PATH.

• Running it – After setup, invoke: ``sh takopi ` Send messages to your bot; prefix with /codex, /claude, /opencode, or /pi to select an engine. Use /<project> <command> to target a registered project (e.g., /happy-gadgets hard reset the timeline`).

• Development – See docs/developing.md and docs/reference/specification.md for contributor onboarding; the repo uses GitHub Actions CI (.github/workflows/ci.yml).

Real‑World Use

A team maintaining several feature branches can takopi init my‑project to register the repo, then from any chat send /my‑project @feat/new‑ui implement the new dashboard. The agent runs in a dedicated worktree, streams progress (logs, file changes, elapsed time) back to the Telegram topic, and a resume line can be copied to continue the same session from a terminal later.

Code Health & Issues

Measured analysis (59 findings, 27 high, 32 medium, 0 low)

SDLC observations (from structure):

• No lockfile → non‑reproducible builds (pyproject.toml declares deps without a requirements.txt/.txt lock).
• CI declares no dependency‑vulnerability scan; no dependabot.yml configured.
• Secrets not found in the repo, but GitHub Actions pins are not locked to commit SHAs (see health audit below).

Code Health Audit (6 findings)

The Bottom Line

takopi delivers a practical Telegram‑bridged runner for LLM‑driven agents, handling worktrees, progress streaming, and resume lines with a clear feature set. The codebase is functional but carries several high‑severity maintainability risks—import cycles, oversized files, duplicated logic, and unpinned GitHub Actions—that should be addressed before relying on it in a mission‑critical pipeline. Teams that need rapid, chat‑driven agent orchestration across multiple repos will find immediate value, provided the listed hygiene items are resolved.

Word count ≈ 480.