Autoresearch: Autonomous Iteration Engine
Turn Claude Code, OpenCode, or OpenAI Codex into a relentless improvement engine: set a goal, define a metric, and let it iterate modify→verify→keep/discard automatically.
Evidence shows 9 safety hooks, enabled by default, with disable options, blocking sensitive files like .env and SSH keys, dangerous commands, and automatic rollback. Data flow transparency is limited; no detailed logging or user visibility. Dependency security is not well documented; no dependency list or vulnerability scanning. External effects are controlled via command allowlist and rollback. Source attribution is only via README author and license, publisher unverified.
Self-consistency is good; README and test files align, multiple test scripts verify hook and orchestrator behavior. Dependency availability is unclear; no runtime dependencies or versions listed. Failure messages are evident in tests, e.g., assertions output FAIL, but actual runtime error handling is not detailed.
Targets Claude Code, OpenCode, and Codex, with multiple installation methods, 14 commands, broad scenario coverage. Capability boundaries are defined via commands and flags, but limitations or failure modes are not explicit. Trigger precision is defined via commands and flags, but limitations or failure modes are not explicit. Environment fit is good, supporting multiple platforms and installation methods.
Information architecture is clear with README, guides, command docs. Install notes are detailed with multiple methods. Naming is stable, command names consistent. Examples and FAQ are mentioned in README but full FAQ content not provided. Known limitations are not explicitly listed. License is MIT, version 2.2.1 in README, but no changelog. Maintenance responsibility is unclear, publisher unverified.
Output usability is high; commands generate structured reports and files. Marginal value is high; automated iteration and diverse commands provide significant value. Cost-benefit is good; claims 95% token reduction but no benchmark data.
Claim traceability is limited; performance claims in README lack evidence. Cross-source corroboration is limited; test files provide some validation but not independent. Fact-inference separation is insufficient; README claims and test results are not clearly distinguished.
- Publisher identity is unverified; use with caution.
- Dependency security is not well documented; review dependency list and vulnerabilities.
- Data flow transparency is limited; hooks may log data but not clearly documented.
- Performance claims (e.g., 95% token reduction) lack benchmark evidence.
What does this agent do, and when should you use it?
Autoresearch is a skill pack built on Karpathy's autoresearch principles, providing 14 commands and 9 safety hooks for Claude Code, OpenCode, and OpenAI Codex. It transforms one-off code improvements into an automated loop of modify→verify→keep/rollback, making one focused change per iteration and evaluating it with mechanical metrics (test coverage, performance) while auto-reverting failures via git. v2.2.0 introduces an autonomous orchestrator: type a plain-language goal, and it classifies it, derives a success predicate, and loops across subcommands until done. Architecturally, v2.1.0 replaced the monolithic 813-line SKILL.md with a 41-line routing file and 12 self-contained command files, slashing token usage by 95% per invocation. The skill installs into Claude Code (plugin or npx), OpenCode, and Codex, covering everything from coding, debugging, security audits, to product improvement.
It provides a full command suite: /autoresearch runs the classic iteration loop (review state → pick one change → commit → run verification → keep or revert); /autoresearch:plan converts a natural-language goal into a validated config; /autoresearch:debug iteratively hunts bugs using hypotheses; /autoresearch:fix auto-repairs errors to zero; /autoresearch:security performs STRIDE/OWASP audits; /autoresearch:ship drives releases through 8 phases; /autoresearch:scenario generates edge cases across 12 dimensions; /autoresearch:predict simulates 5 expert personas; /autoresearch:learn auto-generates docs; /autoresearch:reason runs adversarial debate with blind judges; /autoresearch:probe interrogates requirements with 8 adversarial personas; /autoresearch:improve researches ICP and produces PRDs; /autoresearch:evals analyzes historical result trends; /autoresearch:regression gates stability with STABLE/UNSTABLE verdicts. Every command ships with bounded default iterations, supports Guard commands to prevent regressions, logs results in TSV, and supports --chain chaining. Installation is via npx, plugin, guided script, or manual copy.
- A frontend developer wants to boost test coverage: run /autoresearch in Claude Code with a Goal and Metric, letting it iterate until 90% coverage.
- A backend team faces many failing tests before CI: use /autoresearch:fix to automatically repair all errors until passing.
- A security engineer needs periodic STRIDE/OWASP audits: run /autoresearch:security and get a structured report with code evidence.
- A product manager wants to derive requirements for a new feature: use /autoresearch:probe to surface constraints and /autoresearch:improve to generate PRDs.
- A developer before release needs to ensure no regressions: run /autoresearch:regression to get a STABLE/UNSTABLE verdict.
- A maintainer wants to generate docs for an existing codebase: /autoresearch:learn --mode init creates reference docs and architecture diagrams.
What are this agent's strengths and limitations?
- Dramatically reduces token usage: v2.1.0 cut tokens per invocation by 95% (from ~100K to 5-8K).
- Ships with 9 safety hooks that block reading sensitive files (.env, keys), dangerous commands (force-push, rm -rf), etc.
- Supports three major agent platforms (Claude Code, OpenCode, Codex) with unified installation scripts.
- Every command has a bounded default iteration count, preventing infinite loops; failed changes auto-revert via git.
- Rich command set covers the entire dev workflow: planning, debugging, fixing, security, shipping, scenario generation, doc generation.
- Core dependency on Claude Code's Skill system; though ports exist for OpenCode and Codex, installation is more complex (manual copy or scripts).
- Not compatible with ChatGPT or other non-coding agents; cannot be used there.
- Requires users to provide a mechanically verifiable metric; for hard-to-quantify goals (e.g., subjective design) you need extra setup (like /autoresearch:reason).
- Requires a session restart after install for commands to resolve — a platform limitation.
- Even bounded iterations can consume significant time and tokens; users need to monitor long runs.
How do you install or deploy this agent?
Installation varies by platform:
Claude Code (recommended via npx):
npx skills add uditgoenka/autoresearchOr via plugin:
/plugin marketplace add uditgoenka/autoresearch
/plugin install autoresearch@autoresearchOr manually copy the .claude directory into your project or globally. Or use the guided installer:
git clone https://github.com/uditgoenka/autoresearch.git
cd autoresearch
./scripts/install.sh --claude --globalOpenCode:
./scripts/install.sh --opencode --globalCodex:
./scripts/install.sh --codex --globalHow do you use this agent?
After installation, invoke commands directly in your Claude Code session. Example:
/autoresearch
Goal: Increase test coverage from 72% to 90%
Scope: src/**/*.test.ts, src/**/*.ts
Metric: coverage % (higher is better)
Verify: npm test -- --coverage | grep "All files"
Iterations: 25Or use the orchestrator mode:
/autoresearch help me fix the login bugUseful subcommands:
- /autoresearch:plan to turn goals into configs.
- /autoresearch:debug to hunt bugs.
- /autoresearch:security for audits.
- /autoresearch:ship to release.
If you're on OpenCode, use underscore naming (/autoresearch_debug); on Codex, use $autoresearch debug syntax.
How does this agent compare with similar options?
Compared to Karpathy's original autoresearch, this repository generalizes it beyond ML models to any domain, adds 14 commands and safety hooks, and supports multiple agent platforms.
FAQ
What runtime environment do I need?
Is it safe? Could it break my code?
What if I don't know which metric to use?
Can it work for non-code tasks?
How do I stop the loop?
Iterations: N to your inline config. Since it commits before verifying, your last successful state remains in git.