Agnostic AI

One harness. Every client. One repository.

Agnostic AI is the operating system for an AI coding harness: the guard hooks that block secrets and destructive commands, the working agreement (rules), the on-demand context modules, subagents, saved workflows, Mods (function-hook plugins), operator tools, scheduled jobs and the learning loop that turns incidents into rules. It is installed into the client you use (Claude Code) as links, and ported from there into every other client on the machine (Codex, Gemini CLI, Cursor and sixteen more) in each one's dialect. Your identity, private rules, memory and machine config stay in a small private overlay of your own.

It is not a starter kit designed in an afternoon. It grew rule by rule out of daily use, and most of it exists because something broke first: every guard has an incident behind it, every doc has a word ceiling, every check reports the count it processed, and a check that was never seen failing does not count as verified.

This repository is also published as ucsandman/claude-harness, the name it was first shared under. Both receive every push; they are the same commits.

Contents

• Install
• What is inside
• How it fits together
• Guards
• Rules and context modules
• Mods
• Subagents and workflows
• Tools
• Scheduled jobs and the learning loop
• Porting to twenty clients
• Health checks
• What is shared, what stays private
• Commands
• Documentation
• Repository layout
• Development
• Security
• Related
• License

Install

git clone https://github.com/ucsandman/Agnostic-AI.git && cd Agnostic-AI
npm run setup      # wire the core guards, link the surfaces, assemble CLAUDE.md, port, doctor

Node 18+ and git, nothing else. setup compiles core/rules into ~/.claude/agnostic-rules.md, generates a CLAUDE.md that imports it, wires the core guards into settings.json, links ~/.claude/{hooks,tools,mods,agents,workflows} into this checkout (a real directory there is moved aside, never deleted), ports the harness to every other installed client and runs the doctor (CLAUDE_CONFIG_DIR moves the home). The three commands you keep using:

npm run sync       # rules changed, or a link is missing: recompile, relink, reassemble CLAUDE.md
npm run port       # push the harness to every other installed client
npm run doctor     # drift, a second writer, a broken link, an old path, a private path in public code

To use it as a template: click Use this template, clone, npm run setup. core/port.json chooses the source client, restricts targets, or excludes a hook, skill or MCP server with a reason.

What is inside

How it fits together

Dependency direction is one way: core to engine to the installed surfaces to the client homes. The overlay is read through three named files. Every generated file has one writer, and the doctor fails on a second one.

flowchart LR
  core["core/<br/>rules, modules, targets.json,<br/>guards.json, port.json"] --> engine["engine/<br/>sync, setup, doctor, context graph,<br/>hooks, Mods, harness port"]
  overlay["overlay/ (private)<br/>profile.md, context-graph.json, gates.json"] -. read by sync .-> engine
  engine --> home["~/.claude<br/>hooks, tools, mods, agents, workflows as links<br/>agnostic-rules.md, CLAUDE.md generated"]
  home -- capture --> bundle["harness/ bundle<br/>rules, identity, hooks, skills,<br/>agents, commands, mcp, permissions"]
  bundle -- apply --> clients["19 other clients<br/>Codex, Gemini, Cursor, Windsurf, Cline, ..."]
  clients -- one shim --> guards["engine/hooks/<br/>the same guard scripts everywhere"]

1. Capture reads the client you use into a client-neutral bundle: rules with every @import inlined, hooks in one dialect, skills, agents, commands, MCP servers, permissions. A value that looks like a token becomes ${NAME} and you are told what to export.
2. Apply renders the bundle into each other client's dialect. Hooks are not copied: every client is pointed at the same scripts through a shim; skills are linked.
3. Nothing is destroyed. Generated files carry the port's header; user-owned files get a marked region and are otherwise preserved. Every overwrite is backed up. --check exits 1 on drift.
4. Every drop is explained by npm run explain, from core/port.json.

The three places in full, with the storage layout and the adapter contract: docs/architecture.md.

Guards

engine/hooks/ holds 41 hooks: 38 Node, 2 Python, 1 PowerShell. They run on Claude Code's events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, SubagentStart, PreCompact) and, through engine/hooks/shim.cjs, on every other client that has hooks. One file, core/safety/guards.json, is the policy every guard reads: secret paths are always blocked, hard-stop commands need a human, a missing policy fails closed.

Every guard has an override marker for the case it was not written for, and a probe under engine/hooks/tests/ that makes it fail on purpose. The roster with markers: docs/guards.md. Measured cost per event: docs/hook-latency.md.

Rules and context modules

core/rules/global-rules.md is the working agreement every client receives: non-negotiables (secrets, hard stops), how to work, communication, definition of done, memory. npm run sync compiles it (with core/traits/traits.md) into the primary client's rules file; npm run port carries it everywhere.

Situational text is a module, not standing prompt. A module is a markdown file with a context: block (keyword, path and command triggers; requires and suggests edges) that loads when the prompt, the edited file or the command says it applies, in dependency order, under a budget, with the reason attached.

How the graph selects, resolves and packs: docs/context-graph.md. Your own section of CLAUDE.md comes from overlay/profile.md and never enters this repository.

Mods

engine/mods/ holds the function-hook plugins that run inside Claude Code's hooks engine with no process spawn: claude-runtime (the runtime adapter: events, judgments, snapshots) and harness-mods (routing, context nudges, secret redaction, subagent accounting, a read cache). canary.cjs and shadow-report.cjs verify them from a classic hook, and universal-adapter.cjs records which of these capabilities each other client has, so a port drops a Mods-only artefact with a reason instead of pretending. The research record behind them is labs/claude-mods/.

Subagents and workflows

Every spawn names its model and every fan-out declares its ceiling; the guards enforce it. The contract: core/rules/modules/delegation-and-model-routing.md.

Tools

Zero-dependency Node and PowerShell, each in its own directory with a README or a header that says what it does.

Scheduled jobs and the learning loop

jobs/install.cjs --apply points Windows Task Scheduler at this checkout. The jobs are the harness's memory of its own mistakes:

engine/harvest feeds storage/candidates.jsonl; engine/distill promotes on evidence (three signals across two sessions, older signals counting half, a contradiction demoting); tools/dashboard is where a human approves. The same ladder produced most of the rules in core/rules/global-rules.md.

Porting to twenty clients

Codex CLI works as the source too: the same eight components are read back from ~/.codex and written into Claude Code and the rest. The live matrix for your machine is npm run status; the generated per-client table is docs/targets.md: rules written to 20 of 20 clients, hooks driven in 5, skills linked in 15, subagents in 4, commands in 6, MCP in 8.

Supported clients: Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, Cursor, Windsurf, GitHub Copilot, Cline, Aider, OpenHands, Goose, Continue, Zed, OpenCode, Trae, Amazon Q, Sourcegraph Cody, OpenClaw, Hermes, and a generic system prompt for any local or API model. Adding one is one entry in core/templates/targets.json (engine/harness/README.md).

Health checks

npm run doctor answers one question: is the installed harness the one this repository describes? Fourteen checks, each printing the count it processed:

links, hook-wiring, rules-drift, claude-md, old-refs, private-boundary, linked-leftovers, orphan-hooks, unexpected-links, context-graph, data-files, deps, jobs, mirror-current.

The pre-commit hook runs the secrets scan, wiredark, the guard freeze and the doc gates on every commit. tools/prove exists because a check that was never observed failing has been run, not verified.

What is shared, what stays private

This repository holds everything portable: rules and modules, guards, Mods, agents, workflows, tools, jobs, docs. Your overlay (~/.claude/overlay/, in a repository of your own) holds profile.md (the private section of CLAUDE.md), context-graph.json (your context roots) and gates.json (extra frozen files); memory, meditations and settings.json stay in the Claude home. CLAUDE.md has one writer, npm run sync. The doctor fails when a tracked file here carries your account's home path. docs/private-overlay.md.

Commands

Flags: --from claude|codex, --to codex,gemini, --check, --dry-run, --force, --home <dir>, --json. Full list: docs/configuration.md.

Documentation

Repository layout

core/       rules/ (global-rules.md + modules/), templates/targets.json (the client registry), safety/guards.json, traits/, port.json, examples/
engine/     harness/ (capture, apply, status, cli; sources/, targets/)   context/ (the module graph)   sync/   setup/   doctor/
            hooks/ (the guards, lib/, tests/, adapters/, shim.cjs)   mods/ (function-hook plugins)   harvest/  distill/  ingest/  skills/  audit/  docs/  tests/
agents/     subagent definitions        workflows/   saved Workflow scripts        skills/    the consolidated skill library
tools/      operator CLIs and pages      jobs/        scheduled jobs + install.cjs   packages/  markdown-agent-memory
docs/       this documentation           examples/    an installed harness           labs/      research (may depend on engine; never the reverse)
harness/    your captured bundle (gitignored)    storage/  runtime state, backups, reports (gitignored)

Installed surfaces: ~/.claude/{hooks,tools,mods,agents,workflows} are links into engine/hooks, tools, engine/mods, agents, workflows.

Development

npm test               # engine suite + sync, hook, wire-protocol, port, capability and context regressions
npm run docs:check     # generated docs are current

Every test builds a throwaway home directory; nothing in the suite touches yours. CI runs on Ubuntu (Node 18 and 22) and Windows (Node 22). Commits pass the secrets scan, wiredark, the guard freeze and the doc gates locally first. See CONTRIBUTING.md.

Security

No secret is read by the harness: guards deny the paths, envdoctor reports names and presence only, a captured value that looks like a token is replaced by ${NAME}, and the doctor fails on the author's home path or on transcript-derived data in the tree. Report a vulnerability privately as described in SECURITY.md.

Related

• agnostic-agent: the terminal coding agent that used to live in this repo. Local or hosted models, subagents, the same safety policy.
• DashClaw: remote approvals and execution evidence for unattended agents.
• agent-capsule: move a whole Claude Code harness onto a fresh Linux box.
• markdown-agent-memory: the memory policy this harness runs on, as a package.

If this saved you an incident, sponsoring keeps the nightly loop running.

License

MIT. See LICENSE.

Runtime capabilities (supports in core/templates/targets.json)

Claude Code now has capabilities other targets do not (the Function Hooks layer in ~/.claude/mods, 2026-09-16). Every target declares them explicitly; universal-adapter.cjs exposes capabilitiesOf(client) and requires(client, feature) so a porter DROPS a Mods-only artefact with a recorded reason (dropped: target lacks <feature>) instead of forcing every runtime to the lowest common denominator or pretending a target exposes a feature it does not. The Claude row describes the harness with ~/.claude/mods installed. engine/tests/reg-capabilities.cjs fails when this table and targets.json disagree.