Portable contracts for coding agents.
agent-md installs one source-of-truth rules file, repo-local hooks,
persistent task state, and a few helper scripts so agents can stop
guessing and start proving their work.
Honest scope:
- Markdown rules are advisory. The agent has to read and follow them.
- Hooks and git hooks are enforceable where the host agent supports them.
- Tests, type-checks, screenshots, and evidence notes are stronger than model self-assessment.
# From inside your project directory
curl -sL https://raw.githubusercontent.com/iamfakeguru/agent-md/main/install.sh | bashInstalls support for Claude Code, Codex, Cursor, and Windsurf by default.
your-project/
AGENT.md # source of truth
AGENTS.md # Codex / Cursor / Windsurf
CLAUDE.md # Claude Code
agent-md.toml.example # deterministic verification config
.claude/
settings.json
hooks/ # Claude Code enforcement
.codex/
hooks.json
hooks/ # Codex hook wrappers
.agents/skills/ # native Codex skills
agent-md-verify/
visual-evidence/
.cursor/rules/agent-md.mdc # Cursor project rule
.windsurf/rules/agent-md.md # Windsurf workspace rule
.agent-md/
bin/
discover_helpers.sh
doctor.sh
playwright-capture.sh
memory/
agents.md
plan.md
progress.md
verify.md
gotchas.md
.githooks/pre-commit # optional fallback for any agent
Agent guidance has two layers:
| Layer | Purpose | Reliability |
|---|---|---|
| Rules files | Judgment, planning, style, process | Advisory |
| Hooks/artifacts | Type-checks, tests, lint, state updates, visual evidence | Enforceable where supported |
If something can be forgotten or rationalized away, move it out of prose and into a checked artifact.
The production-agent lessons that fit this repo are applied as contracts, not as copied API boilerplate:
- Cost/context discipline — concise directives, helper discovery, and
durable
memory/files instead of giant repeated prompts. - Reliability — structured hook JSON, deterministic checks, destructive-command blocks, and explicit unverified-state warnings.
- Performance — bounded work slices, selective context loading, safe parallel tool use, and truncation warnings.
- Tool use — structured tool-result guidance, validation before execution, and clear helper boundaries.
- Output quality — tests, runtime evidence, visual artifacts, and independent/adversarial verification.
API-specific features such as prompt caching, streaming display,
provider retries, idempotency keys, temperature tuning, and batch
processing belong in the application or host runtime. agent-md tells
the coding agent to document and verify those choices when the project
uses them; it does not pretend to enforce provider behavior from a rules
file.
| Check | Claude Code | Codex | Cursor / Windsurf / Other |
|---|---|---|---|
| Bash safety | Hard block via .claude/hooks/block-destructive.sh |
Hard block via .codex/hooks/pre-tool-use.sh |
Not covered |
| Type-check/lint/tests at finish | Hard block via stop-verify.sh |
Continuation via .codex/hooks/stop.sh |
Optional .githooks/pre-commit |
memory/progress.md updated |
Hard block via state-enforcement.sh |
Continuation via .codex/hooks/stop.sh |
Optional .githooks/pre-commit |
| UI visual evidence | Advisory by default, hard block when [visual].required = true |
Same through Codex Stop wrapper | Advisory through rules |
| New export without nearby test | Advisory | Advisory through rules/skills | Advisory through rules |
| Truncated Bash output | Advisory | Advisory through Codex PostToolUse | Not covered |
| Planning, context, edit safety | Advisory | Advisory | Advisory |
Codex hooks are experimental and require:
[features]
codex_hooks = truein ~/.codex/config.toml.
# All supported agents
./install.sh .
# Specific agents
./install.sh --agent=claude .
./install.sh --agent=codex,cursor .
# Git hook fallback
./install.sh --githooks .
./install.sh --no-githooks .
# Claude settings handling
./install.sh --claude-settings=skip .
./install.sh --claude-settings=merge .
./install.sh --claude-settings=replace .The installer backs up existing top-level rule files before replacing
them. Existing memory/*.md files are never overwritten. Existing
.claude/settings.json is skipped by default unless you choose merge
or replace.
Heuristics are useful, but explicit commands are better. Copy the example config and declare your project checks:
cp agent-md.toml.example agent-md.toml[verify]
typecheck = "npx --no-install tsc --noEmit"
lint = "npx --no-install eslint ."
test = "pnpm test"
lint_file = "npx --no-install eslint {file}"
[visual]
required = true
artifacts_dir = ".agent/visual"
freshness_seconds = 3600When no checks are detected, hooks allow completion but warn that the work is unverified.
UI work needs more than passing tests. Capture a screenshot:
./.agent-md/bin/playwright-capture.sh http://localhost:3000 .agent/visual/home.pngThen write .agent/visual/home.md:
# Visual Check
Changed files:
- src/app/page.tsx
Route: /
Viewport: 1280x800
Artifact: home.png
Observed result: layout renders without overlap at desktop width.The strict visual hook requires a fresh non-empty markdown file that references a fresh non-empty image by filename and includes the required fields.
memory/ is the durable handoff surface between sessions:
agents.md— active agents, MCPs, tech stack, toolingplan.md— macro design and vertical slicesprogress.md— current task, completed tasks, backlog, blocked workverify.md— definition of donegotchas.md— mistakes already corrected by the human
The state hook blocks completion when source files changed but
memory/progress.md did not.
agent-md intentionally separates plain helper scripts from Codex-native
skills.
.agent-md/bin/*are shell helpers any agent can run..agents/skills/<name>/SKILL.mdare native Codex skills.
Discover helpers:
./.agent-md/bin/discover_helpers.sh
./.agent-md/bin/doctor.shUse Codex skills with $agent-md-verify or $visual-evidence.
- A rules file cannot force judgment by itself.
- Hooks only cover events exposed by the host agent.
- Pre-commit hooks can be bypassed with
git commit --no-verify. - Bash safety hooks are guardrails, not a sandbox.
- Cursor and Windsurf get rules plus optional git-hook fallback, not native runtime enforcement from this repo.
bats tests/
shellcheck .claude/hooks/*.sh .codex/hooks/*.sh .agent-md/bin/*.sh .githooks/pre-commit install.shCI runs Bats, ShellCheck, JSON validation, alias-sync checks, and installer smoke tests.
MIT.
