Teledex

Telegram gateway for Codez App Server v2, durable topic sessions, and Codez-first agent workflows.

Install · Config · Architecture · Stack · Security · Troubleshooting

Teledex connects Telegram chats and forum topics to local Codez sessions. It is the Telegram gateway layer for the Codez stack: Telegram handles the operator surface, Teledex owns routing/session state, and Codez App Server v2 owns the agent runtime.

This repository is the full public source projection. It includes the real CLI, Telegram gateway, Codez App Server v2 integration, session/state modules, tests, scripts, docs, config examples, and publication audit tooling.

Runtime Shape

Telegram chat/topic -> Teledex -> Codez App Server v2

Codez App Server v2 is required for the public runtime. Upstream codex exec --json compatibility code remains in the source tree for legacy tests and migration context, but it is not the supported public backend.

Quick Start

git clone https://github.com/Krablante/teledex.git
cd teledex
npm ci
cp examples/teledex.env.example teledex.env
$EDITOR teledex.env
npm run doctor -- --env-file teledex.env
npm start -- --env-file teledex.env

Minimal config:

TELEDEX_BACKEND=app-server-v2
TELEDEX_ENABLE_APP_SERVER_V2=1
TELEGRAM_BOT_TOKEN=replace-me
TELEGRAM_ALLOWED_USER_IDS=replace-me
TELEGRAM_FORUM_CHAT_ID=replace-me
CODEX_BIN_PATH=codex
CODEZ_APP_SERVER_URL=stdio://
TELEDEX_WORKSPACE_ROOT=../teledex-workspace
TELEDEX_STATE_ROOT=../teledex-state

Verify

npm run audit:public is a clean-tree publication audit. Run it before npm ci, or after removing local install artifacts such as node_modules.

npm run audit:public
npm ci
npm run check:syntax
npm test
npm run smoke:config

npm run smoke -- --env-file teledex.env is an optional local runtime smoke for a configured Linux user-service style environment. Live Telegram use still requires your own bot token and allowlisted Telegram user id.

Stack

Layer	Public surface	Responsibility
Codez	Codex-compatible runtime	App Server v2, goal RPC, long-session hardening, prompt pruning
RTK Codex Plugin	Optional Codex plugin	Shell/token safety and bounded output guarding
Pitlane Codex Plugin	Optional Codex plugin	Token-efficient code navigation rewrites
Teledex	Telegram gateway/session layer	Topics, queues, goal UX, and Telegram delivery around durable Codez sessions

Security Boundary

Allowed Telegram users can operate Codez inside TELEDEX_WORKSPACE_ROOT. Use a dedicated workspace and only allow users you trust. The public repo does not ship private runtime state, tokens, personal routing data, local host inventory, logs, sessions, or deployment files.

License

MIT. Teledex is an independent Telegram gateway for the Codez stack and is not an official Telegram, OpenAI, or Codex release.