![\"Auto](\"assets/autoresearch-banner.svg\")
\n\n \n
\n ![\"v3.18.3\"](\"https://img.shields.io/badge/version-v3.18.3-58a6ff?style=flat\"){kind=icon}
![\"Stars\"](\"https://img.shields.io/github/stars/Maleick/AutoResearch?style=flat&color=58a6ff\")
![\"Last](\"https://img.shields.io/github/last-commit/Maleick/AutoResearch?style=flat\")
![\"Version\"](\"https://img.shields.io/github/v/release/Maleick/AutoResearch?style=flat\")
![\"License\"](\"https://img.shields.io/github/license/Maleick/AutoResearch?style=flat\")
![\"Docs\"](\"https://img.shields.io/badge/docs-autoresearch.teamoperator.red-blue?style=flat\"){kind=icon}
\n Docs •\n Wiki •\n Commands •\n Runtime •\n Self-Improvement\n
\n\nMulti-runtime autonomous recursive self-improvement engine.
\n\n```text\n┌──────────────────────────────────────────────┐\n│ ITERATION MODEL Subagent-first │\n│ ORCHESTRATION Standing pool │\n│ VERIFICATION Mechanical metrics │\n│ PERSISTENCE State + Memory │\n│ META-LEARNING Strategy adaptation │\n└──────────────────────────────────────────────┘\n```\n\n## What It Does\n\nAuto Research is a **subagent-first autonomous iteration engine** that runs structured improve-verify loops inside **OpenCode** or **Hermes Agent**. Unlike simple task runners, it maintains a pool of specialized subagents, persists learnings across iterations, and can run recursive self-improvement loops on its own codebase.\n\n- **Plans** experiments from a measurable goal\n- **Modifies** one focused change per iteration\n- **Verifies** mechanically — never on intuition alone\n- **Keeps or discards** based on strict metric improvement\n- **Learns** from patterns across iterations\n- **Repeats** until the stop condition is met\n\n## The Core Loop\n\n```mermaid\nflowchart LR\n A[\"Plan\"] --> B[\"Modify\"]\n B --> C[\"Verify\"]\n C --> D{\"Keep?\"}\n D -->|yes| E[\"Learn\"]\n D -->|no| B\n E --> F[\"Memory\"]\n F --> A\n```\n\n```mermaid\nflowchart TD\n A[\"Goal + Metric + Verify\"] --> B[\"Baseline\"]\n B --> C[\"Pool Init\"]\n C --> D[\"Iteration N\"]\n D --> E[\"Subagent Context\"]\n E --> F[\"Focused Change\"]\n F --> G[\"Mechanical Verify\"]\n G --> H{\"Strict Improvement?\"}\n H -->|yes| I[\"Keep + Record\"]\n H -->|no| J[\"Discard + Reset\"]\n I --> K{\"Stop Condition?\"}\n J --> K\n K -->|no| D\n K -->|yes| L[\"Report + Memory\"]\n```\n\n## The Self-Improvement Loop\n\nAuto Research can run on itself. The recursive loop adds a meta-orchestrator that:\n\n```mermaid\nflowchart TD\n A[\"Meta-Goal: Improve AutoResearch\"] --> B[\"Run Child Loop\"]\n B --> C[\"Measure: Tests pass? Docs improved?\"]\n C --> D{\"Child Success?\"}\n D -->|yes| E[\"Update Memory + Strategy\"]\n D -->|no| F[\"Adapt Approach\"]\n E --> G[\"Persist Learnings\"]\n F --> B\n G --> H[\"Meta-Report\"]\n H --> I{\"Meta-Stop?\"}\n I -->|no| B\n I -->|yes| J[\"Archive Run\"]\n```\n\nSee [`skills/autoresearch/references/self-improve-loop.md`](skills/autoresearch/references/self-improve-loop.md) for the full recursive loop specification.\n\n## Installation\n\n### OpenCode\n\nFor OpenCode, paste this one-line install prompt into your agent. This URL is pinned to the immutable `v3.18.3` release instructions:\n\n```text\nFetch and follow instructions from https://raw.githubusercontent.com/Maleick/AutoResearch/refs/tags/v3.18.3/INSTALL.md\n```\n\nRecommended plugin install in `opencode.json`:\n\n```json\n{\n \"plugin\": [\"opencode-autoresearch@latest\"]\n}\n```\n\nFor reproducible/pinned installs, see [INSTALL.md](INSTALL.md#pinned-installation-reproducible).\n\nRestart OpenCode, then run the setup wizard:\n\n```text\n/autoresearch\n```\n\n### Hermes Agent\n\n```bash\n# 1. Clone AutoResearch\ngit clone https://github.com/Maleick/AutoResearch.git\ncd AutoResearch\nnpm install\n\n# 2. Install the Hermes skill\nmkdir -p ~/.hermes/skills/software-development/autoresearch\ncp skills/hermes/autoresearch-prompt.md ~/.hermes/skills/software-development/autoresearch/SKILL.md\ncp skills/hermes/INTEGRATION.md ~/.hermes/skills/software-development/autoresearch/REFERENCES.md\n\n# 3. Create a cronjob\nhermes cron create \\\n --name \"autoresearch-loop\" \\\n --workdir ~/projects/AutoResearch \\\n --skill autoresearch-hermes \\\n \"every 15m\" \\\n \"Run AutoResearch iteration loop. Detect phase from .autoresearch/state.json and execute one phase. Approved verify command: \\\"npm run test:coverage\\\". Approved guard command: \\\"npm run typecheck\\\".\"\n```\n\nSee [`skills/hermes/README.md`](skills/hermes/README.md) for full Hermes setup, troubleshooting, and command mapping.\n\n### npm CLI (both runtimes)\n\nGlobal install path:\n\n```bash\nnpm install -g opencode-autoresearch\nautoresearch doctor\nautoresearch --version\n```\n\nOne-time package runner path:\n\n```bash\nnpx opencode-autoresearch doctor\n```\n\nSee [`INSTALL.md`](INSTALL.md) for prerequisites, verification, updating, and troubleshooting.\n\n## Quick Start\n\n### OpenCode\n\n```bash\n# 1. Add the plugin to opencode.json\n# { \"plugin\": [\"opencode-autoresearch@latest\"] }\n\n# 2. Restart OpenCode\n\n# 3. Navigate to your project\ncd ~/Projects/my-project\n\n# 4. Start Auto Research in OpenCode\n/autoresearch\n```\n\n### Hermes Agent\n\n```bash\n# 1. Ensure the skill is installed (see Installation above)\n\n# 2. Initialize state from a trusted shell before enabling unattended cron\nautoresearch init \\\n --goal \"Improve test coverage\" \\\n --metric \"coverage_pct\" \\\n --direction \"higher\" \\\n --verify \"npm run test:coverage\" \\\n --guard \"npm run typecheck\" \\\n --iterations 20 \\\n --mode background\n\n# 3. Start the cronjob\nhermes cron resume autoresearch-loop\n\n# 4. Check progress\ncat .autoresearch/state.json | jq .\n```\n\n## Runtime Surfaces\n\n| Surface | Entry point |\n| --- | --- |\n| OpenCode | `/autoresearch`, `/autoresearch:plan`, `/autoresearch:debug`, `/autoresearch:fix`, `/autoresearch:learn`, `/autoresearch:predict`, `/autoresearch:scenario`, `/autoresearch:security`, `/autoresearch:ship` |\n| Hermes | Cronjob `autoresearch-loop` (see `skills/hermes/README.md`) |\n\n## Commands\n\n| Command | Purpose | Hermes Equivalent |\n| --- | --- | --- |\n| `/autoresearch` | Default improve-verify loop | Cron runs iteration loop |\n| `/autoresearch:plan` | Planning workflow | Subagent task: plan experiments |\n| `/autoresearch:debug` | Debugging workflow | Subagent task: debug failures |\n| `/autoresearch:fix` | Fix workflow | Subagent task: fix issues |\n| `/autoresearch:learn` | Learning workflow | Memory tool + pattern analysis |\n| `/autoresearch:predict` | Prediction workflow | Subagent task: predict outcomes |\n| `/autoresearch:scenario` | Scenario expansion | Subagent task: expand scenarios |\n| `/autoresearch:security` | Security review | Subagent task: security audit |\n| `/autoresearch:ship` | Ship-readiness workflow | Subagent task: ship checks |\n\n## CLI Commands\n\n| Command | Purpose |\n| --- | --- |\n| `autoresearch init` | Initialize a run |\n| `autoresearch goal init` | Create a `GOAL.md` goal definition file (interactive or from flags) |\n| `autoresearch wizard` | Generate setup summary |\n| `autoresearch status` | Print run status |\n| `autoresearch explain` | Human-readable run state |\n| `autoresearch history` | Show recent iteration log |\n| `autoresearch scores` | Show score trend history |\n| `autoresearch badge` | Generate score/component badge markdown + SVG |\n| `autoresearch config` | Show runtime configuration |\n| `autoresearch report` | Generate markdown report |\n| `autoresearch summary` | Aggregate stats across runs |\n| `autoresearch suggest` | Suggest next goal from memory |\n| `autoresearch launch` | Launch background run |\n| `autoresearch stop` | Request stop |\n| `autoresearch resume` | Resume background run |\n| `autoresearch complete` | Mark run complete |\n| `autoresearch record` | Record iteration result |\n| `autoresearch export` | Export run data (json/md) |\n| `autoresearch completion` | Generate shell completions |\n| `autoresearch doctor` | Verify installation |\n| `autoresearch help` | Show usage |\n\n### `autoresearch goal init`\n\nCreate a `GOAL.md` goal definition file. Supports interactive wizard, CLI flags, and stdin JSON.\n\n**Interactive (TTY):**\n```bash\nautoresearch goal init\n```\n\n**From flags (non-interactive):**\n```bash\nautoresearch goal init \\\n --goal \"Reduce test failures\" \\\n --metric failures \\\n --direction lower \\\n --verify \"npm test\" \\\n --guard \"npm run lint\"\n```\n\n**From a preset template:**\n```bash\nautoresearch goal init --template performance # benchmark_ms / lower / npm run bench\nautoresearch goal init --template quality # test_failures / lower / npm test\nautoresearch goal init --template coverage # coverage_pct / higher / npm run coverage\n```\n\n**From stdin JSON (CI / scripted use):**\n```bash\necho '{\"goal\":\"reduce latency\",\"metric\":\"p99_ms\",\"direction\":\"lower\",\"verify\":\"npm run bench\"}' \\\n | autoresearch goal init\n```\n\n**Dry-run preview:**\n```bash\nautoresearch goal init --template performance --dry-run\n```\n\n## Architecture\n\n```mermaid\nflowchart LR\n A[\"OpenCode /autoresearch\"] --> B[\"CLI\"]\n H[\"Hermes Cronjob\"] --> B\n B --> C[\"Run Manager\"]\n C --> D[\"State JSON\"]\n C --> E[\"Results TSV\"]\n C --> F[\"Subagent Pool\"]\n F --> G[\"Orchestrator\"]\n F --> I[\"Scout\"]\n F --> J[\"Analyst\"]\n F --> K[\"Verifier\"]\n F --> L[\"Synthesizer\"]\n```\n\n## Runtime Artifacts\n\n| Artifact | Purpose |\n| --- | --- |\n| `.autoresearch/state.json` | Checkpoint state for the current run |\n| `autoresearch-results.tsv` | Iteration log |\n| `autoresearch-report.md` | End-of-run report |\n| `autoresearch-memory.md` | Reusable memory for later runs |\n| `.autoresearch/launch.json` | Background launch manifest |\n\n## Examples\n\nSee [docs/examples/README.md](docs/examples/README.md) for reproducible run examples with complete state, results, and report artifacts.\n\n## Self-Improvement Mode\n\nRun Auto Research on its own codebase:\n\n```bash\n# Initialize a recursive self-improvement run\nautoresearch init \\\n --goal \"Improve test coverage and documentation\" \\\n --metric \"coverage_pct\" \\\n --direction \"higher\" \\\n --verify \"npm run test:coverage\" \\\n --guard \"npm run typecheck\" \\\n --mode \"background\" \\\n --iterations \"20\"\n\n# Check status\nautoresearch status\n\n# Resume if stopped\nautoresearch resume\n```\n\nThe self-improvement loop:\n1. Baselines current state (tests, docs, metrics)\n2. Dispatches subagents to identify improvement opportunities\n3. Makes one focused change per iteration\n4. Verifies mechanically (tests, typechecks, lint)\n5. Keeps strict improvements, discards regressions\n6. Records patterns to `autoresearch-memory.md`\n7. Adapts strategy when repeated discards occur\n8. Continues until iteration cap or goal met\n\n## Subagent Pool\n\nThe standing pool provides specialized roles reused across iterations:\n\n| Role | Purpose |\n| --- | --- |\n| `orchestrator` | Owns goal, state, and keep/discard decisions |\n| `scout` | Gathers context and surfaces opportunities |\n| `analyst` | Challenges hypotheses and identifies risks |\n| `verifier` | Runs mechanical verification independently |\n| `synthesizer` | Compiles findings into next iteration plan |\n| `security_reviewer` | Security-focused review variant |\n| `debugger` | Debug workflow specialization |\n| `release_guard` | Ship-readiness verification |\n| `research_tracker` | Pattern tracking across iterations |\n\n## Runtime Comparison\n\n| Feature | OpenCode | Hermes |\n|---------|----------|--------|\n| Entry | `/autoresearch` slash command | Cronjob or `delegate_task` |\n| Subagents | Standing pool (unlimited) | Batch via `delegate_task` (max 3) |\n| Real-time | Yes | 15-minute cron intervals |\n| Slash commands | 8 variants | Separate cron jobs or tasks |\n| State | `.autoresearch/state.json` | Same file format |\n| Memory | File-based (`autoresearch-memory.md`) | `memory` tool + file |\n| Background | `autoresearch launch` | Native cron |\n| Resume | `autoresearch resume` | Cron continues automatically |\n\n## Development\n\n```bash\nnpm run typecheck # TypeScript strict checks\nnpm run build # Compile TypeScript to dist/\nnpm run test # Run test suite\nnpm pack --dry-run # Preview shipped package contents\n```\n\n## Repository Layout\n\n```text\nsrc/ # TypeScript source (runtime helpers, CLI, subagent pool)\ndist/ # Compiled JavaScript output\ncommands/ # OpenCode command surfaces\nskills/autoresearch/ # OpenCode skill bundle with references\n references/ # Workflow and runtime references\n core-principles.md # Loop discipline\n loop-workflow.md # Main iteration workflow\n subagent-orchestration.md # Pool management\n state-management.md # State semantics\n self-improve-loop.md # Recursive self-improvement\nskills/hermes/ # Hermes Agent skill bundle\n README.md # Hermes setup and usage\n INTEGRATION.md # Architecture and command mapping\n autoresearch-prompt.md # Cron prompt template\nhooks/ # Shell hooks for session lifecycle\ndocs/ # Install and architecture docs\nwiki/ # GitHub wiki pages\n.autoresearch/ # Runtime state directory\n.opencode-plugin/ # Plugin manifest\n```\n\n## Notes\n\n- **OpenCode** users: install via `opencode.json` plugin array or `npm install -g opencode-autoresearch`.\n- **Hermes Agent** users: install via skill files in `skills/hermes/` and create a cronjob.\n- The CLI uses Node.js ESM modules.\n- Self-improvement loops require `--mode background` for long-running unattended operation.\n- Memory files (`autoresearch-memory.md`) are portable across runs and repositories.\n\n## License\n\nMIT — See [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md"}