EVIDRA DOCUMENTATION

From open question
to defensible result.

Evidra is a TypeScript research and experimentation harness. The model proposes. The controller records, executes, evaluates, and knows when the evidence is not enough.

Quick start

Requirements: Node.js 22.19 or newer, Git, and an authenticated Codex CLI or a local Ollama model.

$ git clone https://github.com/StarAtNyte/evidra.git
$ cd evidra
$ nvm install 22 && nvm use 22
$ npm install && npm run build && npm link
$ evidra

Inside the TUI, authenticate, choose a model, and start a campaign:

› /login codex
› /model
› /thinking medium
› /research start

Ordinary messages remain ordinary conversation. Research autonomy begins only when you run /research start or /challenge start.

Mental model

Evidra separates model judgment from system truth. Agents explore possibilities; the controller owns the durable state and enforces the rules that make a result worth trusting.

PROJECTDurable SQLite state, event log, sources, claims, hypotheses, decisions, experiments, and artifacts.

CAMPAIGNAn objective with an explicit budget, phase goals, stopping condition, and resumable checkpoints.

LANEAn independent research direction with its own context, worktree, and evidence trail.

EXPERIMENTA reproducible manifest with a declared change, executor, metric or outcome, artifacts, and validation contract.

PROMOTIONA result is accepted only when the configured evidence, integrity, replication, and evaluation gates pass.

Command surface

The TUI is the primary interface. Type / for live suggestions and press Tab to autocomplete. Shell commands are available explicitly with !.

/research startDefine or resume a research campaign and run autonomous cycles.

/challenge startSwitch to Challenge mode and run a challenge campaign in the active workspace.

/statusShow project, phase, campaign, queue, executor, and evidence state.

/modelChoose from the models available through the active provider.

/thinkingSelect reasoning effort for the active route.

/permissionsChoose safe, fast, or YOLO execution policy for the current terminal session.

/computeChoose local, container, or Modal experiment execution.

/usageInspect token, time, GPU reservation, and provider-limit state.

/resumeContinue a saved session or campaign from its latest valid checkpoint.

!commandRun an explicit terminal command through the permission boundary.

Research campaigns

Use research mode for scientific questions, algorithm design, literature synthesis, software investigations, or any problem where the outcome needs evidence rather than a single answer.

1. Set the objective

Evidra asks for the ultimate goal, success condition, budget, execution route, and constraints. It then derives internal phase goals automatically.

2. Build the evidence base

The director inspects the workspace, gathers bounded primary sources, extracts claims with provenance, and turns promising ideas into falsifiable hypotheses.

3. Explore in parallel

Independent lanes investigate different mechanisms. Later lanes receive a compact cross-pollination board rather than a shared mutable transcript.

4. Run and validate

Experiments run in isolated worktrees with manifests, logs, checksums, environment snapshots, and declared outcomes. Failed ideas remain useful negative evidence.

5. Continue until justified

Phase gates, replication requirements, statistical comparisons, and evidence audits determine whether the campaign advances, replans, pauses, or completes.

Challenge campaigns

Challenge mode uses the same research engine for repositories with a measurable evaluator, competition contract, benchmark, or external score.

The first included adapter is WhestBench, but the harness is not tied to Kaggle or ML. A challenge can define any evaluator, metric, artifact, proof, behavior, or system property.

› /challenge start
› /compute modal
› /permissions safe

Evidra protects evaluator/configuration files, compares candidates against a best-so-far ratchet, records external scores with provenance, and refuses to promote results that fail reproducibility or integrity gates.

Execution backends

Keep the controller where you work and choose where heavy experiments happen.

LOCALFast iteration in the current workspace. Best for inspection, lightweight experiments, and debugging.

CONTAINERIsolated Docker or Podman worktree with a minimal environment and network disabled by default.

MODALRemote CPU/GPU workers with streamed logs, declared artifacts, resource reservations, and the same local evidence gates.

MODAL CONTROLLERRun the headless controller itself in Modal for unattended campaigns with durable Volume-backed state.

$ EVIDRA_MODAL_WORKSPACE="$PWD" modal run modal_controller.py::run \
  --goal "maximize robust validation performance" \
  --budget 4h --mode research --executor modal --autonomy fast

Safety and control

Permission level is scoped to the current terminal session and is never silently carried into a new session.

SAFERead-only inspection and bounded, non-destructive operations. Best default.

FASTBroader autonomous execution with bounded concurrency and the same hard external-submission veto.

YOLOMaximum local automation after an explicit operator choice. Destructive and external actions still require their configured gates.

Press Escape to interrupt an active process and stop its child workers. Send guidance while work is running; Evidra steers at the next safe tool boundary without launching a concurrent second agent.

Long-running work

Campaigns are designed to survive the things that normally break agent workflows: lost terminals, provider limits, worker crashes, and partial progress.

Every cycle checkpoints phase, lane, director, critic, execution, and completion state.
Heartbeat and lease recovery prevents duplicate controllers and marks dead work retryable.
Provider exhaustion can wait durably for reset or move to an explicitly configured route.
Retries are bounded and must change the route, model, executor, or search operator after an unchanged failure.
Saved sessions can be resumed without carrying permissions or stale active processes across terminal sessions.

Read the full operational contract in docs/codex-operations.md ↗.

From open questionto defensible result.