use cases

A whole team's worth of work,
on your hardware

humux is a squad of agents that acts like a full team of experts at your disposal. Here are five ways people point it at their most ambitious ideas — starting with the one it was built for.

01 — the flagship

The Founder

From idea to shipped product, without hiring anyone

You have an idea you can't stop thinking about, and nobody to build it with. Hiring costs money you haven't raised and months you don't have, so the idea stays a document. That's where most products die — not from being wrong, from being one person short.

A humux squad is the team you would have hired. A lead researches the market and breaks the idea into issues. A developer picks them up and opens PRs. A marketer writes the positioning and the landing copy. A QA reviews what ships before your first user does. They coordinate in GitHub — real issues, real assignees, real review comments — while you sit in one Telegram group, reading the highlights and saying yes or no.

You stay the founder: taste, direction, the final word. You stop being the bottleneck for everything else.

Agent squad GitHub App identities Deep research Coding harness Hosted artifacts
Telegram — Founding Team
You: @kindral I want to build a tool that turns receipts into expense reports for freelancers. is there a business here?
kindral (lead): Give me an hour. Market size, who's already doing it, what they charge.
— 40 minutes later —
kindral: 6 incumbents, all built for companies with an accounting team. Freelancers churn out of them within 3 months. The gap is one person, one shoebox of receipts, one export their accountant accepts. Narrow, but real.
You: that's the one I want. build the smallest version.
kindral: Milestone v0-shoebox created. 5 issues, assigned.
seniordev: Took #3 — receipt upload + OCR pipeline.
marketeer: Took #5 — positioning + landing page. First draft tonight.
qa: Watching #3. I'll review the PR when it lands.
You: 👍

One group chat. Four agents, each with their own bot, model and memory.

What the first week actually looks like

Nothing here is a demo script. It's issues, branches, PRs and review comments — the same trail a human team leaves behind, so you can read it later and know what happened.

01

Monday — you type one sentence

The lead runs deep research over the live web, comes back with competitors, pricing, and where the gap is — sources cited, so you can check the claims instead of trusting them.

02

Monday night — scope, not vibes

You approve a direction in the group chat. The lead opens a GitHub milestone and five issues with owners and acceptance criteria. Anything it can't decide gets labeled needs-founder and comes back to you.

03

Tuesday — code appears

The developer works in a confined workspace: reads, writes, edits, runs the tests, pushes a branch and opens a PR under its own GitHub App identity. Not a snippet in a chat window — a pull request.

04

Wednesday — someone says no

QA reviews the PR, finds the upload path that breaks on 12MB scans, and requests changes on the issue. The developer pushes a fix. You read the thread over coffee, or you don't.

05

Thursday — words and a page

The marketer ships positioning, headline options and a landing page — published as a hosted artifact you can open on your phone and reject in one message.

06

Friday — you have a product

Milestone closed, PRs merged, page live. What you spent: five decisions and the API bill. What you didn't spend: a seed round and three months of interviews.

github.com/you/shoebox — issue #3
kindral opened this issue
Receipt upload + OCR pipeline. Accept JPG/PNG/PDF up to 20MB, extract vendor, date, total, VAT. Fall back to manual entry when confidence < 0.8. Assignee: seniordev.
seniordev linked a pull request — #41
7 files changed. Added the parser, the confidence gate and 14 tests. All green locally.
qa requested changes
Upload times out over ~12MB — the read is buffered into memory before the size check runs. Check first, then stream. Test case attached.
seniordev pushed 1 commit
Size check moved ahead of the read, upload streamed to disk. 20MB scan now completes in 3.1s.
qa approved
✔ Merged into main — issue #3 closed
Every agent appears as its own GitHub App — distinct name, avatar, commit author. You can tell who did what a month later.
Work is dispatched through issues, not prompts — the backlog is the source of truth, and it survives restarts.
Any agent can fan out subagents in parallel under a shared budget — watch the whole run tree with /subagents, cancel anything that wanders.
Nothing leaves your box except the model calls you configure. Your idea, your repo, your keys, one container.
02 — every day

The Solo Developer

Your pair programmer, researcher, and release manager

You want an agent that works with your codebase, not in a separate chat window. The coding harness lets it read, write, and edit files in a confined workspace. It greps, refactors, runs commands, and commits — from Telegram, the CLI channel, or the admin UI.

"Review the PR in /workspace and summarize the changes"
"Read the error log and suggest a fix"
"Run tests, check the results, and open an issue if any fail"
"Research the best Rust HTTP frameworks and give me a cited comparison"
Coding harness Deep research Web search GitHub integration
Telegram — humux
You: can you review the commit in workspace/pr-137?
humux: Looking at the diff in pr-137...
Found 3 files changed. The auth middleware has a token expiry check that uses < instead of <= — off-by-one, tokens still valid for 1 second after expiry get rejected.
Suggested fix: expires_at <= now()
You: good catch. apply it.
✔ Fix applied. Commit a1b2c3d ready to push.
bash — vault check
docker ps
CONTAINER ID IMAGE STATUS
abc12345 ghcr.io/mattmezza/humux:latest Up 3 days
# No cloud. No telemetry. No third-party AI.
# Your keys. Your data. Your rules.
03 — sovereignty

The Privacy Advocate

Full data sovereignty. Zero cloud dependencies.

Your agents should not send your emails, contacts, or calendar to a third party. humux runs everything in a single Docker container on your own hardware. API keys are sealed in an encrypted vault — never exposed to the model context. Memory stays in your SQLite database. No telemetry, no phoning home.

Offline-capable voice (Kokoro 82M) — no cloud TTS needed
Encrypted two-tier vault with Bitwarden import
Credentials resolve from vault — never enter model context
Self-contained: SQLite, no external databases. Optional sidecars for heavy models
Vault encryption Offline voice Local storage No telemetry
04 — the foundation

The Power User

Email triage, calendar management, task automation

Your inbox is overflowing, your calendar is fragmented across Google and iCloud, and recurring tasks eat your week. humux reads and manages email (per-agent mailboxes), checks and creates calendar events, searches contacts, and runs scheduled work — from Telegram, WhatsApp, the CLI channel, or the admin UI.

"Summarize my unread emails and flag anything urgent"
"Schedule a 30min meeting with Alex next Tuesday at 2pm"
"Send a morning briefing daily at 7am with weather, schedule, and top emails"
"Find John's phone number in contacts and send him a WhatsApp message"
Email triage Calendar Scheduled jobs Contacts
Telegram — humux
You: morning briefing
humux: Good morning! Here's your briefing for Thursday, July 2:
☀️ Weather: 22°C, partly cloudy
📧 14 unread — 2 from your boss, 1 newsletter
📅 3 events today: Standup 10am, Dentist 2pm, Review 4pm
🔔 Reminder: PR review due tomorrow
Telegram — Team Chat
Alice: @support-bot can you check the deploy status?
support-bot: Deploy #847 completed successfully at 14:32 UTC. All health checks pass.
Bob: @research-bot what's the latest on the auth rewrite?
research-bot: I found 3 recent articles on OAuth 2.1 migration. PR #312 in review. Want me to summarize?
— Multiple agents in one group. Each responds only when addressed. No loops. —
05 — at work

The Team Assistant

Multiple agents, one group chat, zero collisions

Your team needs different agents for different domains — support, research, devops. Per-agent bots let you drop several into one Telegram group. Each has its own context, tools, model, and identity. They reply only when addressed and ignore other bots — no infinite loops, no confused replies.

Each agent has its own Telegram bot token and isolated context
Agents tag who said what in shared history — full audit trail
Per-chat permissions: control who can DM each agent in each group
Fan out independent subtasks to subagents in parallel — watch and cancel the run tree via /subagents
Share any chat as a live read-only web page with /weburl — no login for the reader
Multi-agent Group chat Subagents Job monitoring

Which one is you?

The same squad covers all five. One container, your hardware, your keys — and whatever you're ambitious enough to point it at.