night-owl-research-agent

NORA (Night Owl Research Agent)

A fully automatic, domain-aware AI research agent for Geoscientists, Remote Sensing researchers, and GIScientists — powered entirely by Claude Code skills.

Quick Start

NORA runs inside Claude Code. There is no Python entry point, no server to spin up, and no build step — you just drop the skills into Claude Code's skill directory and invoke the launcher.

Step 1 — Install Claude Code

Install Claude Code first. Any of the official distributions works:

• CLI (recommended):

  npm install -g @anthropic-ai/claude-code
  claude --version
  

• Desktop app (macOS / Windows): download from https://claude.com/claude-code
• VS Code extension: install "Claude Code" from the Marketplace
• Web: https://claude.ai/code

Sign in once with your Anthropic account so Claude Code can reach the API.

Step 2 — Get NORA onto your machine

git clone https://github.com/GRIND-Lab-Core/night_owl_research_agent.git
cd night_owl_research_agent

Step 3 — Install the skills into Claude Code

Claude Code looks for skills under ~/.claude/skills/ (user-level, available in every project) or <project>/.claude/skills/ (project-local). Copy the entire skills/ folder from this repo into one of those locations.

macOS / Linux (user-level — recommended):

mkdir -p ~/.claude/skills
cp -R skills/* ~/.claude/skills/

Windows PowerShell (user-level):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse -Force .\skills\* "$env:USERPROFILE\.claude\skills\"

Windows bash / Git Bash:

mkdir -p "$USERPROFILE/.claude/skills"
cp -R skills/* "$USERPROFILE/.claude/skills/"

Project-local alternative (skills only visible when Claude Code is opened in this folder):

mkdir -p .claude/skills
cp -R skills/* .claude/skills/

Also copy the launcher slash command so /launcher is available:

# macOS / Linux
mkdir -p ~/.claude/commands
cp .claude/commands/launcher.md ~/.claude/commands/

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\commands" | Out-Null
Copy-Item -Force .\.claude\commands\launcher.md "$env:USERPROFILE\.claude\commands\"

Verify the install — open Claude Code and run:

/skills

You should see the NORA skills (full-pipeline, lit-review, idea-discovery-pipeline, deploy-experiment, paper-draft, …) listed.

Step 4 — Start a research session

Open the night_owl_research_agent folder in Claude Code (this gives NORA access to CLAUDE.md, RESEARCH_PLAN.md, output/, memory/, and tools/), then pick one of the two entry points:

Option A — interactive launcher (best for first-time users):

/launcher

The launcher walks you through a short questionnaire — research topic, stage to start from, control flags (AUTO_PROCEED, HUMAN_CHECKPOINT, COMPACT_MODE, REVIEWER_DIFFICULTY) — and routes to the correct skill.

Option B — end-to-end pipeline (best when you already know what you want to run):

Skill: full-pipeline
"Your research direction here, e.g. 'urban soundscape inequality via street-view + audio foundation models'"

or, if you prefer a slash-style invocation:

/full-pipeline "your research direction"

full-pipeline chains all four stages: idea-discovery-pipeline → deploy-experiment → auto-review-loop → generate-report and then hands off to paper-writing-pipeline for the manuscript.

Tip: for reproducibility, fill in RESEARCH_PLAN.md (or BRIEF.md) in the project root before launching. When either file is present, skills read it as the authoritative brief and ignore conflicting $ARGUMENTS.

Step 5 — (Optional) Enable extras

• MCP servers — edit .mcp.json and register with Claude Code (/mcp inside the chat) to enable filesystem, fetch, arxiv_mcp, geo_mcp, github, and brave_search. See mcp/README_MCP.md.
• Hooks — settings.json wires harness/hooks/*.sh into Claude Code's lifecycle (writes handoff.json on session end, validates tool use, sends desktop notifications). On Windows, run the hook scripts via Git Bash or WSL.
• W&B — if your experiments use Weights & Biases, run wandb login once on the host where deploy-experiment will launch training.
• API keys — set ANTHROPIC_API_KEY (for Claude Code), plus any optional keys you want to use (SEMANTIC_SCHOLAR_API_KEY, GITHUB_TOKEN, BRAVE_API_KEY).

Prerequisites summary

What It Does

NORA automates the complete academic research lifecycle using Claude Code skills — Markdown-defined workflows that Claude reads and executes, selecting appropriate tools and methods based on context.

1. Literature review — searches ArXiv, Semantic Scholar, local papers, Zotero, and Obsidian; synthesizes findings and identifies ranked research gaps.
2. Idea discovery — generates 8–12 research ideas from literature gaps, validates novelty via multi-source search + external reviewer, and pilot-tests the top candidates. Pilots run a mandatory local-GPU presence check first (nvidia-smi → CUDA, then MPS, then none); when a local GPU is detected, every pilot launches on it instead of silently falling back to CPU or remote.
3. Method refinement — iteratively refines vague research directions into problem-anchored, implementation-ready proposals via adversarial review (up to 5 rounds, score ≥ 9 target).
4. Experiment design & execution — produces claim-driven experiment roadmaps and deploys to local, remote SSH, or Modal serverless GPU (Track A), or runs spatial/GIScience methods on CPU (Track B), or both for mixed GeoAI. The same mandatory local-GPU check runs at Step 0 of deploy-experiment so any ML/DL workload (pilot or full) executes on the local GPU when present.
5. Data acquisition — discovers, evaluates, downloads, validates, and documents datasets from government portals, APIs, cloud archives, and open repositories with full provenance.
6. Spatial analysis — guideline-driven: classifies the analytical objective, runs ESDA, and applies geospatial diagnostics conditionally on the research question. MAUP discussion, GWR/MGWR, residual Moran's I, alternative spatial weights, and spatial CV are triggered only when the claim depends on them; when in doubt the skill pauses for a human checkpoint instead of running heavyweight checks (or skipping reviewer-expected ones) by reflex.
7. Adversarial review — up to 4 rounds of generator–evaluator-separated review with per-criterion hard floors; medium / hard / nightmare reviewer modes via Codex MCP, codex exec, or a Claude subagent. Domain personas (giscience, remote-sensing, spatial-data-science) apply geo-specific must-checks only where the paper's claims actually depend on them instead of penalizing every paper for missing MAUP / GWR discussion.
8. Report + paper writing — consolidates every pipeline artifact into output/NARRATIVE_REPORT.md, then runs paper-writing-pipeline to produce a journal-ready manuscript (Markdown → LaTeX → PDF/DOCX) with journal-specific profiles for IJGIS, IEEE TGRS, ISPRS JPRS, RSE, AAG, TGIS, and more.

Architecture

NORA is a skills-first system. All research logic lives in Markdown skill files that Claude reads and executes.

Skills describe workflow logic in Markdown. Claude reads a skill to understand the workflow, then decides the exact sequence of actions based on context — the skill provides guidelines and decision frameworks, not rigid procedures.

You (or /launcher)
    ↓ invokes
Skill SKILL.md  ←─── reads domain knowledge from skills/knowledge/
    ↓ Claude decides what to do
CLI tools (tools/arxiv_fetch.py, etc.) + inline Python + MCP servers as needed
    ↓ produce
Output files (reports, paper-cache, figures, manuscript)
    ↓ read by
Next skill in pipeline

The single installed slash command is /launcher. Every other skill is invoked by name (Claude Code's native Skill tool) or by being called internally from another skill.

Skills

23 workflow skills in skills/ plus domain knowledge in skills/knowledge/. Each skill is a self-contained Markdown workflow file.

Workflow Skills

Domain Knowledge

Control Flags

Edit CLAUDE.md before starting a long run: