Simple Man

May 23, 2026 · View on GitHub

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

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.

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.

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

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.

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

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.

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.