This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
gotd/td is a pure-Go implementation of the Telegram MTProto 2.0
protocol and a client built on top of it, for users and bots.
- ARCHITECTURE.md — the layered design (binary → transport → crypto →
mtprotoconnection →pool→ high-leveltelegram.Client), the request lifecycle, the code generation pipeline, and what every package does. Read it before making non-trivial changes; it is the authoritative map of the codebase and is kept current. - CONTRIBUTING.md — coding guidelines (Uber style), testing-on-test-servers rules, and the allocation-testing expectations for hot paths.
../../telegram (i.e. /src/telegram) holds local clones of the official Telegram source — use them
to resolve protocol/API questions, error semantics, and undocumented behavior rather than guessing:
| Repo | Use for |
|---|---|
tdlib |
Canonical client behavior; the reference this project aims for parity with |
tdesktop |
Telegram Desktop; source of the api.tl schema and MTProto details |
android |
Official Android client (Java/C++) |
ios |
Official iOS client |
telegram-bot-api |
Bot API server; bot-specific semantics |
mtproxy |
MTProxy reference (faketls, obfuscation) |
tgcalls |
Voice/video call protocol reference |
cd ../../
mkdir telegram
gh repo clone telegramdesktop/tdesktop
gh repo clone DrKLO/Telegram android
gh repo clone tdlib/td tdlib
gh repo clone tdlib/telegram-bot-api
gh repo clone TelegramMessenger/Telegram-iOS ios
gh repo clone TelegramMessenger/tgcalls
gh repo clone TelegramMessenger/MTProxyGo 1.25 (go.mod). CI runs against oldstable and stable.
make test # go test --timeout 5m -race ./... (see go.test.sh)
make coverage # coverage run, filters generated tl_*_gen.go (see go.coverage.sh)
make generate # regenerate code from _schema/*.tl (go generate ./...)
make check_generated # generate + `git diff --exit-code`; CI fails if generated code is stale
golangci-lint run # lint; config in .golangci.ymlRun a single test / package:
go test ./telegram/... -run TestClient_Connect
go test -race ./mtproto/...-
Generated code. The
tg,tg/e2e,mt, andtgtracepackages (and anytl_*_gen.gofile) are generated from_schema/*.tlbycmd/gotdgen(templates ingen/). Never edit*_gen.goby hand — change the schema or the generator and runmake generate. CI enforces this viamake check_generated. -
Schema updates are deliberate:
make download_schema generatepulls a new layer from tdesktop. Don't bump layers early (multiple in-flight layer versions cause breakage) — see CONTRIBUTING.md. -
Offline testing. Use
tgmock(a mocktg.Invoker) to unit-test client helpers, andtgtest(an in-process pure-Go Telegram server, withtgtest/clusterfor multi-DC) for end-to-end tests. Tests run with-race; never test against production Telegram servers. For time-dependent logic (pings, retries, timeouts) use theclockabstraction backed bygotd/neo, nottimedirectly. -
No runtime reflection.
binserialization is non-streaming and reflection-free by design; keep hot paths allocation-light and verify withtestutil.ZeroAlloc/testutil.MaxAlloc(see CONTRIBUTING.md "Testing allocations"). -
Context error semantics. On context cancellation, return the wrapped
ctx.Err(), never the underlying transport error. -
go-faster/errors.Wrapdoes not short-circuit on nil.errors.Wrap(nil, msg)returns a non-nil error (unlikepkg/errors). Guard withif err != nil { return errors.Wrap(err, ...) }before wrapping a result that may be nil. -
New external dependencies should be isolated in a subpackage so they don't leak into the core
clock/mtprototree (e.g.clock/ntpkeepsbeevik/ntpout of core).
- Conventional Commits (enforced by commitlint in CI), e.g.
feat(telegram): ...,fix(rpc): .... - Branch off
main; one focused PR per change.