{"id":50312651,"url":"https://github.com/ehmo/autoresearch-skill","last_synced_at":"2026-05-28T22:02:08.555Z","repository":{"id":352724392,"uuid":"1181846880","full_name":"ehmo/autoresearch-skill","owner":"ehmo","description":"Autonomous codebase improvement","archived":false,"fork":false,"pushed_at":"2026-04-20T20:54:42.000Z","size":36,"stargazers_count":43,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T22:33:48.295Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T17:50:26.000Z","updated_at":"2026-04-20T22:10:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ehmo/autoresearch-skill","commit_stats":null,"previous_names":["ehmo/autoresearch-skill"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ehmo/autoresearch-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fautoresearch-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fautoresearch-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fautoresearch-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fautoresearch-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmo","download_url":"https://codeload.github.com/ehmo/autoresearch-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fautoresearch-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33627948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-28T22:02:07.990Z","updated_at":"2026-05-28T22:02:08.546Z","avatar_url":"https://github.com/ehmo.png","language":"Shell","funding_links":[],"categories":["Full list"],"sub_categories":["Infra / Skills / Forks"],"readme":"# autoresearch\n\nAutonomous codebase improvement. Three independent teams run against your code in a loop: one finds problems, one fixes them, one simplifies what's left. Everything happens on a branch. Nothing touches main until you merge.\n\nCurrent skill version: **2.0.0** ([changelog](skills/autoresearch/CHANGELOG.md)). Run `/autoresearch version` to print the version of the installed skill.\n\n## Three modes\n\n- **narrow** — you have a measurable goal (p99 latency, coverage %, bundle size, lint count). You propose one or more angles and rank them. Autoresearch works angle 1 first, re-measures after every cycle, and stops when the target hits.\n- **broad** — you have an aspiration without a number. Autoresearch generates 3–5 diverse hypotheses — at minimum one obvious, one bold (challenges an assumption), and one creative (outside-the-box) — runs each on its own branch, and compares results to name a winner.\n- **sweep** (default) — general quality improvement: bug hunting, refactoring, coverage gaps. The original loop.\n\n## Where this came from\n\nAndrej Karpathy's [autoresearch](https://github.com/karpathy/autoresearch) showed that you can let an agent modify training code, run experiments, keep what works, and throw away what doesn't. You go to sleep, you wake up to a better model. [pi-autoresearch](https://github.com/davebcn87/pi-autoresearch) and [drivelineresearch/autoresearch-claude-code](https://github.com/drivelineresearch/autoresearch-claude-code) generalized this beyond ML to any codebase.\n\nThis project uses up to three teams with information barriers between them instead of a single agent. Each team starts from a clean context and only sees what the coordinator passes to it. The team fixing bugs doesn't know how they were found, and the team simplifying code doesn't know what was broken.\n\n## How a cycle works\n\nEach cycle runs three stages:\n\n1. The Red team reads the codebase and writes a findings report with file paths, line numbers, and descriptions of what's wrong. It doesn't modify anything. In narrow mode the Red team is scoped to the current angle; in broad mode it is scoped to the current hypothesis.\n\n2. The coordinator strips the analysis methodology from the findings and passes only the \"what and where\" to the Green team. The Green team fixes issues one at a time, running tests after each commit.\n\n3. The Refactor team gets the codebase in its current state with no context about what was found or fixed. It picks 3–5 simplifications, runs tests after each change.\n\nThe coordinator verifies tests, logs results, and starts the next cycle.\n\nIn narrow mode the coordinator re-measures the goal metric after each cycle and stops the whole session once the target is hit. In broad mode the coordinator runs all tracks sequentially (or in parallel if configured), then writes a comparison document and names a winner.\n\n## What to expect\n\nOn a 25K-line Go project, five cycles produced 49 commits on a feature branch: 31 bug fixes (8 breaking core functionality), 6 new test suites, 5 performance optimizations replacing N+1 query patterns, and about 100 lines of dead code removed.\n\nYour results will depend on the size, test coverage, and existing quality of the target project. Codebases with good test coverage get the most value since the Green team can verify its fixes. Projects with few tests will see the Red team flag missing coverage as a priority.\n\n## Install\n\n### Via `npx skills` (recommended)\n\nIf you have Node installed, install with one command — no cloning, no symlinks:\n\n```bash\nnpx skills add ehmo/autoresearch\n```\n\nThat's it. The CLI fetches the repo, discovers `skills/autoresearch/SKILL.md` from its frontmatter `name:` field, and installs it into the right directory for your agent. Works with Claude Code, Cursor, Codex, and other agents the `skills` CLI supports.\n\nInstall only the skill (no slash command) for a specific agent:\n\n```bash\nnpx skills add ehmo/autoresearch -a claude-code\n```\n\nUseful companion commands:\n\n```bash\nnpx skills list                    # show installed skills\nnpx skills update ehmo/autoresearch\nnpx skills remove ehmo/autoresearch\n```\n\n### Claude Code (manual install)\n\nIf you prefer a local clone and symlinks:\n\n```bash\ngit clone git@github.com:ehmo/autoresearch.git\ncd autoresearch\n./install.sh\n```\n\nCreates symlinks in `~/.claude/` for the skill and slash command. The script checks that Claude Code is installed first.\n\nTo use a non-default config directory, export `CLAUDE_DIR` before running:\n\n```bash\nexport CLAUDE_DIR=/custom/path\n./install.sh\n```\n\n### Codex\n\nAdd the contents of `agents/codex.md` to your project's AGENTS.md or equivalent instruction file.\n\n### Other agents\n\nThe full protocol is in `skills/autoresearch/SKILL.md`. It's plain markdown. Drop it into whatever instruction format your agent uses.\n\n## Usage\n\nNarrow mode (drive a specific metric):\n\n```\n/autoresearch narrow ~/path/to/project\n```\n\nYou'll be asked for a metric, a measurement command, a baseline, and a target. Then for one or more angles — and if you give more than one, you'll be asked to rank them 1, 2, 3 before cycles start.\n\nBroad mode (diverge and compare):\n\n```\n/autoresearch broad ~/path/to/project\n```\n\nYou'll be asked for an aspiration (\"make the CLI faster to use every day\"). The coordinator generates 3–5 diverse hypotheses, shows them to you for approval, then runs each on its own branch. At the end you get a comparison document and a winner.\n\nSweep mode (default, general quality):\n\n```\n/autoresearch ~/path/to/project\n```\n\nThe coordinator detects your stack, finds the test command, creates a branch, and starts running cycles. It asks for confirmation before modifying anything.\n\nResume after a break (mode is read from the session file):\n\n```\n/autoresearch resume\n/autoresearch resume myproject\n```\n\nCheck progress:\n\n```\n/autoresearch status\n```\n\n### Configuration\n\nCreate `.autoresearch.yml` in your project root to customize behavior:\n\n```yaml\n# Override auto-detected test command\ntest_command: \"make test-unit\"\n\n# Limit what the teams can see and modify\ninclude:\n  - \"src/\"\n  - \"lib/\"\nexclude:\n  - \"vendor/\"\n  - \"generated/\"\n\n# Stop after this many cycles (default: runs until diminishing returns)\nmax_cycles: 10\n\n# Skip the refactor stage\nteams:\n  - red\n  - green\n```\n\nWithout a config file, autoresearch detects everything automatically and runs all three teams.\n\n## How sessions are stored\n\nSession data lives in `sessions/\u003cproject-name\u003e/` within the autoresearch repo:\n\n```\nsessions/myproject/\n  session.md        # What's been done, what's left to try\n  results.tsv       # One row per team per cycle\n  ideas.md          # Findings deferred for later cycles\n  cycles/\n    001/\n      red-findings.md\n      green-patch.md\n      refactor-patch.md\n      eval-results.md\n```\n\nThe `sessions/` directory is gitignored.\n\n## Requirements\n\n- An AI coding agent with sub-agent support for full clean-room separation (Claude Code), or a single-agent setup with reduced separation (Codex, others)\n- Git\n- A test suite that exits non-zero on failure\n\nStack detection covers Go, Node/TypeScript, Rust, Python, Java/Kotlin, Ruby, PHP, Elixir, and anything with a Makefile.\n\n## Limitations\n\nWorks best on projects with decent test coverage. Without tests, the Green team has no way to verify its fixes don't break things.\n\nLarge monorepos benefit from the `include`/`exclude` config to keep the teams focused on relevant code.\n\nThe information barriers between teams are enforced by sub-agent context separation, not cryptography. Each sub-agent starts fresh with only the information the coordinator passes to it.\n\nNot tested on Windows outside of WSL. The install script uses symlinks which require elevated permissions on native Windows.\n\n## Uninstall\n\n```bash\n./uninstall.sh\n```\n\nRemoves symlinks from `~/.claude/`. Session data in `sessions/` is kept.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmo%2Fautoresearch-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmo%2Fautoresearch-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmo%2Fautoresearch-skill/lists"}