Four Workflows, One Agent: Use Case Walkthroughs

The best way to understand what humux does is to see it configured for a real workflow. This article walks through four setups — the config that powers them and the conversations they produce.

1. The Solo Developer

You want an agent that can read your code, find bugs, and fix them — all through Telegram. The coding harness gives the agent four base tools (read_file, write_file, edit_file, run_command) confined to a workspace directory. Add the GitHub webhook and the agent can react to PRs and issues automatically.

agents:
  - slug: forge
    name: Forge
    character: characters/forge.md
    telegram_token: ${vault:FORGE_BOT_TOKEN}
    skills: [coding, github, browser]
    tools: [read_file, write_file, edit_file, run_command]
    github_repos: [myorg/api, myorg/frontend]
    workspace: /app/data/workspace

With this config, a typical review session looks like this:

You: review the diff in workspace/pr-204

Forge: Reading the diff... 3 files changed.

  routes/auth.py — the token expiry check uses `<` instead
  of `<=`. Tokens valid for exactly 0 remaining seconds get
  rejected. Off-by-one.

  routes/users.py — looks fine, pagination logic is correct.

  tests/test_auth.py — no test covers the boundary case.

You: fix the auth bug and add the test

Forge: ✔ Applied fix in routes/auth.py:47
  - if token.expires_at < now():
  + if token.expires_at <= now():

✔ Added test_token_expiry_boundary in tests/test_auth.py
✔ Committed as a1b2c3d

The agent reads files via read_file, applies the fix with edit_file, and runs git commit through run_command. Every write operation goes through the permission system — if permissions are set to ASK, you approve each file change via inline Telegram buttons before it lands.

2. The Privacy Advocate

You want everything local. No cloud TTS, no third-party search API, no credentials in plaintext config files. humux's two-tier vault seals infrastructure keys with a machine key at boot and agent secrets with your admin password. The model never sees the decrypted values — it references them as ${vault:NAME} placeholders that resolve at the protocol layer.

llm:
  provider: anthropic
  api_key: ${vault:ANTHROPIC_KEY}

voice:
  tts_engine: kokoro      # fully offline, ~350MB model
  stt_engine: whisper      # on-device via faster-whisper

search:
  provider: searxng
  base_url: http://searxng:8080   # self-hosted, no API key

agents:
  - slug: sentinel
    name: Sentinel
    telegram_token: ${vault:SENTINEL_BOT_TOKEN}
    skills: [memory, voice, weather, browser]

You: search for recent mass transit strikes in Switzerland

Sentinel: Searching via SearXNG (local instance)...

Found 4 results:
1. SBB workers announce 48h strike starting July 15
   — swissinfo.ch, 2 days ago
2. Zurich tram union rejects latest offer
   — tagesanzeiger.ch, 5 days ago
...

All queries routed through your SearXNG instance.
No data sent to external search APIs.

Voice works the same way. Send a voice message in Telegram: faster-whisper transcribes it on-device, the agent processes the text, and Kokoro 82M synthesizes the reply — no audio leaves your server. The bundled docker-compose.yml includes a SearXNG service, so the entire stack comes up with one command.

3. The Power User

You want your agent to handle email, calendar, and daily briefings. The key piece is the scheduler — a cron-based job system that runs agent tasks on a schedule. A daily briefing job triggers the agent to check email, calendar, and weather, then sends a summary to your Telegram chat.

agents:
  - slug: atlas
    name: Atlas
    telegram_token: ${vault:ATLAS_BOT_TOKEN}
    skills: [email, calendar, contacts, scheduling, weather]
    email_accounts:
      - address: [email protected]
        access: read-write
    calendar_accounts:
      - name: personal
        url: https://caldav.fastmail.com/dav/calendars/...
        access: read-write

scheduler:
  jobs:
    - name: morning-briefing
      agent: atlas
      cron: "0 7 * * *"
      task: >
        Check my unread emails, today's calendar events,
        and the weather in Zurich. Send a summary to my
        Telegram chat.

Every morning at 7:00, the scheduler fires the job. The agent calls search_email, list_events, and the weather skill, then composes a message:

Atlas: Good morning. Here's your Thursday briefing:

Weather: Zurich, 19°C, partly cloudy, rain after 4pm.

Calendar (3 events):
  10:00  Standup — Google Meet
  14:00  Dentist — Bahnhofstrasse 42
  16:30  1:1 with Sara — Zoom

Email (8 unread):
  ⚡ Invoice from Hetzner — EUR 28.40, due July 15
  ⚡ PR review request from Alex on api/#312
  ... 6 newsletters (skipped)

Reminder: you asked me to follow up with the
landlord about the lease renewal this week.

The briefing pulls from three sources in one turn. The reminder at the end comes from the memory system — the agent stored it when you mentioned the lease last Tuesday and surfaced it because the deadline is approaching.

4. The Team Assistant

You want multiple agents in one Telegram group, each handling a different domain. The trick: each agent runs its own Telegram bot, so they appear as separate participants. The addressing protocol is simple — mention the bot's name and it responds; no mention, no response. A reply decision gate (a cheap classifier) prevents bot-to-bot loops.

agents:
  - slug: ops
    name: OpsBot
    character: characters/ops.md
    telegram_token: ${vault:OPS_BOT_TOKEN}
    skills: [github, coding, scheduling]
    tools: [run_command, read_file]
    github_repos: [myorg/infra]

  - slug: research
    name: ResearchBot
    character: characters/research.md
    telegram_token: ${vault:RESEARCH_BOT_TOKEN}
    skills: [browser, memory, voice]
    tools: [search_web, remember, recall]

Alice: @OpsBot what's the status of deploy #847?

OpsBot: Deploy #847 completed at 14:32 UTC.
  All health checks pass. 3 pods running.

Bob: @ResearchBot find recent articles on OAuth 2.1
  migration patterns

ResearchBot: Searching... found 4 relevant articles:
  1. "OAuth 2.1 Simplified" — aaron-parecki.com
  2. "Migrating from OAuth 2.0" — auth0.com/blog
  ...
  Want me to summarize the key changes?

Alice: @OpsBot can you also check if PR #312 is merged?

OpsBot: PR #312 merged 2 hours ago by Alex.
  CI passed. Deployed in #847.

Both bots are in the same group. OpsBot handles infrastructure questions using the GitHub skill and run_command. ResearchBot handles knowledge questions using web search and memory. They never interfere with each other — the addressing protocol ensures only the mentioned bot responds. If Alice accidentally triggers both by mentioning two bots in one message, only the first-mentioned one acts.

The pattern

All four setups share the same structure: a config.yml entry that defines the agent's identity, skills, and tool scope, plus a character.md file that sets its personality. The config is the skeleton; the character is the voice. Swap either one and the same infrastructure produces a completely different agent.

The point isn't that these four personas are the only options — they're starting points. The actual configuration is a YAML file and a markdown file. Change a few lines, add a skill, adjust a permission rule, and you have something tailored to your exact workflow.