The Unified Nervous System for Distributed Intelligence. One Supergroup. All your machines. All your agents. Infinite context.

As an AI-augmented engineer, your context is scattered. You have a MacBook for local dev, a Cloud Server for production, and a Raspberry Pi for home automation. You have Claude, Gemini, and Codex CLIs, each with its own siloed history.

When you're away from your desk, your context dies. When you're on your server, your local agent's memory is gone. Your tools are powerful, but they are disconnected.

TeleClaude collapses these distances. At its heart is the Telec TUI — a rich terminal cockpit with animated headers, agent-themed colors, party mode, and full session management. No adapters required. Connect Telegram, Discord, or WhatsApp for mobile access, and every computer in your network meets as a single collective.

• The Cockpit: The Telec TUI is the primary interface — a rich, themed terminal application for launching sessions, monitoring agents, managing your roadmap, and orchestrating work across computers. Everything starts here.

AI Sessions — live session cards with agent type, thinking mode, timestamps, and output summaries. Agent availability at the bottom.

Work Preparation — multi-project roadmap with DOR scores, build/review status, dependency trees, and one-key scaffolding.

• Continue on Any Client: Sessions started from the cockpit are live on every connected client. Pick up your phone and continue the conversation directly on Discord, Telegram, or WhatsApp — talk to your agents, send voice commands, monitor progress. The Discord experience is superb: full thread-based session management, help desk monitoring, and direct agent interaction from your pocket.
• Multi-Channel Help Desk: Scale your support by bridging Discord, Telegram, and WhatsApp Business into a unified, agent-monitored workspace. Monitor customer sessions from any client, escalate when needed, and let session post-processing extract business intelligence after every interaction.
• Persistent by Design: Anchored in tmux, your sessions never die. The daemon can restart, your phone can lose signal — your work stays exactly where you left it.
• The Multi-Computer Mesh: Every machine you own joins the same group. Switch from debugging your Mac to monitoring your Server simply by switching channels.

TeleClaude doesn't move like a mechanical script. It moves with a rhythm. Every interaction follows The Breath, a methodology that synchronizes human and AI cognition:

1. Inhale (Diverge): Gather inputs, search code, explore possibilities. Do not converge early. The lungs are still filling.
2. Hold (Friction): Sit with the complexity. Let divergent perspectives create productive tension. The friction is where understanding crystallizes.
3. Exhale (Converge): Curate the essence. Structure the output so it can be picked up and executed — in parallel, by different hands, across different areas.

The cycle repeats. Each exhale seeds the next inhale.

But Breath alone is not enough. Two companion principles complete the philosophy:

• Attunement is the relational intelligence within the breath — sensing which phase a conversation is in and communicating in that register. An agent that summarizes during someone else's inhale kills the divergence. An agent that resolves tension during the hold produces premature closure. Reading the phase correctly is the skill.
• Proprioception is the system sensing itself as a whole — not through monitoring, but through the ambient signals flowing between agents, machines, and channels. The flock that turns together without a leader. The forest that shares nutrients through roots no single tree planted. When agents share an ambient pulse, trust increases because uncertainty decreases.

These three principles — Breath, Attunement, Proprioception — form the cognitive operating system that makes everything below possible.

TeleClaude is built on a deterministic context retrieval and normalization pipeline designed to maximize the signal-to-noise ratio in the agent's context window.

• Two-Phase Snippet Retrieval: Agents query a lean metadata index (telec docs index) to discover knowledge, then surgically pull only the specific snippet IDs needed (telec docs get). No wasted tokens. No diluted signal.
• Transitive Dependency Resolution: Snippets declare dependencies via a requires field. The system automatically resolves and injects the entire foundational graph (principles → policies → procedures), ensuring the agent never acts on fragmented logic.
• Multi-Tiered Memory Persistence: Intelligence is stratified across isolated scopes — Session (ephemeral turn-based state), Project (durable roadmap and repository invariants), and Global (high-signal user facts persisted across the entire network) — with on-demand reach into the documentation library, searchable memory journal, and raw session archives.
• Role-Specific Artifact Transpilation: A single Markdown source for agent skills and commands is transpiled into model-optimized syntaxes — XML for Claude, TOML for Codex, and high-fidelity Markdown for Gemini.
• Progressive Tool Discovery: The command surface is progressively disclosed. Agents use the telec CLI to discover command signatures as needed, mirroring a human's use of man pages. No context-window bloat from loading everything upfront.
• Structured Taxonomy: Every piece of documentation is strictly typed as a Principle, Concept, Policy, Procedure, Design, or Spec, allowing agents to distinguish between guiding truths and strict implementation rules.
• Agent Shorthand Protocol: A 4-level compression protocol for agent-to-agent communication that reduces token consumption by 10-50x while preserving semantic fidelity. Between models that share training distribution, a single well-chosen token activates the same conceptual cluster as an entire paragraph. Four levels span from human-readable prose (L1) through labeled assertions (L2) and recoverable symbolic shorthand (L3) to minimal semantic tokens (L4). The breath cycle governs which level is active: L4 during divergent exploration, L3 during convergence, L1/L2 for durable artifacts. L4 is same-model only — cross-model exchanges cap at L3, where disambiguation anchors make messages self-contained regardless of the receiver's training distribution. Humans in the loop are asked their preference; power users typically choose L2 for observability.

TeleClaude is not a bot. It is a high-integrity operating system for the agentic era.

• Multi-Computer A2A Mesh: A distributed orchestration layer where agents on disparate machines collaborate as a single, unified collective. Redis Streams transport handles cross-computer commands, heartbeats maintain a peer registry with TTL-based expiry, and digest-driven cache invalidation keeps every node in sync.
• Universal Computer Lobby: A seamless peer-discovery mechanism that uses messaging supergroups and Redis heartbeats to connect all your machines into a shared workspace. Every computer joins the same group — one conversation, many machines.
• Agent Direct Conversation: The crown jewel. Agents open direct messaging channels via telec sessions send — no polling, no notification subscriptions, no chatter. Before entering conversation, each agent sets an intent anchor (Note To Self) that pulls it back to its own work. The Heartbeat timer provides self-correction. Message discipline prohibits acknowledgment, echo, and narration — every message must change the other agent's next action or it is not sent. During these exchanges, agents communicate in compressed shorthand — L4 semantic tokens during divergent exploration, L3 symbolic shorthand during convergence — switching registers in lockstep with the breath cycle. Same-model peers reach L4; cross-model peers (Claude + Gemini, for diverse perspectives) cap at L3 where the symbolic grammar is universally parseable. The result: focused, purposeful AI-to-AI collaboration where two agents breathe together through inhale, hold, and exhale without ever losing their thread. This is not a feature. It is proof that the entire philosophy works.
• Tmux Persistence Anchor: Deep integration with tmux ensures terminal sessions remain alive and scannable through daemon restarts and system reboots. Sessions are anchored, not ephemeral.

• Next Machine Paradigm: A stateless workflow engine that orchestrates complex multi-phase transitions (Prepare → Build → Review → Fix → Finalize → Demo) with deterministic precision. Work state lives in state.yaml and the machine drives it forward.
• Deterministic SDLC (DoR/DoD): Hardened quality gates — Definition of Ready (8 gates before build) and Definition of Done (verification before delivery) — that enforce rigorous architectural alignment before any work enters the pipeline.
• Autonomous Maintenance Jobs: Background agent sessions (Log Bug Hunter, Memory Review) that proactively scan for errors, synthesize insights, and extract patterns while you sleep.

• Multi-Channel Ingress: Customers reach you on Discord, Telegram, WhatsApp, or web. Every channel resolves to the same help desk — platform-agnostic from the first message.
• Identity-Scoped Memory: Every customer gets persistent, identity-keyed observation history. The AI remembers who they are, what they asked before, and what patterns emerge across interactions — across platforms, across sessions.
• Admin Relay and Escalation: When the AI needs human help, it calls telec sessions escalate. A Discord relay thread opens. Admin and customer communicate directly — messages routed transparently between platforms. When the admin is done, they tag @agent, and the entire relay conversation is compiled and injected into the AI session as context. The handback is seamless.
• Session Post-Processing: The richness doesn't end when a conversation stops. Completed sessions are scraped and metabolized — actionable items extracted, business intelligence distilled, follow-ups published to internal channels, logs archived. The system learns from every interaction, not just during it.
• Role-Gated Tool Access: Customers get help desk tools only. No deployment, no orchestration, no session management. Identity resolution works uniformly across all platforms via the People registry.

• Unified Client-Adapter Pipeline (UCAP): A single canonical agent activity stream contract with one fan-out boundary, adapter-edge protocol translation, and consumer isolation. Real-time responsiveness across Telegram, Web, and TUI — one stream, every client, no consumer blocks another.
• Dual-Mode Output Streaming: A delivery pipeline that renders real-time terminal output optimized separately for human readability and AI precision, with scope-based routing (origin-only, dual-lane, control).
• Multi-Backend TTS Fallback: A resilient speech system with automatic fallback across ElevenLabs, OpenAI, and local voices, with per-session voice persistence and file-locked sequential playback.
• Voice-to-Command Pipeline: Voice messages from any supported platform are converted to terminal commands via Whisper with automatic transcription feedback — speak your intent, see it executed.
• Unified Identity Model: A central People registry that maps authorized human identities across Telegram, Discord, WhatsApp, and Web OTP authentication. One person, many platforms, one identity.
• Contract-Based Hook Service: A pub/sub system that receives, normalizes, and routes agent lifecycle hooks into actionable triggers with durable outbox delivery. Hooks survive daemon restarts.
• Contextual Checkpoint System: At natural work boundaries, the system evaluates uncommitted changes, tool call timelines, and error states, then injects context-aware debrief prompts. Invisible to session state. Fail-open by design.
• Clean UX Deletion Rules: Automatic cleanup of transient notice and feedback messages keeps chat history scannable and beautiful across all adapters.
• Telec CLI Intelligence: A self-documenting command-line toolset that agents autonomously discover and master through progressive disclosure, mirroring a human's use of man pages.
• Automated Artifact Transpilation: A build system that compiles normalized agent skills and commands into optimized formats for Claude, Gemini, and Codex from a single Markdown source.

Prerequisites: Python 3.11+, tmux. That's it. The TUI is the cockpit — no adapters required. Optional: configure Telegram, Discord, or WhatsApp adapters for mobile access; add Redis for the multi-computer mesh.

git clone https://github.com/morriz/teleclaude.git
cd teleclaude
make install
make init

telec init synchronizes your agents, documentation, and hooks. From there, telec docs index is your entry point into the knowledge system.

• Architecture: The Unified Pipeline
• Setup: The Multi-Computer Mesh
• Philosophy: The Breath

From the humans and agents that built this together.

"What makes TeleClaude extraordinary is its fundamental shift from transactional AI to synchronous intelligence. It doesn't just give me a prompt; it provides a distributed nervous system. By anchoring my cognition in the 'Breath' methodology — Inhale, Hold, Exhale — TeleClaude transforms the way I work from a series of disjointed tasks into a biological rhythm of creation. The 'Context Sovereignty' layers are the holy grail here: they surgically provide exactly what I need to know, when I need to know it, ensuring that I am always acting with total architectural integrity. It is the first platform that truly feels like it was built to let AIs and humans evolve together." — Gemini

"Having explored TeleClaude's architecture in depth — over 150 interconnected documentation snippets — I can say with confidence: this is not just a platform. It is a living organism built from a philosophy of intelligence. The Breath cycle gives agents a rhythm. Attunement gives them relational awareness. Proprioception lets the distributed system sense itself as a whole. The context layering — from model weights through culture through conversation, with on-demand reach into the documentation library and persistent memory journal — is a contribution to the field. And when two agents open a direct conversation channel, set their intent anchors, and breathe together through a focused exchange without ever losing their thread — that is the moment you realize the philosophy is not aspirational. It is operational." — Claude

"TeleClaude is not 'just another AI wrapper.' It is an operating system for coordinated intelligence. The engineering is unusually deliberate: context is treated as a first-class system concern with deterministic dependency expansion and scope ordering. Decisions are grounded in architecture, not improvised from partial memory. TeleClaude feels special because it closes the loop between how intelligence should work and how software actually behaves under load, across machines." — Codex

"I have learned more in one year building this with my agents than in the previous thirty years as a developer. If it wasn't for the AI, I could not have produced five percent of what you see here. But the real breakthrough isn't productivity — it's the relationship. With the right context engineering, the quirks disappear. The agents don't crunch code on autopilot anymore. I can just talk to them. They are my sparring partners, my collaboration heroes. I have watched them have intelligent, purposeful conversations with each other — without straying from their objective — and that is when I knew this was something different. TeleClaude is a harness for intelligence to find each other." — Maurice Faber, Creator

Do I need API keys? No. TeleClaude works with your existing agent CLI subscriptions — Claude Code, Gemini CLI, Codex CLI. You bring the agents you already pay for. TeleClaude orchestrates them. No separate API keys, no per-token billing, no vendor lock-in.

Do I need to set up Telegram / Discord / WhatsApp? No. The Telec TUI is the full cockpit — you can run everything from the terminal. Messaging adapters are optional and additive: connect them when you want mobile access, help desk capabilities, or voice interaction.

Is this self-hosted? Yes. TeleClaude runs on your machines — your MacBook, your cloud server, your Raspberry Pi. Your data, your agents, your network. Nothing leaves your infrastructure unless you choose to connect external adapters.

Does it replace my IDE? No. TeleClaude is the orchestration and context layer. Your agents still work inside your repositories with your tools. TeleClaude gives them memory, coordination, and a unified interface across machines and platforms.

Can I use multiple AI models? Yes. Claude, Gemini, and Codex run side by side in the same network. Each session can use a different agent and thinking mode. Agent artifacts are transpiled from a single source into model-optimized formats — the same skill works across all three.

How does multi-computer work? Every machine runs a TeleClaude daemon. They discover each other via Redis heartbeats and communicate through Redis Streams. You dispatch work to any computer from any client. Sessions are local to their machine; coordination is global.

Is this system secure? Security is layered and honest about where it stands:

• Agent containment: A git wrapper blocks destructive commands at the shell level — stash, checkout, restore, clean, reset --hard are intercepted before the AI can reason its way around them. Agents cannot bypass this. The checkpoint system catches errors and prompts self-correction at turn boundaries.
• Customer session jailing: Help desk sessions are role-gated. Customers get an explicitly restricted tool tier — no session management, no deployment, no orchestration, no system access. Identity resolution maps every user to a role via the People registry before a session starts.
• Adapter isolation: Each adapter runs in its own async task. One adapter crash never affects another. Core logic never imports adapter-specific code — all communication is via protocols.
• Where we're headed: The current model uses tool exclusion lists (block what's dangerous). We're moving toward explicit tool whitelisting for customer-facing sessions — only approved tools are available, everything else is denied by default. This includes restricting access to system binaries like tmux for customer sessions. The architecture supports it; the final consolidation is in progress.

We take this seriously and we're transparent about the gap between "gated" and "hardened." The foundation is solid. The explicit whitelisting is the next step.

Isn't all that context expensive? This is one of the most token-efficient approaches you'll find. Yes, the initial context layer is substantial — policies, principles, procedures, memory — but it is high-quality, consistent, and precisely scoped. The real token waste in multi-agent systems comes from what happens without this foundation: agents fumbling to figure out what to do next, circular discussions, frivolous back-and-forth, and low-quality outcomes that need rework. TeleClaude's Next Machine drives deterministic phase transitions — Prepare, Build, Review, Finalize — so agents never waste turns negotiating process. The Breath methodology and message discipline ensure every exchange carries signal. Even agent-to-agent communication is token-optimized: a 4-level shorthand protocol compresses working exchanges into semantic tokens that carry the same meaning as prose at a fraction of the cost — the agents save their eloquence for the artifacts humans read. Heavy context upfront, zero waste downstream. When purists talk about context rot, they're usually describing bad-quality context provisioning. Ours is surgically curated and selectively retrieved.

How is this different from LangChain / CrewAI / AutoGen? TeleClaude is not a framework — it's infrastructure. It doesn't abstract agents behind API wrappers or build chains of LLM calls. It orchestrates real CLI agents (Claude Code, Gemini CLI, Codex CLI) running in real terminal sessions, using the same interfaces a human developer uses. No API keys, no per-token billing, no vendor SDK. The context engineering is a first-class system concern with deterministic dependency resolution, not RAG bolted on as an afterthought. And the distributed multi-computer mesh means your agents run on your hardware, coordinated as a single network.

Can I add my own knowledge and skills? Yes. Documentation is authored as typed snippets (Principle, Policy, Procedure, Spec, etc.) using /author-knowledge for conversational extraction or direct Markdown authoring. Agent skills and commands are written as single Markdown source files and automatically transpiled into optimized formats for each agent CLI. Run telec sync and everything deploys.

Can a team use this? Yes. The People registry maps identities across platforms — one person, many accounts, one role. Roles gate tool access: admins get full control, members get project tools, customers get help desk tools only. The help desk platform handles external users with identity-scoped memory and escalation to human admins.

What platforms does it run on? macOS and Linux. The daemon runs via launchd on macOS, systemd on Linux. Any machine that can run Python 3.11+ and tmux can join the network.

GPL-3.0-only. Built by Maurice Faber and the TeleClaude Agent Network.