Crodex

Other AI assistants are good at talking. Talking is easy. The hard part is doing — reading codebases, running commands, editing files, debugging, deploying. That's what coding agents solve, and Codex is the best open-source one.

But Codex lives in your terminal. You have to be at your computer, in a shell, to use it.

Crodex wraps Codex and makes it reachable from anywhere — Telegram, WhatsApp, email. The thinnest possible layer between you and a full coding agent, accessible from your phone. One daemon process, persistent conversations that survive restarts, scheduled jobs, multi-project routing — all running locally on your machine.

You (Telegram / WhatsApp / Gmail)
        |
   [ daemon.py ]
        |
   [ CodexEngine ] ── persistent threads, streaming, mode-based permissions
        |
   [ codex app-server ] ── the actual AI (subprocess)

What it does

• Chat with Codex from your phone. Send a Telegram message, get a response from a coding agent that can read files, run commands, and edit code.
• Multi-project routing. Switch between projects mid-conversation. Each project gets its own agent, working directory, and conversation thread.
• Persistent threads. Conversations survive daemon restarts. The agent remembers what you were working on.
• Scheduled jobs. Cron-like system that runs AI-powered tasks on a timer — daily reports, code checks, reminders. The AI can schedule tasks on itself via MCP.
• Gmail inbox monitoring. Watches your inbox and notifies you via Telegram/WhatsApp when new emails arrive.
• Three modes. talk (conversation only), collaborate (can edit, asks first), build (full autonomous access).
• Second Brain integration. Connects to a local knowledge vault for recall, dump, brief, and todo workflows.
• Skills. Markdown files injected into the system prompt — browser automation, newsletters, custom nag reminders.

Claude Code broker: a pool of real terminals

The most unusual piece. Crodex can also drive Claude Code, not through an API or SDK, but by hosting genuine interactive claude terminals inside Windows pseudo-consoles (ConPTY, via pywinpty) that the daemon owns.

Why the terminal layer rather than the obvious route:

• The SDK and claude -p are not terminals. They give you one-shot calls, not a live session holding context, tools and permissions.
• Channels, the supported way to push into a live session, has open inbound-delivery bugs.
• Operating at the terminal layer depends on no product feature, so no feature change can break it.

Each "pet" is one independent terminal with its own ConPTY, working directory, transcript and lifecycle, addressable by name. They run in parallel.

crodex daemon
  └── ClaudeBroker
        ├── pet "main"     ConPTY ── claude   (own cwd, transcript, job queue)
        ├── pet "master"   ConPTY ── claude   ← orchestrator, can command the others
        └── pet "research" ConPTY ── claude

Design decisions worth calling out:

Replies travel by file, not screen scraping. An injected job tells the agent to write its result as JSON to jobs/claude_replies/<job_id>.json, and a watcher collects it. Parsing a TUI full of ANSI escapes would be brittle; a file is not.

Readiness is detected by normalising output. ANSI stripped, whitespace removed, then matched against known markers, because TUI text arrives interleaved with cursor movements rather than as tidy lines.

Startup is handled, not assumed. The broker answers the bypass-permissions prompt with arrow-down then Enter, and nudges past interstitials with a bounded number of blind Enters.

Crashes self-heal. On PTY exit it backs off, respawns, and re-injects that pet's unfinished jobs. A JSONL ledger lets the system recover across daemon restarts.

Agents can drive it themselves. A local HTTP API (/claude/new, /claude/assign, /claude/status, /claude/raw, /claude/kill) lets the orchestrator pet spawn and command other pets, fanning work out and collecting results.

Architecture

crodex/
├── daemon.py              # Entry point — boots everything, runs forever
├── SOUL.md                # Agent personality
├── IDENTITY.md            # Name, vibe
├── MEMORY.md              # Persistent rules and context
│
├── engine/codex.py        # Brain — manages agents, threads, streaming turns
├── gateway/router.py      # Switchboard — routes between master + worker agents
├── memory/manager.py      # Builds system prompts from personality files + skills
│
├── bridges/
│   ├── base.py            # Shared command dispatcher (25 commands)
│   ├── telegram.py        # Telegram adapter
│   ├── whatsapp.py        # WhatsApp adapter — Node.js sidecar + HTTP polling
│   └── gmail.py           # Gmail monitor — IMAP polling, notifies via other bridges
│
├── brokers/claude_broker.py # Pool of Claude Code terminals in ConPTYs
├── api/scheduler_api.py   # Local HTTP API — scheduler + agent-drivable claude pets
├── jobs/scheduler.py      # Cron scheduler with persistence and failure tracking
├── tools/scheduler_mcp.py # MCP tools so the AI can schedule tasks on itself
├── skills/                # Skill definitions (injected into prompts)
├── utils/                 # Heartbeat, SecondBrain, MemPalace, usage tracking
└── scripts/               # Standalone automation scripts

How a message flows

1. You send a message on Telegram
2. TelegramBridge receives it, checks allowlist
3. Router decides: master agent or project worker?
4. MemoryManager builds a system prompt (SOUL + IDENTITY + MEMORY + skills)
5. CodexEngine acquires a turn lock, gets or creates a persistent thread
6. Codex app-server thinks, reads files, runs commands, edits code
7. Events stream back — thinking, command output, file edits, final answer
8. Bridge formats and sends the response to Telegram

Bridges

Every bridge inherits from BaseAdapter, which provides 25 shared commands (/mode, /cron, /status, /dump, /recall, etc.). A new platform adapter only needs to implement send_text(), start(), and stop() — it gets everything else for free.

Bridge	Transport	Direction
Telegram	Bot API polling	Send + Receive
WhatsApp	Node.js sidecar + HTTP	Send + Receive
Gmail	IMAP polling	Receive only (notifies via Telegram/WhatsApp)

Setup

Prerequisites

• Python 3.11+
• Node.js 18+ (for WhatsApp bridge)
• Codex CLI installed and on PATH
• A Telegram bot token (from @BotFather)
• An OpenAI API key (or OpenRouter key)

Install

git clone https://github.com/theybash/crodex.git
cd crodex
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your tokens and keys

Configure

Edit .env:

OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=...
ALLOWED_USER_IDS=123456789          # Your Telegram user ID
DEFAULT_MODE=collaborate             # talk / collaborate / build
DEFAULT_MODEL=o4-mini
SECOND_BRAIN_PATH=/path/to/vault    # Optional

WhatsApp (optional)

WHATSAPP_ENABLED=true
WHATSAPP_SESSION_DIR=~/.crodex/whatsapp-session
WHATSAPP_ALLOWED_JIDS=919876543210@s.whatsapp.net
WHATSAPP_BRIDGE_PORT=3100

First run requires QR code scan to authenticate the WhatsApp session.

Gmail monitor (optional)

GMAIL_ENABLED=true
GMAIL_IMAP_USER=you@gmail.com
GMAIL_IMAP_PASSWORD=abcd efgh ijkl mnop   # Google App Password
GMAIL_POLL_INTERVAL=60
GMAIL_ALLOWED_SENDERS=boss@company.com     # Empty = all non-automated

Generate an App Password at: Google Account > Security > App passwords.

Run

python daemon.py

Or with PM2 for auto-restart:

pm2 start ecosystem.config.js
pm2 logs crodex

Commands

All commands work on every platform (Telegram, WhatsApp):

Command	What it does
/help	List all commands
/master	Switch back to master agent
/mode <talk|collaborate|build>	Show or change operating mode
/model <name>	Show or change AI model
/status	Current agent, mode, model, workers
/reset	Archive thread, start fresh
/cancel	Interrupt a running turn
/cron add daily 09:00 <prompt>	Schedule a daily job
/cron list	List scheduled jobs
/cron remove <id>	Remove a job
/turns	Recent turn history
/dump <text>	Save to Second Brain
/recall <query>	Search Second Brain
/brief	Daily brief
/todo	Manage tasks
/idea <text>	Quick capture
/usage	Token usage report
/health	Daemon health check

Telegram-only: /torrent <magnet>, /educate <file>, /learn.

Modes

Mode	Permissions
talk	Read-only. Conversation, no file changes.
collaborate	Can edit files. Asks before dangerous operations.
build	Full access. Auto-approves everything.

Scheduling

/cron add daily 09:00 generate a summary of yesterday's git commits
/cron add seconds 3600 check if the deploy is healthy || ok:all systems healthy

The || ok: suffix sets success criteria — the scheduler verifies the AI's response contains that text. Failed jobs get reported. The AI can also schedule tasks on itself via MCP tools.

Multi-project routing

Crodex scans your Second Brain's projects/ folder and creates a worker agent for each project:

You: switch to EnSocial
Crodex: wanna talk to the EnSocial agent?
You: yes
Crodex: [now working in /path/to/ensocial]

Each worker has its own conversation thread, working directory, and personality.

Personality

Crodex's personality is plain markdown:

• SOUL.md — Communication style, values, modes
• IDENTITY.md — Name, emoji, vibe
• MEMORY.md — Persistent rules and context
• skills/*.md — Domain knowledge injected into prompts

No database. No YAML config. Just markdown.

Security

• Runs entirely on your local machine — nothing in the cloud
• Telegram allowlist (ALLOWED_USER_IDS)
• WhatsApp allowlist (WHATSAPP_ALLOWED_JIDS)
• Gmail allowlist (GMAIL_ALLOWED_SENDERS)
• API keys stay in .env (gitignored), never logged
• Singleton lock prevents multiple daemon instances

License

MIT