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 missing Astra/high, multi-agent and experimental-context defaults; preserves user values and updates only the exact legacy pair described in Configuration..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 | gpt-6-astra / high default |
kiss_explorer |
Investigate and report facts without editing | gpt-6-astra / medium |
kiss_coder |
Implement the assigned change and run its checks | gpt-6-astra / medium |
kiss_reviewer |
Independently inspect the result without editing | gpt-6-astra / medium |
Setup fills missing master fields with gpt-6-astra / high; current seed roles explicitly use gpt-6-astra / medium. Existing explicit user choices are preserved. The role wizard changes selected roles only. Static checks do not prove effective Host settings; verify them 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 Astra task to verify loading.
Only Read This If You Want Different Model Settings
Setup fills missing master fields with gpt-6-astra / high; current seed roles explicitly use gpt-6-astra / medium. Existing explicit user choices are preserved. The role wizard changes selected roles only. Static checks do not prove effective Host settings; verify them in a new task.
For child Agents, Codex resolves an explicit spawn setting first, then the corresponding [agents] default, then the parent; an explicit role-file value is the final override. The current starter roles explicitly set Astra / medium as that final override.
Plugin updates and setup preserve every existing role. To explicitly set gpt-6-astra and medium effort in all three existing KISS roles, use this exact qualified prompt:
$kiss-my-agent:kiss-my-agent-setup configure agents in this project: for kiss_explorer, kiss_coder, and kiss_reviewer, set model to gpt-6-astra and model_reasoning_effort to medium
Configure existing employee roles through Codex:
$kiss-my-agent:kiss-my-agent-setup configure agents for this project
The role wizard changes only an existing role's model, reasoning effort, and permission mode; it does not modify the Master. See Configuration for global roles, exact precedence, permissions, and legacy setup migration details.
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.