KISS My Agent
Keep It Simple, Scientist. Less ceremony. More science.
Reduce Codex overengineering and overdefense. Build a runnable, verifiable research MVP first, expose errors early, then iterate quickly from real results.
What KISS My Agent Is
KISS My Agent is an open-source Codex Plugin for research and exploratory engineering. It gives Codex a simple set of working principles: start from the current goal or hypothesis, build the smallest version that can run and be validated, then use real results to decide whether to continue, change, or stop.
It is outcome-driven, not process- or workload-driven: the number of files changed, Agents used, checks run, or steps completed cannot replace the question “did this answer the current problem?”
The Two Core Problems It Solves
| Problem | What it means | Common result |
|---|---|---|
| Overengineering | Productizing before the current hypothesis is tested: adding abstractions, configuration, migrations, or platforms for future possibilities that nobody uses today | One experiment becomes a large system, feedback slows down, and both scope and new bugs grow |
| Overdefense | Preventing errors from surfacing naturally by layering validation, retries, fallbacks, exception handling, or gates—and sometimes presenting failure as success | The real cause disappears, a wrong result looks “normal,” and the next iteration starts from unreliable information |
Growing the scope, fixing something other than the code actually in use, treating a passing test as the goal, or letting several Agents conflict over the same work are common consequences of these two tendencies.
Why Codex Can Fall Into Them
Codex tends to produce answers that look complete, robust, and successful. Prompts often ask for “comprehensive,” “robust,” or “production-ready” work without stating the current hypothesis, minimum goal, and stop condition. Adding frameworks, validation, retries, or fallbacks is easy to generate and easy to present as progress. Codex also tends to avoid an obvious failure, so an error may be caught, routed around, or packaged as a usable result. Mature products can genuinely need complete architecture and safeguards when real requirements and risks justify them. Added too early in research, however, they slow the feedback loop and obscure its most valuable signal: why this real run succeeded or failed.
How KISS Drives a Research Loop
Goal or hypothesis → smallest runnable, verifiable version → real run → visible success or failure → next iteration or stop
- Define the question and the minimum success condition for this round so implementation does not quietly rewrite the goal.
- Build only what is needed to run and test the hypothesis. Get a research MVP first; decide whether to productize it after the result.
- Run the real path early. Allow low-cost, recoverable mistakes to expose their original cause instead of covering them with a fallback or empty result.
- Act on the real result: fix the first revealed problem and start the next round, or stop when the hypothesis is answered or the goal is met. More process and changes do not prove more progress.
Multi-Agent work is only an optional accelerator: use it when the task truly splits into independent parts, and keep one clear person or Agent responsible for each shared file, device, or output. “Do not fear mistakes” means only low-cost, recoverable experimentation; never remove or bypass authentication, permissions, irreversible-operation safeguards, or other high-risk safety boundaries.
Is It for You?
| Good fit | Not the problem it solves |
|---|---|
| Research prototypes, algorithm validation, experimental tools, and other work that needs an MVP quickly | Mature product work with stable requirements and a real need for complete compatibility, migration, audit, or safety systems |
| The solution is uncertain and real runs should guide rapid exploration | High-risk work where failure is irreversible and strict safety analysis must come first |
| Debugging hidden errors, or stopping Codex from productizing an imagined future | Deterministic security enforcement, formal verification, a general orchestration platform, or verified non-Codex support |
KISS does not promise to get the first attempt right. It aims to produce trustworthy feedback sooner so the next step can be right.
Quick Start
Tested with authenticated, Plugin-capable Codex CLI 0.152.1 and 0.153.0. You need git and GitHub network access; other Codex versions are not verified. Normal users do not need Python, Node.js, Docker, or another language runtime.
Confirm that this Codex build supports Plugins:
codex --version
codex plugin --help
Install the Plugin:
codex plugin marketplace add AoiOTA/Kiss-My-Agent
codex plugin add kiss-my-agent@kiss-my-agent
At this point only the Plugin is installed. A new Codex session can discover its two Skills, but no persistent project rules or roles have been configured yet.
Open a new Codex session in the complex project. On the tested Codex CLI 0.152.1 baseline, type $ and select kiss-my-agent-setup (kiss-my-agent) in the Skill picker. The picker inserts a structured Skill reference; add the setup request and submit the prompt to invoke it. If you paste raw text instead, use the fully qualified command shown here:
$kiss-my-agent:kiss-my-agent-setup set up this project with the default team
Project setup writes the persistent project rules and role configuration. Trust the project through the Codex interface, then open another new session; only that trusted fresh session loads the project rules and roles. Then ask for work normally:
Find the cause of this failing parser test, make the smallest correct fix, and run the affected tests.
Setup check is optional. It inspects the configured files; it does not prove live Agent behavior:
$kiss-my-agent:kiss-my-agent-setup check this project
Default setup manages three project locations:
.codex/config.toml: fills only missing multi-agent and experimental-context defaults; preserves all model and effort settings..codex/agents/: editable employee-role filesAGENTS.md: the marked KISS instructions block
It preserves existing user configuration and needs no choices by default. On a fresh setup it creates each missing starter role, while every role that already exists is user-owned and is never overwritten. A role removed after setup stays absent. Setup asks only when the target or a conflict is unclear. If setup stops, follow its reported reason and exact path instead of overwriting files; see Installation.
The Plugin has no background service; the Codex Host loads the configuration and starts the requested Agents.
The Default Team
The Master is the main Codex Agent in the conversation you are using now—the primary session—not another employee role.
| Who | Job | Default |
|---|---|---|
| You / Owner | Set the goal, architecture, acceptance criteria, non-goals, and stop point | Human decision |
| Master | Plan, assign work, resolve conflicts, judge evidence, and summarize | Host/session choice |
kiss_explorer |
Investigate and report facts without editing | Follow Master |
kiss_coder |
Implement the assigned change and run its checks | Follow Master |
kiss_reviewer |
Independently inspect the result without editing | Follow Master |
Master uses the current Host/session model and reasoning effort. New seeds omit both overrides and follow the Master; default delegation omits model and effort arguments. Setup preserves existing model choices and roles. Use explicit follow-master configuration to remove selected role and selected-scope [agents] overrides; legacy KMA Master pins require a separate explicit selection. Verify effective settings in a new task. The Master normally assigns directly, may use multiple instances of a role, keeps one Agent responsible for each shared item, and may give one temporary lead to a large independent subsystem.
If delegation is disabled or unavailable, or no suitable role exists, the Master may continue within its capabilities and existing authorization without a staffing approval step. Report unmet explicit requirements for independent checking or a specific role, and real capability gaps; direct execution must not be presented as satisfying them.
The company comparison only explains responsibilities; it is not a fixed workflow or game system.
Setup defaults missing features.context_management.experimental_mode to true, preserving explicit false. On Ubuntu 24.04 with the ChatGPT Pro client, no API key is needed. After updating the Plugin, run setup in the original scope, explicitly configure selected existing roles, then start a new trusted task to verify loading.
Only Read This If You Want Different Model Settings
Choose Master model and effort in the Host. Plugin updates and setup preserve existing settings; to make the three existing roles follow the Master, use this qualified project prompt:
$kiss-my-agent:kiss-my-agent-setup configure agents in this project: make kiss_explorer, kiss_coder, and kiss_reviewer follow master
Configure existing employee roles through Codex:
$kiss-my-agent:kiss-my-agent-setup configure agents for this project
Ordinary role configuration changes selected roles only. Follow-master mode can explicitly remove selected-scope [agents] defaults and separately selected exact marked legacy KMA Master pins; user values remain preserved. See Configuration for scope, precedence and permissions.
Update Now
The first command updates immediately. The second only verifies the installed result:
codex plugin marketplace upgrade kiss-my-agent
codex plugin list --marketplace kiss-my-agent
Look for kiss-my-agent@kiss-my-agent, status installed, enabled, and a version matching the current release badge at the top of this README. Start a new session after an update. Host refresh updates only the Plugin package; it does not change project or global configuration, instructions, or role files.
KISS My Agent has no updater of its own. Codex may refresh an unpinned Git marketplace at startup. Existing roles are never automatically updated or version-classified; use the role wizard or edit their TOML manually when you want newer model or effort choices. Pinning and rollback details are in Installation.
Limitations
- Tested on Codex CLI 0.152.1 and 0.153.0; other versions and non-Codex hosts are not verified.
- Instructions improve the working context but cannot guarantee model compliance, correctness, or acceptance.
- Successful delegation or passing tests do not prove the user's product or research goal.
- The current release has no MCP service, standalone UI, telemetry, evaluation platform, or LTS promise.
- It does not replace authentication, permissions, administrator policy, project safety rules, or domain expertise.
Detailed Documentation
- Installation and recovery / 安装与恢复
- Configuration / 配置
- Testing and evidence / 测试与证据
- FAQ / 常见问题
- Contributing / 贡献
- Security / 安全
The full documentation site is published in English and Simplified Chinese.