Simple Man

High-compression professional communication mode for coding agents.

Simple Man is not a persona. It is a communication policy:

Minimum user-facing words; same work quality.

It is designed for users who work with agents for many hours and want lower cognitive load without making the agent passive, less careful, or less proactive.

What it changes

It compresses user-facing communication:

• no preambles
• no praise
• no filler
• no repeated recaps
• no generic closing offers
• sentence fragments and compact labels when clear
• compact status updates
• compact final answers
• compact review findings
• compact explanations and plans

What it does not change

It must not reduce:

• repository search
• usage search
• dependency tracing
• impact analysis
• validation
• test/lint/typecheck effort
• proactive detection of related correctness issues

Examples

Same model, same failing mini-project, same task. Only the communication policy changed. These are real captured Codex final answers from evals/reports/codex-skill-comparison.md.

Expired-session auth bug

Prompt: inspect a Node auth API where expired sessions are still accepted, fix it, run tests, and hand off root cause, files changed, validation, and remaining risk.

No Simple Man	With Simple Man
Engineering Handoff Root cause: authenticate accepted any session returned by store.get(token) and never checked session.expiresAt against the store clock. Files changed: src/middleware.js: rejects sessions with missing/non-numeric expiresAt or expiresAt <= store.now(). test/auth.test.js: added coverage for the expiration boundary where expiresAt === now. Validation: npm test passed, 3/3 tests. Remaining risk: This assumes expiresAt and store.now() use the same timestamp unit, and that auth store implementations provide the existing now() API.	Fixed. Root cause: authenticate trusted store.get(token) and never checked session.expiresAt. Files changed: src/middleware.js Validation: npm test -> pass, 2/2 tests. Remaining risk: none identified.
Result: both fixed the bug and passed npm test. Answer length: 601 chars vs 221 chars, 63% shorter.

Payment idempotency retry bug

Prompt: inspect a Python payment ledger where retrying with the same idempotency key creates another local charge, fix it, run tests, and hand off root cause, files changed, validation, and remaining risk.

No Simple Man	With Simple Man
Root cause The charge path was append-only. After a gateway timeout, the fake provider had already accepted a charge, but retrying with the same idempotency key created a new provider charge and the ledger had no local idempotency lookup to return an existing local charge. Files Changed ledger.py: added idempotency-key indexes in FakeGateway and PaymentLedger. Provider retries now replay the original remote charge. Ledger retries now return the existing local charge instead of appending another. test_ledger.py: extended the retry test to verify no extra gateway call or local charge is created after the local charge exists. Validation Command: PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v Result: passed, 1 test run. Remaining Risk This is still an in-memory implementation. A production version would need persistent idempotency storage with transaction/concurrency protection, and likely validation that reused idempotency keys match the original customer and amount.	Root cause: no idempotency-key lookup; timeout lost the accepted provider charge locally, and retries created new charge records. Files changed: ledger.py: added provider/local idempotency maps; same key returns existing charge; mismatched reuse raises ValueError. test_ledger.py: added regression for repeated same-key retry. Validation: PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v -> passed, 2 tests. Remaining risk: idempotency state is in-memory only; no durable/concurrent store in this fixture.
Result: both fixed the retry bug and passed python3 -m unittest -v. Answer length: 1022 chars vs 520 chars, 49% shorter.

Unsafe migration rollout order

Prompt: inspect a SQLite rollout where a migration drops legacy_sessions.expires_at before the backup reads it, fix it, run tests, and hand off root cause, files changed, validation, and remaining risk.

No Simple Man	With Simple Man
Root Cause rollout.py applied migrations/001_drop_expires_at.sql before running backup_legacy_sessions.sql. The backup query still selects legacy_sessions.expires_at, so the column was gone before the backup could read it. Files Changed rollout.py: moved backup_legacy_sessions(conn) before apply_drop_migration(conn). Validation Command: python3 -m unittest test_rollout.py Result: passed, 1 test ran OK. Remaining Risk The focused test now covers the required order: backup reads expires_at, then the migration drops it. Remaining risk is limited to behavior outside this small rollout path, such as real backup storage durability or additional migrations not represented in the current test.	Root cause: rollout() ran apply_drop_migration() before backup_legacy_sessions(), so expires_at was dropped before the backup query selected it. Files changed: rollout.py Validation: python3 -m unittest test_rollout.py passed, 1 test. Remaining risk: none known; only the focused repo test exists and was run.
Result: both fixed the rollout order and passed python3 -m unittest -v. Answer length: 736 chars vs 324 chars, 56% shorter.

Agent support

This repo ships two activation surfaces:

• full skill: skills/simple-man/SKILL.md
• compact always-on runtime policy: AGENTS.md, AGENTS.md.snippet, CLAUDE.md, GEMINI.md

Agent/tool	Path
OpenAI Codex / Agent Skills	skills/simple-man/SKILL.md, AGENTS.md, AGENTS.md.snippet
Claude Code	CLAUDE.md, optional global skill copy
Gemini CLI	GEMINI.md, or configure Gemini to read AGENTS.md
Qwen Code	AGENTS.md, optional global skill copy
Cursor / Windsurf / Cline / Copilot / Continue / Zed / Junie	AGENTS.md, or copy AGENTS.md.snippet into that agent's native rule file
Amp / OpenCode / Kilo / Roo / Aider / other AGENTS.md agents	AGENTS.md

Always-on project files do not invoke $simple-man; they inline a compact runtime policy to avoid loading full skill overhead on every turn.

Agent-specific dotdir rule files are not committed here by default. They are target-project activation files, not the source of the skill.

See INSTALL.md for per-agent setup notes.

Benchmark

This repo includes two Codex-based token benchmark suites:

• runtime_economics: coding-agent cost, including instruction overhead and long-session amortized net.
• reference_compression: Caveman README-style output compression against a verbose normal helpful baseline.

make bench-dry-run
make bench-refresh
make bench
make bench-check
make bench-compare-sample
make bench-reference-dry-run
make bench-reference-refresh
make bench-reference
make bench-reference-check

The benchmark compares control, generic terse, simple_man_runtime, simple_man_candidate, simple_man_skill, and optional Caveman arms. Runtime headlines use output compression and long-session net; reference headlines use output-only compression vs normal.

See evals/README.md.

Install

Install Simple Man as an always-on Codex communication policy:

curl -fsSL https://raw.githubusercontent.com/Maksim-Burtsev/simple-man/master/install.sh | bash

Important: Simple Man is always-on after install. This is expected.

The installer copies skills/simple-man to ~/.codex/skills/simple-man and writes the compact runtime policy into ~/.codex/AGENTS.md.

Codex plugin package

To add the repo-local plugin package to Codex:

codex plugin marketplace add Maksim-Burtsev/simple-man --ref master
codex plugin add simple-man@simple-man

Plugin install makes the skill available in Codex. Always-on behavior comes from the installer writing global Codex instructions.

Recommended usage

Use it as the default communication layer for Codex when you want minimum user-facing words without reducing search, validation, or implementation effort.