UniDeX Agent Harness

zzoretich4stars

1# UniDeX Agent Harness

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: MIT
Last checked: 2026-10-28

Stars: 4
Tools: —
Uptime: —

Overview

About UniDeX Agent Harness

UniDeX, the Unified Agentic Development Harness: Claude Code, Codex and local models building software together, run by a Chief of Staff that learns how you work. Persistent memory in a plain-Markdown vault, proposals you approve before anything changes, and a macOS app over all of it.

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install UniDeX Agent Harness?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does UniDeX Agent Harness need an API key?

No required environment variable is listed on this record.

What transport does UniDeX Agent Harness use?

UniDeX Agent Harness runs locally over stdio.

When was UniDeX Agent Harness last checked?

Last checked 2026-10-28. UniDeX, the Unified Agentic Development Harness: Claude Code, Codex and local models building software together, run by a Chief of Staff that learns how you work. Persistent memory in a plain-Markdown vault, proposals you approve before anything changes, and a macOS app over all of it.

From the publisher

Documentation

UniDeX is an agent-driven development harness: Claude Code, Codex and local models work on your projects together throughout the development lifecycle. One model plans and the other reviews the plan, one builds and the other inspects the diff, and a model on your Mac handles the routine background work (session summaries, memory, insights) at no cost. You work through your Chief of Staff, a named agent you interview once that answers in every Claude Code or Codex session, briefs you on where your work stands, and improves itself as it goes: repeated corrections become rules, changes to its own duties arrive as proposals you approve, and it earns autonomy one kind of change at a time. Run it with Claude Code, Codex or both: they share one memory, so every session starts with what the last ones learned, and your data goes nowhere but your Mac and your own Claude Code or Codex login.

What you get

Screenshots

The full gallery, with Files, To-Do, Notifications, Routines and the rest of Brain, is in docs/screenshots.md. The pictures come from a made-up demo vault.

Quick start

Download UniDeX from the latest release (AgenticOS-Workbench-<version>-arm64.dmg), open it and drag the app to Applications.
Open the app. Its setup wizard installs what UniDeX needs (Node, uv, Ollama and its model; Claude Code and Codex if you want them) with nothing on the Mac beforehand: no Homebrew, no terminal. It asks which hosts and which vault folder, asks your Chief of Staff's questions, installs, offers to bring in your Claude Code and Codex history, and opens on a guided tour.
Start a claude or codex session: the first prompt already carries your memory and your Chief of Staff. In Codex, run /hooks once first and trust the agenticos entries, as the wizard's last step reminds you. Installed without a host? Add one later under Settings ▸ Hosts, or with aos hosts add claude (or codex).

Prerequisites

The app's wizard installs all of these itself; each download is pinned, checksummed and checked against its maker's code signature. From a terminal, you bring them.


macOS 13 or later, Apple silicon	required	The app is built for it, and schedules run through launchd. Linux is untested and unsupported; Windows is not supported.
Node.js 20 or newer	required	The runtime runs on Node.
uv	required	Installs the pinned graphify with a Python of its own.
Ollama	recommended	Runs background work on this Mac: `qwen3.5:4b` under 12 GB of memory, else `qwen3.5:9b`. Without it that work waits or uses heuristics.
Claude Code and/or Codex, signed in	optional	The hosts your sessions run in. With neither, everything else is set up and you add one later.
python3 3.9 or newer	cost module only	Only `aos cost enable` runs it.

Installation

With the app. The app is signed and notarized and carries the runtime inside it. Its wizard runs in six steps (Check, Choose, Your agent, Install, Your history, Finish) and nothing is written until you choose Install. Afterwards it keeps itself current from GitHub Releases and offers to update the runtime in your vault when it carries a newer one.

From a terminal. The same install from a clone of this repository, which is also how CI tests it:

git clone https://github.com/zzoretich/UniDeX-Agent-Harness.git
cd UniDeX-Agent-Harness
npm ci --ignore-scripts
npm run setup                          # the interactive installer (= node cli/aos.js init)
export PATH="$HOME/.local/bin:$PATH"   # add the same line to ~/.zprofile
aos doctor                             # exits 0 when every check passes
aos local pull                         # with Ollama: download this Mac's model and the embedder

Then wire your host: for Claude Code, add the one line the installer prints (@/path/to/your/vault/AGENTICOS.md) to ~/.claude/CLAUDE.md; for Codex there is nothing to paste, so open codex, run /hooks and trust the agenticos entries once. Then open the app.

Every wizard step, every installer step and flag, hosts, providers and spend caps are in docs/install.md. Updating from 1.x? docs/migrating-to-2.0.md says what the update asks and how to undo it.

Uninstall

aos uninstall --keep-vault     # remove both plugins (or the direct Codex wiring), schedules, symlink, the graphify tool dir and agenticos.json; keep the vault
aos uninstall                  # additionally delete the vault, after you type its path back
aos uninstall --host codex     # unwire only the Codex host; keep everything else

To remove the app too, quit it and drag UniDeX from Applications to the Trash; its own settings are in ~/Library/Application Support/AgenticOS Workbench. ~/.claude and ~/.codex are left as they were, and no form of aos uninstall edits your CLAUDE.md: remove the @<vault>/AGENTICOS.md line yourself.

Your first session

Run claude or codex in any folder and ask what do you know about me? The first prompt arrives with your memory (<brain-context>) and your agent (<persona>). When you are done, /wrap saves what the session learned into the vault. In a later session, use the agenticos recall tool to search for … answers from your own notes.

Then say sitrep for a one-action briefing on where your work stands, and review persona flags to walk through anything your Chief of Staff has flagged or proposed.

Everyday commands

The ones you will use most. Every command, with every flag, is in docs/commands.md.

Inside a session (Claude Code: /name · Codex: $agenticos:name)

Command	Does
`/remember <text>`	Note something in this session's working memory; tag it `#promote` to keep it at `/wrap`.
`/wrap`	End the session: keep what it learned as memories and summarise it into today's daily note.
`/todo <text>`	Add a to-do, with "by Friday" as its due date and "urgent" as its priority.
`/propose <idea>`	File a proposal for your Chief of Staff's review, with its own page.
`/cross-review` · `/handoff`	Have the other provider review your plan or diff; send a scoped task to the model that suits it.
`/team`	Your agent teams: boards, gates waiting on you, live runs.
sitrep · review persona flags	Where your work stands; decide what your Chief of Staff has pending.

On the command line

Command	Does
`aos doctor`	Check the whole install, host by host. Exits 1 on any failure.
`aos status`	The provider in use, today's spend against the caps, and what ran.
`aos upgrade`	Update both plugins and the runtime in your vault. Never touches memory, notes or persona.
`aos config` · `aos config set <key> <value>`	Every setting and the file it comes from; change one safely.
`aos hosts add claude\|codex`	Wire one more host into this install.
`aos import`	Bring your Claude Code and Codex history into the vault, on the local model.
`aos routines list\|run <slug>`	Your recurring routines: when they run next, and run one now.
`aos statusline install`	An opt-in status line: three lines in Claude Code, a footer in Codex.

Staying up to date. The app updates itself and installs the new version when you quit, or at once from Restart to Update, then offers to update the runtime in your vault (aos upgrade does the same from a terminal). What each version changed is in CHANGELOG.md and on its release page.

The agent you work through: a named agent with one job description, a memory of its own decisions, and a contract about what it may change without asking. You interview it once during the install (its name, how it addresses you, its voice, what to watch, its model and schedule). After that it rides along on every prompt on either host and works on a schedule whether or not you are at the keyboard. Its identity, state and proposals are generated in your vault and never ship in this repository.

What it does on its own

Duty	When	What it does
tick	hourly	Notices what changed (failed routines, new commits, your corrections, open flags); with nothing new, it stops without a model call.
reflect-daily	22:00	Turns the day's signals into at most two proposals.
monitor	13:00	Duty health, vault drift and unfinished work; prepares one safe fix.
sitrep	weekdays 07:45	One page on where your work stands, leading with exactly one recommended action.
reflect	Sundays	Curates its playbook and promotes repeated corrections to feedback rules.
heartbeat	every 30 min	Flags a duty that missed its window. Never calls a model.

Duties run headless on its model for each host (claude-opus-5-5, or gpt-6-sol on Codex), each under its own cap and a daily cap across both hosts, and a duty never runs git commit.

How it improves itself

flowchart LR
  T["tick · hourly<br/>notices what changed"] --> Q[("queue.jsonl")]
  Q --> R["reflect · nightly<br/>files at most 2 proposals"]
  R --> P[("proposals/")]
  P --> Y["you · review persona flags<br/>approve · reject · accept · dismiss"]
  Y --> L[("ledger.jsonl")]
  L --> W["heartbeat · daily<br/>verified, or regressed"]
  W -. "a regression is a new signal" .-> T

Its identity, its duties and anything outside its own folder are guarded: it changes them only by filing a proposal with a recheck, a command that keeps passing for as long as the finding is still true. Every outcome lands in a ledger, so a rejected idea is never filed twice and a regression counts against the fix that caused it. Once one kind of change has three verified approvals with no regression and no rejection, it may propose applying that kind on its own, a proposal you approve like any other. aos persona off is the kill switch.

Talking to it: sitrep for the morning page, review persona flags to decide everything pending in one pass, and aos persona to re-run the interview, rename <name> it or turn it off and on. The full reference is docs/chief-of-staff.md.

flowchart LR
  CC["Claude Code session"] -- "hooks, via aos" --> RT["vault/brain/scripts"]
  CX["Codex CLI session"] -- "hooks, via aos" --> RT
  RT --> V[("Your vault<br/>memory · daily notes · _index")]
  V -- "agenticos MCP server" --> CC
  V -- "agenticos MCP server" --> CX
  V --> HUD["UniDeX app"]
  RT -. "provider: local" .-> OL["local model (Ollama)"]
  RT -. "provider: auto" .-> HC["headless Claude, capped"]
  RT -. "provider: auto" .-> HX["headless Codex, capped"]

Hosts. Claude Code loads plugin/ and Codex loads codex-plugin/, which is generated from it, so the hooks, the MCP server and the commands match on both. Claude Code only, Codex only, or both on one vault work the same.
Hooks. Session start, every prompt, every tool use, stop and session end each run aos <script> inside your vault: inject context, update working memory, stream telemetry, cost the session and wrap it.
The vault. An ordinary folder of Markdown: the memory both hosts share, daily notes, a workspaces/ folder for your projects, your Chief of Staff's files, and the caches the app reads.
Providers. Under local, a new install's default, background work runs on the local model and spends nothing. Hosted calls (the Chief of Staff's duties, cross-review, and anything you send to a host) go through your own Claude Code or Codex login, each under a daily cap.
The graph. Every scan rebuilds a structural graph of the vault with no model; at most once a day a second pass adds concepts and inferred links, on the local model under local.
The app reads the same files: what ran, live agent runs, the memory graph, provider state, spend, and your agent's identity and flags.

Every hook, runner, provider rule and the graph pipeline in full: docs/how-it-works.md.

Privacy

Your vault stays on your machine. Background calls go to the local model on your Mac or to your own Claude Code or Codex login; the cost analyzer runs with --no-api.
Telemetry redaction is on by default.
The graph's structural pass calls no model. Its daily semantic pass reads new or changed notes on the local model under provider local, or on your own login under its own $1/day cap otherwise; it is off under provider none, and aos graph semantic off turns it off anywhere.
This repository ships machinery, not content: the Chief of Staff's identity, state and playbook are generated for you at install. A privacy gate runs in CI against a public list of generic terms plus the maintainer's private list, and gitleaks checks every pushed commit, so nothing personal can land here.

Repository layout

brain/scripts      the runtime that gets vendored into your vault (hooks, collectors, recall, MCP server, persona)
cli                the installer and the aos subcommands (persona, schedule, routines, cost, the Codex host) + two install rehearsals
plugin             the Claude Code plugin: hooks.json, .mcp.json, bin/aos, 21 commands, 9 skills (also the source of codex-plugin)
codex-plugin       the Codex plugin, generated from plugin/ by npm run build:codex-plugin: hooks.json, .mcp.json, bin/aos, 28 skills
hud                the UniDeX app's interface (TypeScript), which the app compiles into its window
app                the UniDeX macOS app: that interface in an Electron window (its own lockfile; see app/README.md)
vault-template     the seed vault (AGENTICOS.md, MEMORY.md, brain/ incl. the duty routines, persona templates incl. the heartbeat watchdog, hourly tick and nightly reflect routines)
extras             the launchd schedule template, the cost analyzer, optional Ollama helpers
tools              export-from-vault, the privacy gate, and the brand-asset generator behind docs/assets
docs               install, commands, how it works, screenshots, chief of staff, cost, migrating to 2.0 and to 1.0,
                   the app's smoke checklist, the release acceptance runbook, and design/ — the spec and plan behind each feature

Working on UniDeX itself? CONTRIBUTING.md has the checkout, the checks, and how to open a pull request.


docs/install.md	The setup wizard step by step, the terminal install, every installer step and flag, bringing in your history, hosts, providers and spend caps.
docs/commands.md	Every `aos` command and in-session command, staying up to date, and the status line.
docs/how-it-works.md	Hosts, hooks, runners, the vault, providers and the graph, in full.
docs/chief-of-staff.md	The interview, the persona layout, duties and their schedules, the heartbeat, proposals and their ledger, the kill switch, caps.
docs/screenshots.md	Every screenshot of the app, on a demo vault.
docs/cost.md	The cost module: enabling it, what it records, the budget.
docs/migrating-to-2.0.md	What an install from 1.x sees after updating to 2.0, and how to undo it.
docs/migrating-to-1.0.md	Moving an install from before 1.0 onto the app.
docs/app-smoke.md · docs/acceptance.md	The app's manual smoke checklist and release procedure; the release acceptance runbook.
app/README.md	Running, testing and building the app from a checkout.
extras/ollama/README.md	Running Ollama as a supervised service (optional), pulling the models by hand.

Credits

Created by Zach Zoretich — @zzoretich.

Built with Claude Code. The brand assets under docs/assets/ are generated, not hand-drawn: node tools/brand-assets.js rebuilds all 24 from one palette in tools/brand-assets.js, and tools/brand-assets.test.js holds them to being inert, on-palette and byte-stable.

cross-review and handoff are adapted from claudex-loop by Chase AI, and the glossary and ADR formats inside cross-review from Matt Pocock's skills, both under the MIT License; each skill's THIRD-PARTY-NOTICES.md carries the notice and what changed.

License

MIT — AgenticOS Workbench contributors. Issues and pull requests are welcome.

macOS 13 or later, Apple silicon

required

The app is built for it, and schedules run through launchd. Linux is untested and unsupported; Windows is not supported.

Node.js 20 or newer

required

The runtime runs on Node.

required

Installs the pinned graphify with a Python of its own.

Ollama

recommended

Runs background work on this Mac: qwen3.5:4b under 12 GB of memory, else qwen3.5:9b. Without it that work waits or uses heuristics.

Claude Code and/or Codex, signed in

optional

The hosts your sessions run in. With neither, everything else is set up and you add one later.

python3 3.9 or newer

cost module only

Only aos cost enable runs it.

git clone https://github.com/zzoretich/UniDeX-Agent-Harness.git cd UniDeX-Agent-Harness npm ci --ignore-scripts npm run setup # the interactive installer (= node cli/aos.js init) export PATH="$HOME/.local/bin:$PATH" # add the same line to ~/.zprofile aos doctor # exits 0 when every check passes aos local pull # with Ollama: download this Mac's model and the embedder

aos uninstall --keep-vault # remove both plugins (or the direct Codex wiring), schedules, symlink, the graphify tool dir and agenticos.json; keep the vault aos uninstall # additionally delete the vault, after you type its path back aos uninstall --host codex # unwire only the Codex host; keep everything else

Command

Does

/remember <text>

Note something in this session's working memory; tag it #promote to keep it at /wrap.

/wrap

End the session: keep what it learned as memories and summarise it into today's daily note.

/todo <text>

Add a to-do, with "by Friday" as its due date and "urgent" as its priority.

/propose <idea>

File a proposal for your Chief of Staff's review, with its own page.

/cross-review · /handoff

Have the other provider review your plan or diff; send a scoped task to the model that suits it.

/team

Your agent teams: boards, gates waiting on you, live runs.

sitrep · review persona flags

Where your work stands; decide what your Chief of Staff has pending.

Command

Does

aos doctor

Check the whole install, host by host. Exits 1 on any failure.

aos status

The provider in use, today's spend against the caps, and what ran.

aos upgrade

Update both plugins and the runtime in your vault. Never touches memory, notes or persona.

aos config · aos config set <key> <value>

Every setting and the file it comes from; change one safely.

aos hosts add claude|codex

Wire one more host into this install.

aos import

Bring your Claude Code and Codex history into the vault, on the local model.

aos routines list|run <slug>

Your recurring routines: when they run next, and run one now.

aos statusline install

An opt-in status line: three lines in Claude Code, a footer in Codex.

Duty

When

What it does

tick

hourly

Notices what changed (failed routines, new commits, your corrections, open flags); with nothing new, it stops without a model call.

reflect-daily

22:00

Turns the day's signals into at most two proposals.

monitor

13:00

Duty health, vault drift and unfinished work; prepares one safe fix.

sitrep

weekdays 07:45

One page on where your work stands, leading with exactly one recommended action.

reflect

Sundays

Curates its playbook and promotes repeated corrections to feedback rules.

heartbeat

every 30 min

Flags a duty that missed its window. Never calls a model.

flowchart LR T["tick · hourly notices what changed"] --> Q[("queue.jsonl")] Q --> R["reflect · nightly files at most 2 proposals"] R --> P[("proposals/")] P --> Y["you · review persona flags approve · reject · accept · dismiss"] Y --> L[("ledger.jsonl")] L --> W["heartbeat · daily verified, or regressed"] W -. "a regression is a new signal" .-> T

flowchart LR CC["Claude Code session"] -- "hooks, via aos" --> RT["vault/brain/scripts"] CX["Codex CLI session"] -- "hooks, via aos" --> RT RT --> V[("Your vault memory · daily notes · _index")] V -- "agenticos MCP server" --> CC V -- "agenticos MCP server" --> CX V --> HUD["UniDeX app"] RT -. "provider: local" .-> OL["local model (Ollama)"] RT -. "provider: auto" .-> HC["headless Claude, capped"] RT -. "provider: auto" .-> HX["headless Codex, capped"]

brain/scripts the runtime that gets vendored into your vault (hooks, collectors, recall, MCP server, persona) cli the installer and the aos subcommands (persona, schedule, routines, cost, the Codex host) + two install rehearsals plugin the Claude Code plugin: hooks.json, .mcp.json, bin/aos, 21 commands, 9 skills (also the source of codex-plugin) codex-plugin the Codex plugin, generated from plugin/ by npm run build:codex-plugin: hooks.json, .mcp.json, bin/aos, 28 skills hud the UniDeX app's interface (TypeScript), which the app compiles into its window app the UniDeX macOS app: that interface in an Electron window (its own lockfile; see app/README.md) vault-template the seed vault (AGENTICOS.md, MEMORY.md, brain/ incl. the duty routines, persona templates incl. the heartbeat watchdog, hourly tick and nightly reflect routines) extras the launchd schedule template, the cost analyzer, optional Ollama helpers tools export-from-vault, the privacy gate, and the brand-asset generator behind docs/assets docs install, commands, how it works, screenshots, chief of staff, cost, migrating to 2.0 and to 1.0, the app's smoke checklist, the release acceptance runbook, and design/ — the spec and plan behind each feature

docs/install.md

The setup wizard step by step, the terminal install, every installer step and flag, bringing in your history, hosts, providers and spend caps.

docs/commands.md

Every aos command and in-session command, staying up to date, and the status line.

docs/how-it-works.md

Hosts, hooks, runners, the vault, providers and the graph, in full.

docs/chief-of-staff.md

The interview, the persona layout, duties and their schedules, the heartbeat, proposals and their ledger, the kill switch, caps.

docs/screenshots.md

Every screenshot of the app, on a demo vault.

docs/cost.md

The cost module: enabling it, what it records, the budget.