Skip to content
Back to search

night_owl_research_agent

Fully automatic AI research agent for Geoscientists, Remote Sensing researchers, and GIScientists. Features harness engineering, GeoBenchmark (OLS/GWR/MGWR), journal templates, and MCP servers.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/grind-lab-core--night-owl-research-agent/badge.svg)](/listings/grind-lab-core--night-owl-research-agent)

HTML

<a href="/listings/grind-lab-core--night-owl-research-agent"><img src="/api/listings/grind-lab-core--night-owl-research-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 494 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # NORA (Night Owl Research Agent)
  2. > A fully automatic, domain-aware AI research agent for Geoscientists, Remote Sensing researchers, and GIScientists — powered entirely by Claude Code skills.
  3. ![NORA Banner](res/NORA_Banner.png)
  4. ---
  5. ## Quick Start
  6. 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.
  7. ### Step 1 — Install Claude Code
  8. Install Claude Code first. Any of the official distributions works:
  9. - **CLI** (recommended):
  10. ```bash
  11. npm install -g @anthropic-ai/claude-code
  12. claude --version
  13. ```
  14. - **Desktop app** (macOS / Windows): download from <https://claude.com/claude-code>
  15. - **VS Code extension**: install "Claude Code" from the Marketplace
  16. - **Web**: <https://claude.ai/code>
  17. Sign in once with your Anthropic account so Claude Code can reach the API.
  18. ### Step 2 — Get NORA onto your machine
  19. ```bash
  20. git clone https://github.com/GRIND-Lab-Core/night_owl_research_agent.git
  21. cd night_owl_research_agent
  22. ```
  23. ### Step 3 — Install the skills into Claude Code
  24. 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.**
  25. **macOS / Linux (user-level — recommended):**
  26. ```bash
  27. mkdir -p ~/.claude/skills
  28. cp -R skills/* ~/.claude/skills/
  29. ```
  30. **Windows PowerShell (user-level):**
  31. ```powershell
  32. New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" | Out-Null
  33. Copy-Item -Recurse -Force .\skills\* "$env:USERPROFILE\.claude\skills\"
  34. ```
  35. **Windows bash / Git Bash:**
  36. ```bash
  37. mkdir -p "$USERPROFILE/.claude/skills"
  38. cp -R skills/* "$USERPROFILE/.claude/skills/"
  39. ```
  40. **Project-local alternative** (skills only visible when Claude Code is opened in this folder):
  41. ```bash
  42. mkdir -p .claude/skills
  43. cp -R skills/* .claude/skills/
  44. ```
  45. Also copy the launcher slash command so `/launcher` is available:
  46. ```bash
  47. # macOS / Linux
  48. mkdir -p ~/.claude/commands
  49. cp .claude/commands/launcher.md ~/.claude/commands/
  50. ```
  51. ```powershell
  52. # Windows PowerShell
  53. New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\commands" | Out-Null
  54. Copy-Item -Force .\.claude\commands\launcher.md "$env:USERPROFILE\.claude\commands\"
  55. ```
  56. Verify the install — open Claude Code and run:
  57. ```
  58. /skills
  59. ```
  60. You should see the NORA skills (`full-pipeline`, `lit-review`, `idea-discovery-pipeline`, `deploy-experiment`, `paper-draft`, …) listed.
  61. ### Step 4 — Start a research session
  62. 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:
  63. **Option A — interactive launcher** (best for first-time users):
  64. ```
  65. /launcher
  66. ```
  67. 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.
  68. **Option B — end-to-end pipeline** (best when you already know what you want to run):
  69. ```
  70. Skill: full-pipeline
  71. "Your research direction here, e.g. 'urban soundscape inequality via street-view + audio foundation models'"
  72. ```
  73. or, if you prefer a slash-style invocation:
  74. ```
  75. /full-pipeline "your research direction"
  76. ```
  77. `full-pipeline` chains all four stages:
  78. `idea-discovery-pipeline → deploy-experiment → auto-review-loop → generate-report`
  79. and then hands off to `paper-writing-pipeline` for the manuscript.
  80. **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`.
  81. ### Step 5 — (Optional) Enable extras
  82. - **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`.
  83. - **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.
  84. - **W&B** — if your experiments use Weights & Biases, run `wandb login` once on the host where `deploy-experiment` will launch training.
  85. - **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`).
  86. ### Prerequisites summary
  87. | Requirement | Why |
  88. |---|---|
  89. | Claude Code (CLI / desktop / web / VS Code) | Runtime for skills |
  90. | Anthropic account + API credit | Powers the agent |
  91. | Python 3.10+ with `pip install arxiv requests` | `tools/arxiv_fetch.py`, `tools/semantic_scholar_fetch.py` |
  92. | Conda env with `geopandas, pysal, libpysal, esda, spreg, mgwr, rasterio, xarray` | Track B (spatial) experiments |
  93. | CUDA GPU (local / remote SSH / Modal) | Track A (deep-learning) experiments — optional |
  94. ---
  95. ## What It Does
  96. 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.
  97. 1. **Literature review** — searches ArXiv, Semantic Scholar, local papers, Zotero, and Obsidian; synthesizes findings and identifies ranked research gaps.
  98. 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.
  99. 3. **Method refinement** — iteratively refines vague research directions into problem-anchored, implementation-ready proposals via adversarial review (up to 5 rounds, score ≥ 9 target).
  100. 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.
  101. 5. **Data acquisition** — discovers, evaluates, downloads, validates, and documents datasets from government portals, APIs, cloud archives, and open repositories with full provenance.
  102. 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.
  103. 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.
  104. 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.
  105. ---
  106. ## Architecture
  107. NORA is a **skills-first** system. All research logic lives in Markdown skill files that Claude reads and executes.
  108. ![NORA Architecture](res/nora_architecture.png)
  109. 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.
  110. ```
  111. You (or /launcher)
  112. ↓ invokes
  113. Skill SKILL.md ←─── reads domain knowledge from skills/knowledge/
  114. ↓ Claude decides what to do
  115. CLI tools (tools/arxiv_fetch.py, etc.) + inline Python + MCP servers as needed
  116. ↓ produce
  117. Output files (reports, paper-cache, figures, manuscript)
  118. ↓ read by
  119. Next skill in pipeline
  120. ```
  121. 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.
  122. ---
  123. ## Skills
  124. **23 workflow skills** in `skills/` plus domain knowledge in `skills/knowledge/`. Each skill is a self-contained Markdown workflow file.
  125. ### Workflow Skills
  126. | Skill | What it does |
  127. |---|---|
  128. | `full-pipeline` | Master pipeline: idea discovery → experiment → review → report → paper |
  129. | `lit-review` | Search + synthesize + gap analysis (ArXiv, Semantic Scholar, local papers, Zotero, Obsidian) |
  130. | `idea-discovery-pipeline` | Full idea pipeline: lit-review → generate-idea → novelty-check → idea-review → experiment-design-pipeline |
  131. | `generate-idea` | Brainstorm 8–12 ideas, filter, pilot-test top 3, rank (called by idea-discovery-pipeline) |
  132. | `novelty-check` | Verify idea novelty via multi-source search + external reviewer |
  133. | `idea-review` | External critical review of research ideas (Codex MCP) |
  134. | `refine-research` | Iterative method refinement via external review (up to 5 rounds, score ≥ 9) |
  135. | `experiment-design` | Claim-driven experiment roadmap with run order, budget, decision gates |
  136. | `experiment-design-pipeline` | One-shot wrapper: refine-research → experiment-design |
  137. | `deploy-experiment` | Deploy experiments — mandatory local-GPU check at Step 0, then Track A (GPU ML) and/or Track B (CPU spatial) |
  138. | `data-download` | Discover, evaluate, download datasets with provenance tracking |
  139. | `spatial-analysis` | Research-question-driven spatial analysis: classification → ESDA → method → conditional diagnostics → interpretation, with a human checkpoint before adding or skipping heavyweight spatial checks |
  140. | `auto-review-loop` | Up to 4 adversarial review rounds with per-criterion floors |
  141. | `generate-report` | Consolidate lit-review + idea + experiment + review artifacts into `output/NARRATIVE_REPORT.md` |
  142. | `paper-writing-pipeline` | Orchestrates paper-plan → paper-figure-generate → paper-draft → paper-review-loop → paper-covert |
  143. | `paper-plan` | Build section outline + figure plan (`output/PAPER_PLAN.md`) |
  144. | `paper-figure-generate` | Generate publication-quality figures, maps, diagrams, and captions |
  145. | `paper-draft` | Turn `output/PAPER_PLAN.md` into a journal-quality Markdown manuscript |
  146. | `paper-review-loop` | Reviewer-editor review of the draft manuscript and iterative revision |
  147. | `paper-covert` | Convert final manuscript into venue submission package (modular LaTeX, PDF, DOCX) |
  148. | `submit-check` | Validate manuscript against target-journal requirements |
  149. | `training-check` | Monitor running experiments for stalls/failures |
  150. ### Domain Knowledge
  151. | File | Domain |
  152. |---|---|
  153. | `spatial-methods.md` | Spatial statistics, regression, autocorrelation |
  154. | `geoai-domain.md` | GeoAI, spatial deep learning, foundation models |
  155. | `academic-writing.md` | Academic writing conventions |
  156. | `apa-citations.md` | APA 7th edition citation formatting |
  157. | `disaster-resilience.md` | Disaster management, community resilience |
  158. | `environmental-health.md` | Environmental epidemiology, exposure assessment |
  159. | `literature-mining.md` | Literature search and synthesis strategies |
  160. | `research-iteration.md` | Iterative research refinement patterns |
  161. ---
  162. ## Control Flags
  163. Edit `CLAUDE.md` before starting a long run:
  164. ```yaml
  165. AUTO_PROCEED: false # true = auto-select top idea after discovery; false = wait for approval
  166. HUMAN_CHECKPOINT: true # true = pause after each review round; false = run autonomously
  167. COMPACT_MODE: false # true = use output/PROJ_NOTES.md instead of full logs (saves context)
  168. EXTERNAL_REVIEW: false # true = use Claude subagent / external reviewer LLM
  169. ```
  170. `full-pipeline` also accepts `REVIEWER_DIFFICULTY = medium | hard | nightmare` and `ARXIV_DOWNLOAD = true | false`. Overrides can be passed inline, e.g.:
  171. ```
  172. /full-pipeline "topic — AUTO_PROCEED: false, difficulty: nightmare"
  173. ```
  174. ---
  175. ## Harness Engineering
  176. Claude Code's hook system automates lifecycle management (configured in `settings.json`):
  177. | Hook | When | What it does |
  178. |---|---|---|
  179. | `PreToolUse` | Before Bash/Write | Validates paths, blocks dangerous commands, logs intent |
  180. | `PostToolUse` | After tool execution | Updates state, caches results |
  181. | `SkillUse` | Before/after each Skill tool call | `harness/hooks/skill_marker.sh` writes per-stage markers feeding `tools/telemetry_stage_marker.py` |
  182. | `Stop` | Agent session ends | Writes `handoff.json`, updates `memory/MEMORY.md`, runs `tools/telemetry_aggregate.py` to emit `output/TELEMETRY.jsonl` and `output/TELEMETRY_STAGES.jsonl`, sends notification |
  183. | `Notification` | Long tasks finish | Desktop alert via `notify-send` / `osascript` |
  184. ---
  185. ## Autoresearch Scoring Loop
  186. ```
  187. paper-draft writes draft
  188. ↓
  189. paper-review-loop scores it (separate context — generator–evaluator separation)
  190. ↓
  191. All 5 dimension floors met AND weighted avg ≥ 7.5? → ACCEPT
  192. ↓ (else)
  193. paper-draft revises (max 3 attempts total)
  194. ↓
  195. If still not accepted → flag for human review
  196. ```
  197. | Dimension | Weight | Hard floor |
  198. |---|---|---|
  199. | Novelty | 30% | ≥ 6.5 |
  200. | Rigor | 25% | ≥ 7.0 |
  201. | Literature coverage | 20% | ≥ 6.5 |
  202. | Clarity | 15% | ≥ 6.0 |
  203. | Impact | 10% | ≥ 6.0 |
  204. Accept requires weighted avg ≥ 7.5 **and** all five floors met.
  205. ---
  206. ## Journal Templates & Profiles
  207. Templates enforce correct structure, section ordering, word limits, and formatting. `paper-covert` additionally loads a YAML **profile** that drives LaTeX conversion.
  208. ### Markdown templates (`templates/`)
  209. | Category | Journals |
  210. |---|---|
  211. | `geoscience/` | Nature Geoscience, Geophysical Research Letters |
  212. | `remote_sensing/` | Remote Sensing of Environment, IEEE TGRS, ISPRS JPRS |
  213. | `giscience/` | IJGIS, Transactions in GIS, Annals of AAG |
  214. ### Submission profiles (`skills/paper-covert/profiles/`)
  215. `aag_annals.yaml`, `generic.yaml`, `ieee_tgrs.yaml`, `ijgis.yaml`, `isprs_jprs.yaml`, `rse.yaml`, `tgis.yaml`.
  216. ---
  217. ## MCP Servers
  218. Declared in `.mcp.json`. Setup notes in `mcp/README_MCP.md`.
  219. | Server | Purpose |
  220. |---|---|
  221. | `filesystem` | Read/write local files and datasets |
  222. | `fetch` | Fetch web content (papers, data portals, journal pages) |
  223. | `geo_mcp` | Spatial data: GADM, OSM Overpass, Census ACS, GEE (`mcp/geo_mcp_server.py`) |
  224. | `arxiv_mcp` | ArXiv search, paper fetch, abstract parsing |
  225. | `github` | GitHub repo reading and code management |
  226. | `brave_search` | Web search for literature, datasets, documentation |
  227. ---
  228. ## Key Output Files
  229. | File | Written by |
  230. |---|---|
  231. | `output/LIT_REVIEW_REPORT.md` | `lit-review` |
  232. | `output/IDEA_REPORT.md` / `NOVELTY_REPORT.md` / `IDEA_REVIEW_REPORT.md` | `idea-discovery-pipeline` |
  233. | `output/refine-logs/FINAL_PROPOSAL.md` / `REFINE_REPORT.md` | `refine-research` |
  234. | `output/refine-logs/EXPERIMENT_PLAN.md` / `output/EXPERIMENT_TRACKER.md` | `experiment-design` |
  235. | `output/experiment/EXPERIMENT_RESULT.md` / `EXPERIMENT_LOG.md` | `deploy-experiment` |
  236. | `output/experiment/data/` / `figures/` / `scripts/` | `deploy-experiment`, `spatial-analysis` |
  237. | `output/AUTO_REVIEW_REPORT.md` / `REVIEW_STATE.json` / `review-rounds/` | `auto-review-loop` |
  238. | `output/METHOD_DESCRIPTION.md` | `auto-review-loop` |
  239. | `output/NARRATIVE_REPORT.md` | `generate-report` |
  240. | `output/PAPER_PLAN.md` | `paper-plan` |
  241. | `output/figures/` | `paper-figure-generate` |
  242. | `output/manuscript/` | `paper-draft`, `paper-review-loop` |
  243. | `output/papers/` | `paper-covert` |
  244. | `output/reports/submit_check_*.md` | `submit-check` |
  245. | `data/DATA_MANIFEST.md`, `data/raw/` | `data-download` |
  246. | `output/PROJ_NOTES.md` | all skills (append-only, compact log) |
  247. | `output/TELEMETRY.jsonl` (per-session) and `output/TELEMETRY_STAGES.jsonl` (per-skill) | `tools/telemetry_aggregate.py` (run by Stop hook) |
  248. | `output/CONTRACT_VIOLATION.md` | any skill that detects a downgraded success criterion or other contract violation |
  249. | `memory/MEMORY.md`, `handoff.json` | Stop hook |
  250. ---
  251. ## Project Structure
  252. ```
  253. night_owl_research_agent/
  254. ├── CLAUDE.md ← Dashboard and project conventions
  255. ├── README.md ← This file
  256. ├── design_principle.md ← Skill-level design principles (export → Excel via tools/)
  257. ├── design_principle_agents.md ← Sub-agent design principles
  258. ├── settings.json ← Claude Code hooks, permissions, env vars
  259. ├── .mcp.json ← MCP server declarations
  260. │
  261. ├── .claude/
  262. │ ├── commands/
  263. │ │ └── launcher.md ← /launcher (only installed slash command)
  264. │ └── agents/ ← Specialist sub-agent definitions (9 total)
  265. │ ├── orchestrator.md
  266. │ ├── literature-scout.md
  267. │ ├── synthesis-analyst.md
  268. │ ├── gap-finder.md
  269. │ ├── hypothesis-generator.md
  270. │ ├── geo-specialist.md
  271. │ ├── paper-writer.md
  272. │ ├── peer-reviewer.md
  273. │ └── citation-manager.md
  274. │
  275. ├── skills/ ← 22 workflow skills + knowledge/
  276. │ ├── full-pipeline/SKILL.md
  277. │ ├── lit-review/SKILL.md
  278. │ ├── idea-discovery-pipeline/SKILL.md
  279. │ ├── generate-idea/SKILL.md
  280. │ ├── novelty-check/SKILL.md
  281. │ ├── idea-review/SKILL.md
  282. │ ├── refine-research/SKILL.md
  283. │ ├── experiment-design/SKILL.md
  284. │ ├── experiment-design-pipeline/SKILL.md
  285. │ ├── deploy-experiment/SKILL.md
  286. │ ├── data-download/SKILL.md
  287. │ ├── spatial-analysis/SKILL.md
  288. │ ├── auto-review-loop/SKILL.md
  289. │ ├── generate-report/{SKILL.md, templates/}
  290. │ ├── paper-writing-pipeline/SKILL.md
  291. │ ├── paper-plan/SKILL.md
  292. │ ├── paper-figure-generate/{SKILL.md, templates/}
  293. │ ├── paper-draft/{SKILL.md, templates/}
  294. │ ├── paper-review-loop/{SKILL.md, templates/}
  295. │ ├── paper-covert/{SKILL.md, profiles/, templates/}
  296. │ ├── submit-check/SKILL.md
  297. │ ├── training-check/SKILL.md
  298. │ └── knowledge/ ← Domain reference files
  299. │
  300. ├── tools/ ← CLI utilities (called by skills + harness)
  301. │ ├── arxiv_fetch.py
  302. │ ├── semantic_scholar_fetch.py
  303. │ ├── convert_skills_to_llm_chat.py
  304. │ ├── export_design_principle_table.py ← exports design_principle.md tables to Excel
  305. │ ├── export_agent_design_principle_table.py ← exports design_principle_agents.md tables
  306. │ ├── telemetry_stage_marker.py ← called by skill_marker hook (per-skill timing)
  307. │ └── telemetry_aggregate.py ← called by Stop hook (session/stage telemetry)
  308. │
  309. ├── configs/
  310. │ └── default.yaml ← Scoring weights, domain keywords
  311. │
  312. ├── templates/ ← Project + paper templates
  313. │ ├── EXPERIMENT_LOG_TEMPLATE.md
  314. │ ├── EXPERIMENT_PLAN_TEMPLATE.md
  315. │ ├── FINDINGS_TEMPLATE.md
  316. │ ├── HANDOFF_TEMPLATE.json
  317. │ ├── IDEA_CANDIDATES_TEMPLATE.md
  318. │ ├── PAPER_PLAN_TEMPLATE.md
  319. │ ├── RESEARCH_CONTRACT_TEMPLATE.md
  320. │ ├── RESEARCH_PLAN_TEMPLATE.md
  321. │ ├── REVIEW_STATE_TEMPLATE.json
  322. │ ├── geoscience/ (nature_geoscience, grl_template)
  323. │ ├── remote_sensing/ (ieee_tgrs, isprs_jprs, remote_sensing_env)
  324. │ └── giscience/ (ijgis, transactions_gis, annals_aag)
  325. │
  326. ├── harness/
  327. │ ├── hooks/ (pre_tool_use, post_tool_use, skill_marker, stop_hook, notification)
  328. │ └── prompts/system_geo.md
  329. │
  330. ├── mcp/ ← MCP server implementations
  331. │ ├── geo_mcp_server.py
  332. │ └── README_MCP.md
  333. │
  334. ├── memory/MEMORY.md ← Persistent session memory
  335. │
  336. ├── output/ ← All generated outputs
  337. │ ├── AUTO_REVIEW.md
  338. │ ├── REVIEW_STATE.json
  339. │ ├── ARCHITECTURE_DIAGRAM_PROMPTS.md
  340. │ ├── papers/
  341. │ ├── figures/
  342. │ └── reports/
  343. │
  344. ├── res/nora_architecture.png ← Architecture diagram
  345. │
  346. └── archived/ ← Retired skills and pre-skill Python modules
  347. ```
  348. ---
  349. ## Contributing
  350. 1. Fork this repository.
  351. 2. Add skills in `skills/<name>/SKILL.md`.
  352. 3. Add journal templates in `templates/` (plus a YAML profile in `skills/paper-covert/profiles/` if needed).
  353. 4. Add domain knowledge in `skills/knowledge/`.
  354. ---
  355. ## License
  356. MIT License. See `LICENSE` for details.
  357. ---
  358. ## Design Principles
  359. Two living documents describe the rules NORA's skills and sub-agents follow. Treat them as the source of truth when you write or change a skill.
  360. | File | Scope |
  361. |---|---|
  362. | `design_principle.md` | Skill-level principles: anchored problem, smallest adequate mechanism, generator–evaluator separation, conditional geospatial checks, mandatory local-GPU check before any pilot or full experiment, human-checkpoint pattern for synthesis decisions. |
  363. | `design_principle_agents.md` | Sub-agent principles for the 9 specialists in `.claude/agents/` (orchestrator, literature-scout, gap-finder, hypothesis-generator, geo-specialist, paper-writer, peer-reviewer, citation-manager, synthesis-analyst). |
  364. Both files can be exported to Excel for review or workshop use:
  365. ```bash
  366. python tools/export_design_principle_table.py
  367. python tools/export_agent_design_principle_table.py
  368. ```
  369. ---
  370. ## Inspired By
  371. NORA's design borrows ideas from several open-source projects. Credit and gratitude to their authors:
  372. - [BZBarrett/superpowers](https://github.com/BZBarrett/superpowers) — skill-pack patterns for extending Claude Code with composable Markdown workflows.
  373. - [BZBarrett/get-shit-done](https://github.com/BZBarrett/get-shit-done) — pragmatic harness patterns for getting long-running agentic work to actually finish.
  374. - [wanshuiyin/Auto-claude-code-research-in-sleep](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep) — "research while you sleep" autonomous-loop concept that motivated NORA's overnight pipelines, handoff.json recovery, and adversarial review loop.
  375. - [karpathy/autoresearch](https://github.com/karpathy/autoresearch) — generator–evaluator separation and the per-criterion floors + weighted-average scoring loop adapted into `auto-review-loop` and `paper-review-loop`.
  376. If your project influenced NORA and is missing here, please open an issue and we will add it.
  377. ---
  378. ## Citation
  379. If you use NORA in your research, please cite the arXiv preprint:
  380. > Zhou, B., Wu, Q., Huang, X., Ning, H., Li, D., & Zhang, Z. (2026). *NORA: Night Owl Research Agent — Autonomous AI Research for Geoscience, Remote Sensing, and GIScience*. arXiv:2605.02092. <https://arxiv.org/abs/2605.02092>
  381. ```bibtex
  382. @misc{zhou2026nora,
  383. title = {NORA: Night Owl Research Agent --- Autonomous AI Research for Geoscience, Remote Sensing, and GIScience},
  384. author = {Zhou, Bing and Wu, Qiusheng and Huang, Xiao and Ning, Huan and Li, Diya and Zhang, Ziyi},
  385. year = {2026},
  386. eprint = {2605.02092},
  387. archivePrefix = {arXiv},
  388. url = {https://arxiv.org/abs/2605.02092},
  389. howpublished = {\url{https://github.com/GRIND-Lab-Core/night_owl_research_agent}}
  390. }
  391. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.