autoresearch

Executes a repeating cycle of code modification → git commit → mechanical verification → decision logic → result logging that continues until user interruption or iteration limit. The system uses a constraint triangle (scope glob patterns, single mechanical metric, shell verify command) to enable autonomous operation without subjective judgment. Git serves as both memory and causality tracker, with automatic rollback on verification failure.

Converts plain-language goals into structured autoresearch configurations via a 7-phase guided workflow. The wizard validates scope constraints, suggests mechanical metrics from a database of domain-specific examples, and generates shell verify commands. Each phase includes validation gates that ensure the configuration is executable before iteration begins.

Restricts code modifications to files matching user-defined glob patterns (e.g., src/**/*.ts, test/**/*.test.ts). The system validates scope during setup, ensures Claude only modifies in-scope files, and logs scope violations as errors. Scope constraints enable the agent to load full context into memory without overwhelming token limits and prevent unintended modifications to configuration, documentation, or other sensitive files.

Implements strategies for recovering from iteration failures (e.g., verify command timeout, git rollback failure, metric extraction error). The system logs errors with full context (iteration number, command output, stack trace), automatically rolls back failed iterations, and continues to the next iteration. For unrecoverable errors (e.g., git corruption), the system halts and logs detailed diagnostics to enable manual recovery.

Executes autonomous security testing via an adversarial iteration loop that applies STRIDE threat modeling and OWASP vulnerability patterns. Each iteration generates adversarial test cases, runs them against the codebase, and logs security findings. The loop uses a threat model as the constraint and vulnerability count as the mechanical metric, enabling autonomous security hardening.

Uses Git commits as the primary memory mechanism, storing one commit per iteration with Claude's modification summary in the commit message. Each commit is tagged with iteration metadata (metric value, timestamp, decision status). On verification failure, the system automatically reverts to the previous commit, preserving causality and enabling crash recovery. The git log serves as a queryable audit trail of all attempted improvements.

Executes a user-provided shell command to extract a single numeric metric from test output, build logs, or custom scripts. The metric is parsed deterministically (e.g., grep for percentage, regex for latency value) and compared against the previous iteration to decide Keep/Discard. The system validates metric extraction during setup and caches baseline measurements to enable fast iteration-to-iteration comparisons.

Supports two iteration strategies: bounded mode (run exactly N iterations, then stop) and unbounded mode (run until user interruption). Bounded mode is useful for exploration with a fixed budget; unbounded mode enables continuous improvement until diminishing returns. The system tracks iteration count, elapsed time, and metric trajectory to inform stopping decisions.

Implements explicit decision logic that compares the current iteration's metric against the previous best metric and decides to Keep (commit and continue), Discard (rollback and continue), or Crash (halt on unrecoverable error). Keep decisions are based on metric improvement; Discard decisions trigger automatic git rollback; Crash decisions log the error and stop iteration. The decision logic is deterministic and transparent, enabling users to understand why each iteration was accepted or rejected.

Logs all iteration results to autoresearch-results.tsv in a tab-separated format with columns for iteration number, timestamp, metric value, git commit hash, decision status, and error message. The TSV format enables easy parsing and analysis; users can query iteration history to identify patterns (e.g., which types of changes improved the metric). Summary reports aggregate results across iterations and compute statistics (total improvement, iterations to convergence, etc.).

Integrates with Model Context Protocol (MCP) servers to enable Claude to call external tools and services during iteration. The system can invoke MCP-exposed functions (e.g., custom linters, external APIs, specialized test runners) as part of the verify command or modification process. MCP integration enables autoresearch to work with heterogeneous toolchains without embedding tool-specific logic.

Executes user-provided shell commands to verify improvements and extract metrics. The system handles command failures gracefully (logs error, triggers Discard decision), captures stdout/stderr, and parses metric values using regex or custom extraction logic. Verification commands can be arbitrarily complex (e.g., multi-step build + test + benchmark pipelines) as long as they output a parseable metric.