Skip to content

About

Practical agent operations: Telegram hooks, context compaction, quota-aware routing, and adversarial councils.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

agent-infrastructure

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.

The four systems

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.

How they fit together

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
Loading

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.

Quick start (offline, about a minute)

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.

What the hooks can and cannot enforce

  • 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 running usage_footer.py as instructed.
  • Ack gate: blocks only the tools listed in its settings.hooks.json matcher; 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.

Scripts vs instructions

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.

Running it for real

  • Platform.
    • The hooks, usage_footer.py, check_codex_usage.py (default API path), gpt_luna.py and the council runner are standard-library Python / bash and run on Windows, macOS and Linux. gpt_luna.py finds Codex via CODEX_BIN or PATH; grok_usage_cli.js finds Chrome per OS or via CHROME_BIN.
    • self-compact/send_compact.py is Windows-only (PyAutoGUI / Win32 window handling).
  • 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 grok profile; 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_WORKDIR and GOOGLE_AI_STUDIO_KEY.
  • Start small. Begin with the hooks: follow "Installing it" in telegram-harness/README.md (copy, merge settings.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-write sandbox and agy with its permission prompts. The unsandboxed flags the original setup used (--dangerously-bypass-approvals-and-sandbox, --dangerously-skip-permissions) are opt-in via COUNCIL_ALLOW_DANGEROUS=1, which prints a warning.
    • send_compact.py keeps PyAutoGUI's failsafe on and only types into a window whose title matches COMPACT_WINDOW_TITLE_RE, whose owning process is in COMPACT_PROCESS_NAME, that is the only such window, and that is verified to be in the foreground before each keystroke batch. --dry-run reports the target without sending anything. In vscode mode 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).

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.

License

MIT, see LICENSE.

Repository metadata

Suggested GitHub topics: ai-agents, agent-orchestration, claude-code, telegram, python, automation.

About

Practical agent operations: Telegram hooks, context compaction, quota-aware routing, and adversarial councils.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages