bootstrapped in 6 hours at the Personal Agents Hackathon because I wasn't happy with all the other options, this is my version of the personal assistant
- as simple, elegant, portable, and modifiable as possible
- more capable than any other assistant on the market (Dots, Grok Bot, Hermes, OpenClaw)
- made of pluggable parts, modules that can be interchanged and swapped
- swappable harness, hex wraps claude code currently, but hex will be portable and able to set itself up on any harness and system with ease
collectively, we still have a lot of work to do before we figure out the "right" way to build these products. there are many opportunities to reduce friction and make the experience more seamless for end users.
the most difficult part of building a proper personal assistant appears to be security, and user trust/sentiment. this is tricky, because you never solve it once. every update or improvement made needs to take security and trust implications into account.
following security and trust, this is my read on the what the remaining challenges are:
- memory and context management
- instruction/skill management (huge potential for tech debt, and over-constraint; needs constant tuning)
- harness state and persistent durable architecture
- portability and modifiability that doesn't threaten the core
hex will serve as my sandbox for ongoing experimentation and testing, but i've tried to package it as an easy install for anyone familiar with claude code
please join me in my quest to build the most minimal, capable, safe, and hackable personal assistant :)
-- bassim
hex runs wherever Claude Code does, on a machine that stays on (a home server, a Mac that doesn't sleep, a cloud VM), with your own Claude subscription; you pick the model for each role. It's a handful of plain files around Claude Code, plus one SQLite file for its messages and tasks: no framework, no service manager required. One small hub process holds the app connections and starts a Claude Code session for each conversation.
How it works
your apps your machine
┌──────────────┐ ┌─────────────────────────────────────────────┐
│ Telegram │ │ │
│ ├ General │◀─────────────▶│ hub (one connection per app) │
│ └ trip │ │ │ │
└──────────────┘ │ ├──▶ claude "hex" General │
┌──────────────┐ │ ├──▶ claude (bg) trip │
│ Discord │ │ ├──▶ claude (bg) #dev › ci │
│ └ #dev │◀─────────────▶│ ├──▶ claude (bg) #ops › backups │
│ └ ci │ │ ├──▶ claude (bg) ~/code/app │
└──────────────┘ │ └──▶ claude (bg) voice │
┌──────────────┐ │ │
│ Buzz │ │ │
│ └ #ops │◀─────────────▶│ SOUL.md AGENTS.md memory/ state/ │
│ └ backups │ │ │
└──────────────┘ │ │
┌──────────────┐ │ │
│ T3 Code │ │ │
│ └ ~/code/app│◀─────────────▶│ │
└──────────────┘ │ │
┌──────────────┐ │ │
│ Voice, phone │◀─────────────▶│ │
└──────────────┘ └─────────────────────────────────────────────┘
- Every topic is its own Claude Code session. General is the main assistant. When it starts work you'll want to follow, it opens a new topic with a fresh session working there, and closes the topic when the work is done. A session that sits idle for about an hour, the life of its prompt cache, stops, and starts again with its conversation when you write; a big one is taken over by a new session that reads back only what your message needs, instead of paying to cache the whole conversation again.
- A DM is one chat that never ends. Your DMs to hex work like Taelin's OptChat: every message is logged word for word in
chat/, Haiku compresses the log into a tree of one-line summaries in the background, and each message starts a fresh session that sees those summaries instead of a history, opening any line back up to the words it came from. Nothing is compacted and nothing is lost. A message sent while hex is still working reaches that same session.
- Your hex is your own folder.
~/hex holds everything that's yours: SOUL.md (who it is), your own rules in AGENTS.md, what it brings up on its own in PROACTIVE.md, schedules.json, its memory, and every message it heard and sent in state/hex.db (hex log prints them as markdown). It's a private git repo, and hex commits its own edits. hex itself lives in ~/hex/.hex, a clone of this repo. Updates pull there, and bin/migrate adds new default files to your folder and updates the ones you never edited.
- One memory, with a timeline. After every turn, a memory agent records what you said and what happened in OptMem: plain text files, read back at the start of each session, with older memories summarized and still searchable word for word. It also keeps a short profile of who you are, which each session reads first; what you want done is in tasks. Your rules live in
AGENTS.md; everything else hex knows is in OptMem.
- It keeps track. Each thing you ask becomes a task with your words, what done means, the agents on it and proof when it closes. Questions it asks you wait for your answer, and you're reminded of the ones you missed. An idea you park gets researched on a schedule and only comes back with news. Holds pause threads until a time.
- Briefs checked against your words. Before a subagent, job or message to another session starts, its brief is checked against what you asked, your rules and memory, and one that drifts goes back.
Works with your client
Pick a client that's ready, or tell your agent to build yours. Use one for everything, or one for work and another for the rest. One hub serves them all, and each is its own way of working, not a copy of the others.
Telegram: topics and voice notes. Built and running today.
- A group with Topics turned on. General is the main assistant, and every topic is its own session.
- Short, phone-sized answers.
- It comes to you: the hourly heartbeat, and reminders about anything waiting on you.
Discord: tag it and it gets to work. Built and running today.
- Tag the bot in any channel and it starts a thread on your message, with a fresh session working inside it. Inside a thread you just talk.
- Channels group work by area, like
#research or #dev. Room for longer answers, code blocks and history.
Buzz: watch it work. Built and running today.
- Buzz is a workspace where people and agents share channels. Tag hex in a channel and it starts a thread with its own session, or DM it.
- Buzz Desktop shows what hex is doing as it works, step by step.
- Its memory shows up in Buzz. Browsing and editing its files there is coming soon.
T3 Code: hex in any project. Built and running today.
- T3 Code runs coding agents, and hex is one of them: pick hex in any project and that thread is a hex session working in that project's folder, with its memory, rules and tools, T3's own included.
- T3 shows its work as it happens: every command, edit and answer, with T3's own diffs and checkpoints.
- hex reaches T3 over ACP:
hex acp connects T3 to the hex that's already running.
iikb: hex in your keyboard. Built and running today.
- iikb is an iOS keyboard. Its Chats open your Telegram threads with hex in any app: read them and dictate or type back without leaving what you're in.
- Your words reach the thread's own session, the same as typing them in its app (channels/iikb).
Voice: call it. Built and running today.
- Call from the browser or the hex voice iPhone app, which also has a Tasks board of what waits on you in each project, chats with every thread and answers to questions in place. Phone calls work both ways through Twilio.
- Calls reach hex's voice session, and work started on a call keeps going after you hang up.
Your own: tell your agent. hex's Buzz client was built this way. Swap in any app:
Build me a Slack channel on your hub, modeled on your Discord one, so every Slack thread is its own session.
Each thread lives in one app. Say "take this to Discord" or "take this to Buzz" and the same session moves over with its memory. The old thread posts a link to the new one and closes.
Install
You need a machine that stays on and runs Claude Code, and a Claude subscription. Paste this into Claude Code on that machine:
Set up hex for me: https://github.com/AVGVSTVS96/hex. Follow INSTALL.md in that repo.
Your agent does the setup. You only do the parts nobody else can: create a bot with @BotFather, make a Telegram group with Topics turned on, and say hi. The full steps are in INSTALL.md. Anytime after, ~/hex/.hex/bin/hex doctor checks the setup and says how to fix what's off.
What's inside
~/hex/ yours: a private git repo
├── AGENTS.md your rules; imports SOUL.md and .hex/HEX.md
├── SOUL.md who it is
├── PROACTIVE.md what it brings up on its own, and when
├── schedules.json recurring jobs, the hourly check included
├── memory/ its OptMem memory
├── chat/ each DM's chat that never ends: its log, summary tree and view
├── .env state/ bot tokens, thread lists, hex.db with every message and task (never committed)
├── scratch/ throwaway work (never committed)
└── .hex/ hex itself: this repo
├── HEX.md how it works
├── bin/
│ ├── hex init, start, stop, restart, status, doctor; run keeps the hub up; acp connects T3 Code; deliver wakes a thread; task, hold and log
│ ├── session how the hub starts each session
│ ├── chat logs a DM, compresses it, and builds what its next session sees
│ ├── wake loads your profile and its memory as each session starts and after a compaction
│ ├── live-status shows its branches, upcoming jobs, sessions and each active thread's last message as each session starts
│ ├── compacted puts the last turns back after a compaction, or a handoff
│ ├── send-gate holds sends and deletes until you say yes (HEX_SEND_MACHINES addresses go free)
│ ├── transcribe voice notes → text
│ ├── vault asks you for secrets by link, signs in with them
│ ├── job long work as its own unit, waking its thread when it ends
│ ├── place, room runs an agent job on whichever of your machines has room
│ ├── worktree-trash clears away worktrees whose work is merged
│ ├── t3-relink renews a T3 Code link to another machine
│ ├── pkill-guard stops a `pkill -f` that would kill its own shell
│ ├── hands-off keeps edits out of memory/ and .hex/, and memo out of subagents
│ └── update pulls updates, tests them, ships when no session is busy
├── chat/prompt.md Taelin's OptChat prompt, for DM sessions and their compactions
├── plugin/ the hooks every session loads, and skills it reads when needed
├── computer/setup turns a Sprite into its computer
├── defaults/ what `hex init` starts your folder with
├── hub/ gives every thread its own session, keeps every message, runs schedules.json
├── systemd/ units for running hex under systemd
└── channels/ the Telegram, Discord, Buzz, T3 Code, voice and iikb channels
hex doesn't need systemd or any service manager. hex start runs the hub in the background, and the hub keeps General running. To have it come back after a reboot, point whatever your machine uses at hex run: the systemd units in systemd/, which also keep sessions in a memory slice apart from the hub, a launchd agent, a Sprite service, or an @reboot cron line.
channels/ is hex's own plugin marketplace: one bot connection per app, serving every Telegram topic, Discord thread and Buzz thread, plus T3 Code and voice calls, all through the hub in hub/, which gives each thread its own session. Telegram and Discord began as Anthropic's official plugins and were kept in step by an auto-maintained fork, which still has their history; they live here now, and upstream fixes come in by hand. Every morning bin/update pulls hex and runs bin/check before your hub restarts on it, and a hub that then can't start goes back to the commit it last ran on.
Fork it
hex is a testbed. Let's make it better together: fork it, do what you want with it, and send back what works.
pull what's new every morning's update
this repo ─────────────────▶ your fork ───────────────────────▶ your hex
▲ │ ▲
└────── pull request ──────┘ └── your changes
- Install your fork. Paste the prompt from Install with your fork's URL. Your hex is a clone of the repo it was installed from, so its updates come from your fork.
- Change anything, by hand or with any coding agent (
AGENTS.md shows it around). Push to your fork, and your hex picks it up on its next update.
- Pull in what's new here whenever you want: Sync fork on your fork's GitHub page, or
git pull https://github.com/AVGVSTVS96/hex main and push.
- Send back what works. Open a pull request that says what it does and the decisions it makes, with screenshots if it shows anything.
What's next
- A ready-made iMessage client.
- Every thread from every app: hex voice already opens every thread and iikb your Telegram ones; more clients to come.
- More modular, more portable.
Known issues
- A project's own instructions don't load on their own. Every hex session starts in
~/hex, because that's what makes it hex: AGENTS.md, SOUL.md and the hooks all load from there. Claude Code only picks up a CLAUDE.md or AGENTS.md on its own inside the folder a session starts in, so when hex works in a repo somewhere else, like ~/Projects/foo, that repo's rules go unread unless hex opens them itself. A fix is planned soon. Until then, ask hex to read the repo's AGENTS.md or CLAUDE.md before it starts.
Principles
- Don't interrupt. Scheduled jobs wait their turn. The heartbeat only messages you when something needs you. Idle sessions stop and come back when you write.
- Plain files over infrastructure. Everything hex knows lives in markdown you can open, edit and grep, and every message in one SQLite file that
hex log prints as markdown.
- Your machine, your account. hex runs on your machine with your Claude subscription. Its memory and messages are files in your folder, and only you can talk to it.
- Yours to change. About 16,000 lines, in plain files. Ask hex to change itself, add any skill, MCP server or plugin Claude Code can load, have your agent build your own client, or fork the whole thing.
License
MIT
