Practical agent operations: Telegram hooks, context compaction, quota-aware routing, and adversarial councils.
Four agent-ops systems that keep a single always-on coding agent useful as a phone-controlled assistant for weeks at a time. Built by degenyang on top of Claude Code, Codex CLI, Grok (via the Hermes agent), and Gemini. These are working scripts taken from a live setup and sanitized for publication. Each folder's README covers the problem, the mechanism, the design decisions and the real incidents behind them, and how to adapt it.
| Folder | System | What it does |
|---|---|---|
telegram-harness/ |
Telegram-controlled agent harness | PreToolUse hooks block work until an inbound message is acked, and block replies without a well-formed quota footer. They also enforce output-format rules and tooling guardrails. See the limits below. |
self-compact/ |
Self-/compact context loop | A two-hourly cron launches a detached driver that types /compact into the live session. A Telegram ping confirms each compact. |
llm-routing/ |
Routing by complexity and live quota | The main loop orchestrates. Code, research and bulk text go to Codex, Opus, Sonnet, Haiku, Grok, Groq, Gemini or GPT-6 Luna, chosen by task complexity and remaining quota. |
agent-council/ |
Multi-engine council with adversarial critic | Claude, Gemini and Grok seats answer one brief in parallel. A GPT critic cross-examines them. Seats without live web access are re-run or declared dead. |
flowchart TD
U[Owner on phone] -->|Telegram message| H[telegram-harness<br/>ack gate, usage footer,<br/>format + safety hooks]
H --> O[Main orchestrator<br/>long-lived Claude Code session]
O -->|reply with footer| H
O --> R{llm-routing<br/>complexity x live quota}
R -->|hard code| CX[Codex / Opus subagent]
R -->|medium| SN[Sonnet subagent]
R -->|bulk text| BK[Groq / Gemini / Haiku / GPT-6 Luna]
R -->|research legwork| GK[Grok via Hermes]
R -->|high-stakes decision| C[agent-council]
C --> S1[Claude seat]
C --> S2[Gemini seat]
C --> S3[Grok seat]
C --> CR[GPT critic<br/>blind pass + cross-exam]
S1 & S2 & S3 & CR --> SY[Orchestrator synthesis]
SY --> O
K[self-compact<br/>cron every 2h] -->|detached driver types /compact| O
O -->|compact landed ping| H
The compact loop keeps the orchestrator's context from running out. The hooks keep its rules in force whatever the compact summary drops. Routing keeps the orchestrator's own quota for judgement and synthesis.
Needs Python 3.9+ (Node 18+ and bash for the syntax checks). Nothing here calls a network service, launches an engine, or touches the GUI.
python -m pip install -r requirements-dev.txt # pytest only
python demo/run_hooks_demo.py # sample tool calls -> BLOCK/ALLOW vs expected
python -m pytest -q # regression tests (hooks, usage feed, council, routing,
# compact targeting; runs tests/js via node --test if present)
make check # py_compile, node --check, bash -n (or see Makefile)Excerpt of the demo output (each sample tool call, the hook's decision, and the expected one):
ok ALLOW (expected ALLOW) check_telegram_footer.py reply with footer at the end
ok BLOCK (expected BLOCK) check_telegram_footer.py footer with 999% / 75 min
reason: Footer problem: percentage outside 0-100. Telegram reply must END with a valid ...
ok BLOCK (expected BLOCK) check_telegram_ack.py work before acking an inbound
reason: Telegram inbound(s) awaiting acknowledgement: chat_id=111 message_id=7. ...
ok ALLOW (expected ALLOW) check_telegram_ack.py work after a successful ack
ok BLOCK (expected BLOCK) check_codex_prompt_size.py 30 KB positional codex prompt
...
all cases matched
The tests are plain unittest classes, so python -m unittest discover -s tests also works
without pytest. CI (.github/workflows/ci.yml) runs the same steps on every push.
- Footer hook: checks that a Telegram reply ends with a footer in the right format,
with percentages 0-100 and sane countdowns (or
[usage unavailable]). It does not compare the numbers with live usage, so a plausible made-up footer passes. Correct numbers depend on the model runningusage_footer.pyas instructed. - Ack gate: blocks only the tools listed in its
settings.hooks.jsonmatcher; a tool outside that list is not gated. It judges an ack by the transcript, so it cannot see whether the phone actually showed the message. - Fail open: every hook exits 0 (allows) on malformed input or a transcript it cannot read, so a broken hook never bricks the session but also enforces nothing.
| Part | Runnable code | Instructions the orchestrator follows |
|---|---|---|
telegram-harness/ |
the six hooks, usage/usage-wrapper.sh, usage/usage_footer.py |
standing rules, memory, CLAUDE.footer-rules.md |
self-compact/ |
send_compact.py |
compact_2h.cron.md (when to launch it, the skip check, the landing ping) |
llm-routing/ |
check_codex_usage.py, grok_usage_cli.js, gpt_luna.py |
ROUTING_POLICY.md (which engine gets which task) |
agent-council/ |
run_seats.sh (pass 1, stamping, pass 2), seats/*.py, legacy/dispatch.sh |
the Claude seat, dead-seat rule, synthesis (commands in its README) |
Only the hooks enforce anything mechanically. Everything in the right-hand column depends on the model following its instructions.
- Platform.
- The hooks,
usage_footer.py,check_codex_usage.py(default API path),gpt_luna.pyand the council runner are standard-library Python / bash and run on Windows, macOS and Linux.gpt_luna.pyfinds Codex viaCODEX_BINorPATH;grok_usage_cli.jsfinds Chrome per OS or viaCHROME_BIN. self-compact/send_compact.pyis Windows-only (PyAutoGUI / Win32 window handling).
- The hooks,
- Dependencies (install only what you use):
self-compact/requirements.txt(PyAutoGUI),llm-routing/package.json(Playwright, Grok usage scraper);- engines: Claude Code with the Telegram channel plugin and the claude-hud statusline
plugin (install each as its own docs describe; no plugin identifiers are pinned here);
Codex CLI, signed in; Hermes agent with a
grokprofile; the Antigravity CLI or a Gemini API key.
- Configuration is by environment variables. No paths or accounts are hardcoded.
Each README lists its variables, for example
CLAUDE_USAGE_JSON,CLAUDE_CONFIG_DIR,PROJECT_TMP,SEND_COMPACT_LOG,HERMES_BIN,AGY_BIN,CODEX_BIN,CHROME_BIN,GROK_CDP_PORT,LUNA_WORKDIRandGOOGLE_AI_STUDIO_KEY. - Start small. Begin with the hooks: follow "Installing it" in
telegram-harness/README.md(copy, mergesettings.hooks.json, wire the statusline writer) and check that a reply without a footer is blocked. Then add the compact cron. Add the council last. - Safety defaults.
- The council runs Codex in its
workspace-writesandbox and agy with its permission prompts. The unsandboxed flags the original setup used (--dangerously-bypass-approvals-and-sandbox,--dangerously-skip-permissions) are opt-in viaCOUNCIL_ALLOW_DANGEROUS=1, which prints a warning. send_compact.pykeeps PyAutoGUI's failsafe on and only types into a window whose title matchesCOMPACT_WINDOW_TITLE_RE, whose owning process is inCOMPACT_PROCESS_NAME, that is the only such window, and that is verified to be in the foreground before each keystroke batch.--dry-runreports the target without sending anything. Invscodemode it cannot tell Claude from another shell in the same VS Code window, so prefer standalone mode.- The usage checkers print account emails as
<redacted>unless asked (--show-account).
- The council runs Codex in its
Model names (Opus 5, GPT-6 Luna/Astra, Grok 4.7, Gemini 3.8 Flash, and others) are the ones in use in September–October 2026. Swap in whatever your subscriptions provide.
MIT, see LICENSE.
Suggested GitHub topics: ai-agents, agent-orchestration, claude-code, telegram,
python, automation.