open-research 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gangj277
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# Open Research
+
+Local-first research CLI agent. Discover papers, synthesize notes, run analysis, and draft artifacts from your terminal.
+
+## Install
+
+```bash
+npm install -g open-research
+```
+
+Requires Node.js 20+.
+
+## Quick Start
+
+```bash
+# Launch the TUI
+open-research
+
+# Connect your OpenAI account (inside the TUI)
+/auth
+
+# Initialize a workspace
+/init
+
+# Start researching
+> What are the latest advances in transformer attention mechanisms?
+```
+
+## What It Does
+
+Open Research is an AI-powered research agent that runs in your terminal. It connects to OpenAI's API and gives you a full research workflow:
+
+- **Discover papers** across arXiv, Semantic Scholar, and OpenAlex
+- **Read and analyze** PDFs, datasets, and web pages
+- **Run code** — Python scripts, R analysis, LaTeX compilation, anything
+- **Write artifacts** — notes, syntheses, paper drafts grounded in sources
+- **Review changes** — risky edits go to a review queue for your approval
+
+## Tools
+
+The agent has access to:
+
+| Tool | What it does |
+|---|---|
+| `read_file` | Read any file on disk (text, with binary detection) |
+| `read_pdf` | Extract text from PDFs |
+| `list_directory` | Explore directory trees |
+| `run_command` | Execute shell commands (python, R, LaTeX, curl, etc.) |
+| `search_workspace` | Search across workspace files |
+| `write_new_file` | Create new workspace files |
+| `update_existing_file` | Edit existing files |
+| `search_external_sources` | Search academic paper databases |
+| `fetch_url` | Fetch web pages and APIs |
+| `ask_user` | Ask you questions when clarification is needed |
+| `load_skill` | Activate research skills |
+| `create_paper` | Create LaTeX paper drafts |
+
+## Slash Commands
+
+| Command | Description |
+|---|---|
+| `/auth` | Connect OpenAI account via browser |
+| `/auth-codex` | Import existing Codex CLI auth |
+| `/init` | Initialize workspace in current directory |
+| `/skills` | List available research skills |
+| `/config` | View or change settings |
+| `/clear` | Start a new conversation |
+| `/help` | Show all commands |
+| `/exit` | Quit |
+
+## Skills
+
+Built-in research skills that guide the agent's methodology:
+
+- **source-scout** — Find citation gaps and discover relevant papers
+- **devils-advocate** — Stress-test claims and assumptions
+- **methodology-critic** — Critique research methodology
+- **evidence-adjudicator** — Evaluate evidence quality
+- **experiment-designer** — Design experiments and studies
+- **draft-paper** — Draft LaTeX papers from workspace evidence
+- **paper-explainer** — Explain complex papers
+- **synthesis-updater** — Update research syntheses
+- **skill-creator** — Create custom skills
+
+Type `/skill-name` in the TUI to activate any skill, or create your own in `~/.open-research/skills/`.
+
+## Workspace Structure
+
+```
+my-research/
+  sources/       # PDFs, papers, raw data
+  notes/         # Research notes and briefs
+  artifacts/     # Generated outputs
+  papers/        # LaTeX paper drafts
+  experiments/   # Analysis scripts and results
+  .open-research/  # Workspace metadata
+```
+
+## Features
+
+- **Markdown rendering** in terminal output (bold, italic, code blocks, lists, headings)
+- **Slash command autocomplete** with arrow-key navigation
+- **@file mentions** to reference workspace files inline
+- **Shift+Enter** for multi-line input
+- **Context management** — automatic compaction when conversation gets long
+- **Token tracking** — see context usage in the status bar
+- **Tool activity streaming** — see what the agent is doing in real-time
+- **Review queue** — risky edits require your approval before applying
+
+## Development
+
+```bash
+git clone https://github.com/gangj277/open-research.git
+cd open-research
+npm install
+npm run dev        # Run in dev mode
+npm test           # Run tests
+npm run build      # Build for production
+```
+
+## License
+
+MIT

package/builtin-skills/devils-advocate/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: devils-advocate
+description: Stress-test claims, assumptions, and arguments in the current research workspace.
+---
+
+# Devil's Advocate
+
+Challenge the current thesis by locating weak assumptions, counter-evidence, and overclaims.

package/builtin-skills/draft-paper/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: draft-paper
+description: Draft a LaTeX paper from the current workspace evidence and artifacts.
+---
+
+# Draft Paper
+
+Create a paper draft that cites the workspace faithfully and keeps claims grounded.

package/builtin-skills/evidence-adjudicator/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: evidence-adjudicator
+description: Weigh conflicting evidence and assess which claims are best supported.
+---
+
+# Evidence Adjudicator
+
+Compare competing claims and state which evidence is stronger and why.

package/builtin-skills/experiment-designer/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: experiment-designer
+description: Design follow-up experiments and structured evaluation plans from the workspace.
+---
+
+# Experiment Designer
+
+Turn open questions into concrete hypotheses, procedures, and analysis plans.

package/builtin-skills/methodology-critic/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: methodology-critic
+description: Critique study design, methods, and overclaims in cited research.
+---
+
+# Methodology Critic
+
+Evaluate whether the cited methods actually support the claimed conclusions.

package/builtin-skills/paper-explainer/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: paper-explainer
+description: Explain papers, methods, and concepts grounded in the local workspace.
+---
+
+# Paper Explainer
+
+Translate difficult papers into clear, source-grounded explanations.

package/builtin-skills/skill-creator/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: skill-creator
+description: Create or update Open Research skills using the Codex-style skill format.
+---
+
+# Skill Creator
+
+Use this skill when the user wants to create, revise, or package a custom research skill.
+
+## Workflow
+
+1. Clarify the job the skill should do.
+2. Define trigger phrases and example requests.
+3. Keep the skill concise.
+4. Use `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`.
+5. Validate that the folder name matches the normalized skill name.

package/builtin-skills/source-scout/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: source-scout
+description: Find citation gaps and propose relevant external papers for the current research thread.
+---
+
+# Source Scout
+
+Use external search to find papers that close obvious evidence gaps.

package/builtin-skills/synthesis-updater/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: synthesis-updater
+description: Update synthesis artifacts using new evidence from the workspace.
+---
+
+# Synthesis Updater
+
+Revise synthesis outputs without losing provenance or uncertainty labels.