AutoResearch

AutoResearch is one of NeuriCo's three research modes. It turns an initial scored experiment into an iterative improvement loop. Each iteration proposes one change, runs it, scores it against a sealed evaluation protocol, and keeps the change only when it improves the current best result.

Fresh, continue, and bootstrap are entry paths within AutoResearch, not separate user-facing research modes.

Start AutoResearch

The following example creates a scored baseline and runs three improvement iterations:

Docker	Local uv
./neurico run <idea_id> --provider claude --no-github --full-permissions --autoresearch --autoresearch-iterations 3	uv run python src/core/runner.py <idea_id> --provider claude --no-github --full-permissions --autoresearch --autoresearch-iterations 3

Omit --no-github when the idea has a configured GitHub repository. Replace claude with codex or gemini after authenticating that provider.

Continue AutoResearch

Continue from a workspace that already contains a scored best result:

Docker	Local uv
./neurico run <idea_id> --provider claude --no-github --full-permissions --continue-autoresearch --autoresearch-iterations 3	uv run python src/core/runner.py <idea_id> --provider claude --no-github --full-permissions --continue-autoresearch --autoresearch-iterations 3

The existing workspace must have complete scoring files, a valid Git HEAD, and no uncommitted changes. If an interrupted AutoResearch attempt left the workspace dirty, add --continue-recover. This restores the current best checkpoint, discards the incomplete attempt, and continues:

Docker	Local uv
./neurico run <idea_id> --provider claude --no-github --full-permissions --continue-autoresearch --continue-recover --autoresearch-iterations 3	uv run python src/core/runner.py <idea_id> --provider claude --no-github --full-permissions --continue-autoresearch --continue-recover --autoresearch-iterations 3

Bootstrap an existing workspace

Bootstrap is for a workspace where Standard research already produced useful outputs but no scored AutoResearch baseline exists. The baseline command curates the existing workspace manifest, constructs the scoring contract, scores the current implementation, creates the best checkpoint, and writes AutoResearch continuation state. It does not run improvement iterations.

# Docker: create the continuation-ready baseline
./neurico run <idea_id> --provider claude --no-github \
  --bootstrap-autoresearch-baseline

# Docker: then run improvements
./neurico run <idea_id> --provider claude --no-github \
  --continue-autoresearch --autoresearch-iterations 3

# Local uv: create the continuation-ready baseline
uv run python src/core/runner.py <idea_id> --provider claude --no-github \
  --bootstrap-autoresearch-baseline

# Local uv: then run improvements
uv run python src/core/runner.py <idea_id> --provider claude --no-github \
  --continue-autoresearch --autoresearch-iterations 3

The lower-level --bootstrap-rule-maker flag retrofits a scoring protocol and runs the scorer, but it is not the preferred entrypoint when the goal is a continuation-ready AutoResearch baseline.

How the loop works

flowchart TD
    A[Submitted idea] --> RF[Resource finder]
    RF --> RM[Rule maker creates sealed scoring protocol]
    RM --> ER[Initial experiment]
    ER --> SC[Score baseline]
    SC --> BEST[(Current best checkpoint)]
    BEST --> P[Propose one change]
    P --> RUN[Run candidate experiment]
    RUN --> SCORE[Score candidate]
    SCORE --> CMP{Improves current best?}
    CMP -->|yes| ACCEPT[Accept new best]
    CMP -->|no| REJECT[Restore previous best]
    ACCEPT --> P
    REJECT --> P

One iteration performs these steps:

1. Restore the current best checkpoint.
2. Write one proposed change to the attempt's proposal.md.
3. Apply the proposal and run the candidate experiment.
4. Execute the sealed evaluator and write candidate results.
5. Compare the candidate against the current best.
6. Accept the candidate as the new best or restore the previous best.

The workspace Git HEAD always represents the current best accepted result. Rejected attempts remain available in the history directory for review.

Main flags

Flag	Type / default	Description
--autoresearch	switch	Create the scored baseline, then enter the AutoResearch loop
--continue-autoresearch	switch	Resume from an existing scored best workspace
--bootstrap-autoresearch-baseline	switch	Convert an existing unscored workspace into a continuation-ready baseline
--continue-recover	switch	Restore the best checkpoint before continuing an interrupted run
--autoresearch-iterations N	integer, default 1	Number of improvement iterations
--autoresearch-history-dir PATH	path, default logs/experiment-autoresearch	Attempt-history location
--proposer-timeout SECONDS	integer, default 900	Timeout for proposal generation
--rule-maker-timeout SECONDS	integer, default 1800	Timeout for scoring-contract construction
--scorer-timeout SECONDS	integer, default 600	Timeout for scoring
--manifest-trimmer-timeout SECONDS	integer, default 300	Timeout per manifest-trimmer call during bootstrap
--bootstrap-rule-maker	switch	Lower-level scoring-only retrofit for an existing workspace

--autoresearch, --continue-autoresearch, and --bootstrap-autoresearch-baseline are mutually exclusive entry paths.

Outputs

• Current best score: scoring/results.json.
• Current best implementation: the workspace Git HEAD.
• Attempt history: logs/experiment-autoresearch/<parent_sha>/attempt-<n>/.
• Per-attempt artifacts: proposal, results, and accept/reject decision.
• Optional paper: paper_draft/ when --write-paper is enabled.

For human-guided iterative research, use HITL AutoResearch instead. See HITL_AUTORESEARCH.md.