research-hub-agent

Command-line client for Research Hub agent access.

Install:

npm install -g @hci_hub/research-hub-agent

Configure:

research-hub setup

The setup command prompts for your user-scoped token, tests the connection, and can save the environment variables to your shell profile. It also adds the npm global bin directory to PATH so new terminals can find research-hub.

Manual configuration is also supported:

export RESEARCH_HUB_AGENT_TOKEN='<token-created-in-research-hub-settings>'

RESEARCH_HUB_AGENT_API_URL defaults to https://research.runzecai.com/api/agent; set it only if you need a custom deployment.

For a custom deployment:

research-hub setup --api-url https://your-domain.example/api/agent

Use:

research-hub project.list
research-hub context.get --project PROJECT_UUID
research-hub literature --schema
research-hub literature.get --project PROJECT_UUID
research-hub literature.update --project PROJECT_UUID --json-file ./literature-update.json --expected-updated-at 2026-05-01T00:00:00Z
research-hub literature.paper.update --project PROJECT_UUID --id PAPER_NODE_ID --json-file ./paper-analysis.json
research-hub literature.paper.delete --project PROJECT_UUID --id PAPER_NODE_ID
research-hub literature.node.delete --project PROJECT_UUID --node-id NODE_ID
research-hub literature.sync --project PROJECT_UUID --json-file ./literature-sync.json
research-hub todo.create --project PROJECT_UUID --title "Draft intro" --priority high
research-hub meeting.list --project PROJECT_UUID
research-hub meeting --schema
research-hub meeting.create --project PROJECT_UUID --title "Advisor meeting" --set-file transcript_raw=./transcript.md --set-file ai_analysis=./analysis.json
research-hub meeting.update --id MEETING_UUID --json-file ./meeting-updates.json

The token is user-scoped. Research Hub checks ownership or accepted collaboration before each operation.

For long text and structured fields, prefer file-based input instead of shell-escaped inline arguments:

research-hub meeting.update --id MEETING_UUID --set-file transcript_raw=./transcript.md
research-hub meeting.update --id MEETING_UUID --set-file ai_analysis=./analysis.json

--set-file ai_analysis=... parses the file as JSON. Other --set-file fields are read as UTF-8 text.

Whole request payloads can also be loaded from disk:

research-hub meeting.update --id MEETING_UUID --json-file ./updates.json
research-hub source.upsert --project PROJECT_UUID --json-file ./source.json
research-hub source.bulk_update --project PROJECT_UUID --json '{"ids":["SOURCE_UUID"],"updates":{"analyzed_at":"2026-05-01T00:00:00Z"}}'
research-hub source.bulk_upsert --project PROJECT_UUID --json-file ./sources.json
research-hub doc.upsert --project PROJECT_UUID --title "Literature Sync Report" --format md --set-file content=./report.md
research-hub doc.upsert --project PROJECT_UUID --title "Related Work Draft" --format tex --set-file content=./related-work.tex

Project docs support md, txt, and tex; when --format is omitted, Research Hub stores the doc as md.

For meeting.update, updates.json may either contain an updates object or the allowed update fields at the top level:

{
  "updates": {
    "summary": "Updated summary",
    "ai_analysis": {
      "mainSummary": "Updated summary"
    }
  }
}

Preview the request body without calling the API:

research-hub meeting.update --id MEETING_UUID --json-file ./updates.json --dry-run

For meeting field structure and accepted update keys:

research-hub meeting --schema

Meeting records accept:

• title: string, required on create.
• date: ISO 8601 datetime string; create defaults to the current time when omitted.
• summary: string, plain text or markdown.
• transcript_raw: string, raw transcript or meeting notes; use --set-file transcript_raw=... for long text.
• ai_analysis: JSON object, not a string. Common fields are mainSummary, keyDiscussionPoints, proposedStrategy, nextSteps, participantInsights, and optional processedTranscript with byTimeline and bySpeaker.
• attachment: share URL string or null; use this for relevant links, not local-only file paths.

For literature maintenance fields and bulk source sync:

research-hub literature --schema
research-hub source --schema
research-hub project --schema
research-hub doc --schema

literature.update is a full-tree write and is guarded against stale overwrites. Pass expectedUpdatedAt from literature.get, or use --force only when you intentionally want to overwrite the latest tree. Prefer localized actions such as literature.paper.update, literature.paper.delete, and literature.node.delete.

literature.sync accepts a JSON file with externalSources, optional literature_data, matchStrategy, markAnalyzed, and docReport. It can match source metadata, insert missing sources, update the literature analysis, mark matched sources analyzed, and create or update a sync report doc in one call.

To replace one paper's analyzed content after a local agent re-analysis, use literature.paper.update with a JSON file:

{
  "updates": {
    "paperSummary": "What the paper does",
    "projectRelevance": "Why it matters to this project",
    "relationship": "supporting",
    "group": "Related Work Group",
    "gapOrUse": "How to use it or what boundary remains",
    "relevancyInsights": []
  },
  "markSourceAnalyzed": true
}

To remove a single paper without touching unrelated paper analysis:

research-hub literature.paper.delete --project PROJECT_UUID --id PAPER_NODE_ID