How AutoResearch Handles Long-Horizon Research Tasks with Project-Local State in DeepSeek-Reasonix

AutoResearch upgrades standard /goal commands into durable research workflows by creating isolated project-local state directories under .reasonix/autoresearch/ that capture the entire research lifecycle without mutating global project files.

AutoResearch is the runtime strategy that DeepSeek-Reasonix activates when detecting long-horizon research, debugging, optimization, or implementation tasks. The system creates persistent, collision-resistant task directories that isolate mutable research state from your repository's main project files, ensuring that extended autonomous operations remain transparent and reversible.

Detecting AutoResearch Signals and Upgrading Goals

The AutoResearch workflow initiates when the host detects specific trigger phrases or explicit path signals. According to internal/control/input.go (lines 209–211), the system recognizes cues like "keep researching", "debug until the root cause is clear", or explicit paths matching .reasonix/autoresearch/….

When detected, the controller upgrades the ordinary /goal command by inserting the --research flag (or equivalent --auto-research/--deep flags). This upgrade modifies the Goal struct defined in internal/control/goal.go (lines 37–58), which stores a ResearchMode boolean flag alongside the task ID and path.

// Triggering AutoResearch from the host UI or CLI
fmt.Println("/goal --research investigate memory-leak in cache layer")

Project-Local State Directory Structure

Upon activation, AutoResearch creates a dedicated workspace under:

.reasonix/autoresearch/YYYYMMDD-HHMMSS-slug/

The task identifier combines a timestamp with a slug derived from the goal text. If a collision occurs, the system appends "-2", "-3", and so forth until finding a unique name. Users can override this by providing the full .reasonix/autoresearch/<task-id>/ path.

Inside this directory, the controller writes five state files that constitute the only mutable research state:

• task_spec.md – Original research objective and user constraints
• progress.json – Current step, sub-tasks, and completion percentage
• findings.jsonl – Individual information gathered from code, web, or tools
• directions_tried.json – Explored directions that were discarded
• iteration_log.jsonl – Chronological record of each reasoning and tool-call iteration

# Directory structure created by the controller

$ tree .reasonix/autoresearch/20231112-154830-investigate-memory-leak
.reasonix/autoresearch/20231112-154830-investigate-memory-leak/
├── task_spec.md
├── progress.json
├── findings.jsonl
├── directions_tried.json
└── iteration_log.jsonl

State Isolation and Lifecycle Enforcement

The controller enforces strict state isolation by ensuring that REASONIX.md, AGENTS.md, and system prompts remain read-only during research operations. This prevents pollution of the global prompt cache and keeps long-running tasks sandboxed.

According to internal/control/controller.go (lines 494–567), the system monitors for stale iterations—situations where directions are tried repeatedly without progress—and can automatically pivot to new structural approaches. Completion validation occurs by auditing whether the evidence recorded in findings.jsonl satisfies the original objective stated in task_spec.md.

Security Boundaries and Tool Permissions

Despite running as an autonomous loop, AutoResearch maintains strict security gates. As implemented in internal/skill/builtins.go, the research sub-agent operates with a read-only toolset by default:

const builtinResearchBody = `You are running as a research subagent. Gather information from code AND the web, synthesize it, and return one focused conclusion.
The 'task' the parent gave you is the research question. Stay on it.`

Any tool performing public, destructive, or credentialed actions must pass through standard approval, privacy, and caching gates. Write-capable tools require explicit user authorization.

Core Implementation Modules

The AutoResearch flow spans four critical modules:

1. internal/control/input.go – Detects AutoResearch signals and builds the instruction block announcing the workspace creation
2. internal/control/goal.go – Stores the ResearchMode flag and task identification
3. internal/control/controller.go – Orchestrates the planning/execution loop, writes state files, and handles pivot logic
4. internal/skill/builtins.go – Declares the research sub-agent tool and enforces read-only policies

Documentation references in site/src/pages/docs.astro (line 191) and docs/GUIDE.md (line 335) provide user-facing semantics and directory layout specifications.

Summary

• AutoResearch activates when the host detects long-horizon task signals or explicit --research flags, upgrading standard goals into durable research workflows.
• Project-local state resides in timestamped directories under .reasonix/autoresearch/, containing five JSON/Markdown files that track the complete research lifecycle.
• Isolation guarantees ensure that only the task directory mutates, leaving global project files untouched and preventing cache pollution.
• Security controls restrict the research sub-agent to read-only operations unless explicitly authorized, with all destructive actions requiring approval gates.
• Lifecycle management includes automatic pivot detection for stale iterations and completion auditing against recorded findings.

Frequently Asked Questions

What triggers AutoResearch mode in DeepSeek-Reasonix?

AutoResearch triggers when the system detects specific user phrases like "keep researching" or "debug until the root cause is clear", or when the user provides an explicit path to .reasonix/autoresearch/. The detection logic in internal/control/input.go (lines 209–211) upgrades these signals into research goals by appending the --research flag.

Where does AutoResearch store its state?

AutoResearch stores all mutable state in a dedicated directory under .reasonix/autoresearch/YYYYMMDD-HHMMSS-slug/. This location contains five state files—task_spec.md, progress.json, findings.jsonl, directions_tried.json, and iteration_log.jsonl—that capture the complete research lifecycle while isolating changes from your main repository files.

How does AutoResearch handle multiple attempts at the same task?

When creating a task directory, AutoResearch generates a collision-resistant ID from the timestamp and goal slug. If a directory with that ID already exists, the system automatically appends "-2", "-3", and so on until finding a unique name. Alternatively, users can force a specific ID by providing the full .reasonix/autoresearch/<task-id>/ path upfront.

Is AutoResearch safe to run autonomously?

Yes, AutoResearch implements security gating that restricts the research sub-agent to read-only toolsets by default, as defined in internal/skill/builtins.go. Any public, destructive, or credentialed actions still require passing through standard approval gates. The system only enables write-capable tools when explicitly authorized by the user.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}