AgentSmith — the universal agent harness

Vibe coding gets you a working demo. AI-assisted engineering is what keeps it standing once customers arrive, the product changes, or another engineer has to touch it. Agentsmith is that second layer — a portable, battle-tested operating system for Claude Code (and any agent that reads a CLAUDE.md / AGENTS.md / GEMINI.md). Drop it on any machine, pick the kind of work you're doing, and the same disciplined core adapts to it — software, devops/setup, marketing & outreach, document creation, data crunching, research, design, and general admin.

The agent is the model plus the harness. The model is ~10% of the outcome; the harness — the rules, tools, memory, guardrails, and feedback loops around it — is the other ~90%, and it's the part you control. This repo is that 90%, generalized and reusable. (The reasoning is in docs/01-harness-philosophy.md; the public work these ideas build on is credited in full under principles & influences.)

It didn't come from a whiteboard. It grew over ~6 months of real, autonomous work — data crunching, marketing outreach, dozens of smaller projects, and one software product still in active development after half a year — across hundreds of sessions. What's here is roughly its fifth iteration: scrubbed of all project specifics and split into a universal core + swappable work-type profiles.

How it works in 4 steps

1. Install once. setup.sh assembles a deliberately lean CLAUDE.md from the universal core (the rules that never change) plus the profile(s) for the kind of work you're doing. Install the core globally once, then add a thin profile per project. Just run ./setup.sh (with no flags it's the wizard) — it builds the command for you and shows it before running.
2. Work one unit at a time. Each session takes a single tracked item and runs it plan → implement → verify → ship with real autonomy — the agent decides routing and scope, and only pauses for the few things that genuinely need a human (a missing credential, an external surprise).
3. Verify before "done." Nothing ships on vibes. verify.sh runs your project's real checks, bug fixes need a failing test first (prove-it), and review gates catch what tests can't — evidence before assertion, every time.
4. Hand off early, and improve the harness. At ~25–30% context used (or when you say "handoff"), the agent safe-states and writes a recall prompt so the next session resumes clean. And when something goes wrong, the habit is to fix the system, not just the symptom — sharpen a rule, add a gate — so that class of failure is less likely next time.

The deep version of all four — why context is split static/dynamic, why rigor scales with stakes, the conductor/orchestrator modes — is in docs/01-harness-philosophy.md (a 5-minute read).

Never used an agent harness? The docs were written for exactly you — an expert developer new to this — and docs/README.md is the map with a reading order (the numbers are the order): your first hour and your first loop · verify means evidence (the load-bearing concept) · operating modes (sessions vs loops; which model for which phase) · why your agent ignored the rule (before it happens) · the safety model (what it can do to your machine, and how to bound it) · adapting it to your team · a glossary · incident-earned dos & don'ts · and a troubleshooting guide for when it's behaving oddly.

Quick start

Three ways in, easiest first. Pick one.

1. Just ask your agent (no terminal needed)

Already using a coding agent — Claude Code, Codex, OpenClaw, Cursor? Don't run anything yourself. From inside your project, paste this and the agent does it all — it clones the harness, auto-detects the right profile for your project, asks you a couple of quick questions, shows the plan, and runs setup in its terminal:

Set up the Agentsmith harness in this project for me. Read the instructions at
https://raw.githubusercontent.com/PromptPartner/agentsmith/master/AGENT-INSTALL.md
and follow them: get the harness, detect the right profile for this project, ask me
anything you need, show me what you'll change, and then run its setup.

It's on-brand: the agent installs its own harness. Full instructions the agent follows live in AGENT-INSTALL.md. (The raw link resolves once the repo is public; until then, clone Agentsmith locally and point your agent at the local AGENT-INSTALL.md.)

2. Run the wizard (it asks; you answer)

# clone somewhere permanent (it's a tool you keep, not per-project), then just run it:
git clone https://github.com/PromptPartner/agentsmith.git ~/tools/agentsmith && cd ~/tools/agentsmith
./setup.sh          # ← no flags = the wizard

That's the default — bare ./setup.sh launches the wizard. It walks you through scope (this project / global / machine-wide / portable export), profile, how careful the assistant should be (safety mode — cautious by default), operator info, MCP servers, plugin packs, and hooks — then prints the exact command it's about to run (so you learn the flags) and runs it on your confirm. Nothing is written until you say yes, and any file it touches is backed up first.

No git? Download the zip, unzip agentsmith-master.zip -d ~/tools && mv ~/tools/agentsmith-master ~/tools/agentsmith — note --self-update later needs a git clone, not a zip.

On Windows (PowerShell): use setup.ps1 — a faithful port with the same flags and behaviour. It needs PowerShell 7+ (pwsh --version; winget install Microsoft.PowerShell if missing). Every setup.sh command here works by swapping setup.sh → pwsh ./setup.ps1; no jq needed. If PowerShell blocks the script, allow it for the session with Set-ExecutionPolicy -Scope Process Bypass. Full detail: INSTALL.md.

git clone https://github.com/PromptPartner/agentsmith.git $HOME\tools\agentsmith
cd $HOME\tools\agentsmith
pwsh ./setup.ps1          # ← the wizard

3. Drive the flags yourself (power users)

Skip the wizard by passing options. On this path the safety default is trusted (runs without prompts — see Permissions); add --safety cautious to soften it.

./setup.sh \
  --profile software-dev \
  --operator-name "Your Name" \
  --operator-role "your role" \
  --tracker github \
  --target /path/to/your/project

# mixed work? list several (dominant first):
./setup.sh --profile devops-setup,software-dev --target .

# cautious / shared machine? assemble the rules only, touch nothing global:
./setup.sh --profile document-creation --safety cautious --assemble-only --target .

Layered setup (recommended once you run this across several projects): install the universal core once globally, then add only the profile per project —

./setup.sh --global --operator-name "Your Name"        # core → ~/.claude/CLAUDE.md + config + plugins
./setup.sh --profile software-dev --profile-only --target /path/to/project   # thin per-project file

Claude Code concatenates the global core with each project's file automatically. See docs/12-platforms-and-tools.md for per-project vs global.

That writes a lean CLAUDE.md into your project, scaffolds the supporting structure, and (unless --assemble-only) installs the global config + the four universal plugins. Re-run any time — it's idempotent and only rewrites its own managed block.

Useful flags: --with-plugins dev-workflow,stack-lsp (opt-in plugin packs, latest from source) · --with-skills (install the bundled 6-skill harness pack — see below) · --with-hooks (pre-commit secret-scan) · --also-agents-md / --also-gemini-md (emit cross-tool rule files) · --update-plugins · --self-update (pull a newer harness + re-assemble — see below) · --doctor (check install health) · --dry-run.

The bundled skill pack (--with-skills). Six self-contained, work-type-neutral skills you can invoke by name: /handoff (wrap up cleanly), /verify (is this shippable?), /harness-help (non-coder? start here — it explains your profile, rules, and what to type next), /harness-doctor (is my harness healthy?), /new-research, /new-feedback. In project mode they install into <project>/.claude/skills/; with --global, into ~/.claude/skills/. New to this? Just run claude in your project and type /harness-help.

Keeping the harness current — --self-update. Once the harness lives in a git checkout, ./setup.sh --self-update (or ./setup.ps1 --self-update) fast-forwards that checkout from its remote and then re-assembles every managed CLAUDE.md block so your rules reflect the new core/profiles in one step. The remote is configurable, never baked in: --from <url>, else $HARNESS_REMOTE, else a one-line .harness/remote file, else the checkout's own origin. Auth auto-detects from the URL — git@…/ssh://… use your SSH key; https://… reads a token from $HARNESS_GH_TOKEN (read at runtime, never written to disk). It refuses to run on a dirty checkout (your local edits are safe), preserves your operator name/role/tracker through the re-assemble, and takes --no-reassemble (fetch only) or --dry-run (preview the plan).

Prefer to do it by hand? See [INSTALL.md