Miraji

Autoresearch for Amp and OpenCode — an agent-driven experiment loop with JSONL persistence, jj keep/discard, and deterministic resumability.

Run iterative experiments to improve a measurable metric. Each iteration: make one code change, run a benchmark, keep good results as jj commits, discard bad ones automatically.

Install

Clone the repo and run the installer:

git clone https://github.com/your-org/miraji.git
cd miraji
bun install

Then install into the project where you want to run autoresearch:

# From the miraji directory, symlink the CLI to your PATH:
ln -sf "$PWD/bin/miraji-install" ~/.local/bin/miraji-install

# Now from any project:
cd /path/to/your-project
miraji-install
# or globally:
miraji-install --global

Usage

OpenCode

Start a research session with the /autoresearch command:

/autoresearch improve parser speed by 20%

The agent will:

1. Create autoresearch.md (session notes) and autoresearch.sh (benchmark script)
2. Call autoresearch_init to initialize the experiment
3. Iterate: make a change → autoresearch_run → autoresearch_log
4. Keep improvements as jj commits, discard regressions

Amp

Enable autoresearch from the command palette:

autoresearch: start

Enter your goal when prompted. The agent follows the same loop using init_experiment, run_experiment, and log_experiment tools.

Manual

Import the core in your own code:

import { initExperiment, runExperiment, logExperiment, renderStatus } from "miraji"

const state = await initExperiment(workDir, {
  name: "optimize-latency",
  metricName: "latency_ms",
  metricUnit: "ms",
  direction: "minimize",
})

const result = await runExperiment({ workDir, command: "bash autoresearch.sh" })

const log = await logExperiment(workDir, {
  status: result.metric < 100 ? "keep" : "discard",
  metric: result.metric!,
  metrics: result.metrics,
})

console.log(renderStatus(log.state))

Project files

File	Purpose
autoresearch.jsonl	Append-only source of truth (config + run entries)
autoresearch.md	Session notes and observations
autoresearch.ideas.md	Hypotheses to try later
autoresearch.sh	Executable benchmark — prints METRIC name=value
autoresearch.checks.sh	Optional correctness checks
autoresearch.config.json	Optional config: maxIterations, timeoutSeconds, etc.
autoresearch.hooks/before.sh	Optional pre-iteration hook
autoresearch.hooks/after.sh	Optional post-iteration hook

Configuration

Create autoresearch.config.json in your project root:

{
  "maxIterations": 10,
  "timeoutSeconds": 120,
  "autoResume": true
}

Requirements

• jj (required for keep/discard)
• bash, node, bun