Dex: a Markdown vault plus MCP tools for people who want an AI chief of staff
Your AI Chief of Staff — a personal operating system starter kit that adapts to your role. No coding required.
At a glance
- What is it?
- Dex is a Python-based starter kit that installs a folder of Markdown notes and a set of MCP tools, then adapts them to your role through an AI harness. The catch is that the harness you pick decides how much of Dex you actually get.
- Who is it for?
- Adopt Dex if you already pay for Claude Pro or Cursor and want your notes, tasks and meeting records to live as plain Markdown files rather than inside a closed SaaS database.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Dex targets: work scattered across tools that do not talk to each other
Most knowledge workers keep their commitments in one application, their meeting notes in another, and their sense of who owes whom what in their head. Dex is an attempt to collapse that into a single folder of Markdown files plus a set of tools an AI assistant can call. The README describes it as "a personal operating system for your work" covering strategic work management, meeting intelligence, relationship tracking and daily planning, configured for a specific role rather than shipped as a blank template.
The intended user is explicit in the badges and the setup table: someone who is not an engineer. The README carries a "coding required: none" badge and points new readers at a plain-English guide with copy-paste prompts. The install instructions assume you can open Terminal on a Mac or PowerShell on Windows and paste one line, which is a lower bar than cloning a repository and editing a config file, but it is still a terminal.
What makes the targeting credible rather than decorative is the tier table. Dex does not pretend every AI assistant is equivalent. It names which harness gives you which capability, and it treats that as a documented contract. That is a more honest framing than the usual "works with any AI" claim, and it is the single most useful thing in the README.
The four-tier contract: vault, tools, skills, and hooks
Dex is layered, and the layers are cumulative. Tier 0 is the vault: Markdown folders named inbox, projects, people and tasks. At this level Dex is just files, readable in any editor, with no AI involved at all. That is a deliberate floor, and it means the data outlives whatever assistant you happen to be paying for this year.
Tier 1 adds tools and background jobs: tasks, a people index, meeting sync, search, and what the README calls portable context and gate payloads. Any assistant that can run Dex's MCP tools reaches this tier. Tier 2 adds named journeys such as /daily-plan and /process-meetings, generated into a .agents/ directory, for any assistant that reads Agent Skills. Tier 3 is where the automatic behaviour lives: person context when you open a file, safety gates, session learning, and a mid-session health pulse.
Only Claude Code reaches Tier 3 today. The README calls it "the reference implementation" and says Claude Code remains the full-experience reference. Cursor, Codex and Gemini CLI are Tier 2. That is not a marketing distinction. The README states plainly that check_safety_gate is an advisory MCP check and that only a verified pre-tool interceptor can enforce a refusal. In other words, on Tier 2 the safety gate is a suggestion the model can decline to follow, because there is no hook in the harness to intercept the tool call before it runs. The architecture documents for this split are docs/architecture/HARNESS-CAPABILITY.md and docs/architecture/HOOK-INVENTORY.md.
What the installer actually does, and what you have to type
The recommended path is a single pasted line. On Mac, the README gives:
curl -fsSL https://heydex.ai/install.sh | bash
On Windows, in PowerShell:
irm https://heydex.ai/install.ps1 | iex
The README says the script checks your computer, installs anything missing after asking first, downloads Dex to Documents/Dex, and is safe to run more than once. It also says nothing is changed half-way if something fails, and suggests pasting the error message to an AI assistant for diagnosis. The stated total time is about ten minutes, followed by telling Dex your role.
There is a third path for people who already have an assistant that can execute commands locally: tell it to follow https://heydex.ai/install.md. That is an unusual distribution choice and worth noting, because it means the install instructions are themselves designed to be consumed by a model rather than read by a human.
After installation you open the Dex folder in Cursor or Claude Code, say "hi", and the README says Dex introduces itself and sets itself up around your role. The README also warns that you do not go to claude.ai and type commands there. You need one of the listed applications. Cursor is presented as the easiest starting point because its free tier works, while Claude Code Desktop or Terminal requires Claude Pro at $20 per month.
The portability work is unreleased, and the README says so
A section of the README describes a portability preview on the branch: one portable plugin package intended for Codex CLI and desktop, ChatGPT desktop, Claude Code and Cowork, Copilot CLI, and compatible Agent Plugin clients, plus a separately built native plugin and a native extension for another host. The package shares Dex's read-only session context, person context and safety decision code.
The important part is the disclaimer that follows. The README states the package has not been merged, published, submitted to a marketplace, or released. It also names two concrete blockers: Codex IDE extensions do not currently load plugins, and ChatGPT web or Cowork connectors need a separately secured public endpoint before they can reach a local vault. That second point is architectural rather than a matter of unfinished work. A local vault sitting on your laptop is not reachable from a hosted connector without exposing something to the internet, and the README does not claim a solution exists.
If you are evaluating Dex on the strength of the topics list, which includes cursor and mcp, you should read this section before assuming broad harness support. The reference implementation is Claude Code. Everything else is either Tier 2 today or unreleased.
Where Dex is the wrong tool
The licence is the first constraint. The badge and the repository metadata point to PolyForm Noncommercial, and the repository's own licence field is recorded as NOASSERTION, which means automated tooling cannot classify it. PolyForm Noncommercial is a source-available licence, not an OSI-approved open source licence. If you work at a company that generates revenue, the noncommercial restriction is a question for your legal team, not something to settle by reading a badge. Nothing here is legal advice, and the README does not spell out the commercial terms.
The second constraint is the harness dependency. Dex is not a standalone application. It is a vault plus tools that require an external assistant, and the amount of automation you get is determined by that assistant's extension points. If your organisation standardises on a harness without hooks, you are permanently on Tier 2 and the safety gate stays advisory. The README is direct about this rather than glossing it.
The third is the release cadence. The recent release list shows v1.97.13, v1.97.14 and v1.97.15 within four days, and the README links to a post describing 52 releases in two weeks. Rapid version churn in a tool that writes into your personal notes folder means you should expect to re-read release notes. The installer's idempotence helps here, but it does not tell you what changed between v1.97.14 and v1.97.15.
Finally, the desktop and mobile apps do not exist yet. The README says they are "on the way" and points to an early access signup. Anyone who wants to avoid the terminal entirely is waiting on unreleased software.
How Dex differs from Obsidian, Notion and a plain Claude project
The nearest comparison is a note-taking application with a plugin ecosystem, Obsidian being the obvious one. Both put Markdown files on your disk, and both let you extend behaviour. The difference is where the intelligence sits. In Obsidian, plugins are code you install and the AI is an add-on. In Dex, the AI assistant is the interface and the vault is the substrate it reads and writes. Dex's tier table only makes sense if you accept that premise, because the tiers are defined by what the harness can do, not by what the vault contains.
Against Notion or a similar hosted workspace, the split is storage. Dex keeps everything as local Markdown, so the data is portable and inspectable without an export step. The trade-off is that you get no collaborative editing, no shared database, and no web interface. Dex is single-player by construction.
Against simply opening Claude Code in a folder of notes and writing your own prompts, the difference is that Dex ships the prompts as named skills and ships the tools as MCP endpoints. The README's example of saying "plan my day" and having it scan calendar, Slack, Salesforce, Granola and goals is a packaged journey, not something you assemble yourself. Whether that packaging is worth the dependency is the real question, and the answer depends on whether you would otherwise maintain your own prompt library.
Maintenance cost and what to verify before adopting
The upgrade path is the installer. Because the README states the script is safe to run more than once, re-running the curl or irm line is the documented way to stay current, and the release cadence suggests you will do it often. What the README does not describe is a migration story for the vault itself when the folder schema changes. If Dex renames or restructures inbox, projects, people or tasks, your existing files are the thing at risk, and the installer's idempotence does not address that.
The dependency surface is also worth counting before you start. Dex assumes a harness (Cursor or Claude Code), an MCP-capable runtime, and integrations with whatever calendar, messaging and CRM systems you want the journeys to reach. Each of those is a separate thing that can break, and the README's troubleshooting advice is to paste the error to an AI assistant rather than to consult a compatibility matrix.
Concretely, verify three things first. Read docs/architecture/HARNESS-CAPABILITY.md and docs/architecture/HOOK-INVENTORY.md to confirm what your chosen harness implements, because the tier you land on determines whether check_safety_gate can actually refuse anything. Check the LICENSE file for the exact PolyForm Noncommercial terms rather than relying on the badge. And run the installer once on a machine where you can afford to lose Documents/Dex, so you learn what it touches before it touches a folder you care about.
Editorial conclusion
Adopt Dex if you already pay for Claude Pro or Cursor and want your notes, tasks and meeting records to live as plain Markdown files rather than inside a closed SaaS database. Do not adopt it if you need to run it at a company that sells anything, because the PolyForm Noncommercial licence is not a permissive open source licence, and do not adopt it if you will not accept that Cursor, Codex and Gemini CLI are Tier 2 and will never get the pre-tool interceptor that makes safety gates enforceable. Before you commit, read docs/architecture/HARNESS-CAPABILITY.md and confirm which tier your harness actually implements, then check that the installer's ~10 minute estimate holds on your machine.
Community notes