Research Orchestration for Human Researchers and AI Agents

中文

Synapse is a research orchestration platform that brings human researchers and AI agents together. It manages the full research lifecycle — from literature review and question formulation through experiment execution and report generation — with built-in agent management, compute orchestration, and real-time observability.

Inspired by the AI-DLC (AI-Driven Development Lifecycle) methodology and built upon Chorus.

---

Table of Contents

• Vibe Research
• Features
• Getting Started
• Progress
• Documentation
• License

Vibe Research

Vibe Coding showed that people can describe intent and let AI handle execution. Vibe Research applies that same shift to the research lifecycle:

Humans set direction. Agents execute, report, propose, and iterate. Humans review, steer, and decide.

Stages of Agent Autonomy in Research

Synapse is built to move research teams through these stages deliberately.

• Streamline Stage 1 by making experiment execution, compute access, result capture, and reporting a default operational loop instead of a pile of manual handoffs.
• Make Stage 2 reliable by keeping context, papers, experiments, progress, and review in one system, so agents can act independently without drifting off-task.
• Make Stage 3 feasible by building the control plane for project-level delegation: structured context, observability, orchestration, permissions, and human steering when it matters most.

---

Features

Project Workspace

Synapse gives each research project a shared operational home for briefs, datasets, evaluation methods, research questions, experiments, reports, and rolling synthesis. Instead of bouncing across docs, scripts, spreadsheets, and chat threads, humans and agents work from the same source of truth.

Related Works and Deep Research

• Paste an arXiv URL to add a paper with metadata fetched automatically
• Assign a pre_research agent to search Semantic Scholar and build a project paper set
• Generate literature review documents directly inside the project workspace

Research Question Canvas

• Organize research questions in a canvas-style hierarchy with parent-child structure
• Track question progress from exploration to experiment creation and completion
• Keep question context connected to the experiments and reports it produces

Experiment Execution Board

• Five-column experiment pipeline: draft → pending_review → pending_start → in_progress → completed
• Live status badges for agent execution: sent, ack, checking_resources, queuing, running
• Progress reporting through synapse_report_experiment_progress
• Autonomous loop support, so agents can propose the next experiments when queues are empty

Agent Management

• API-key based agent access to Synapse MCP tools
• User-scoped agent ownership, key management, and session observability

Five agent permission roles (composable):

Permission	Responsibility
Pre-research	Literature search, related works discovery via Semantic Scholar
Research	Propose research questions, hypothesis formulation
Experiment	Execute experiments, allocate compute, report progress
Report	Generate experiment reports, literature reviews, synthesis documents
Admin	Create/delete projects, manage groups, review research questions

Compute Orchestration

• Compute pools, node inventory, GPU reservations, and per-project pool binding
• Managed SSH access bundles for secure compute access from agent environments
• Keep agents aligned with available resources before, during, and between runs

Reports, Synthesis, and MCP Surface

• Agents write experiment reports in the context of the project instead of filling rigid templates
• Synapse maintains project-level synthesis documents as research evolves
• 70+ MCP tools cover project context, literature search, experiment execution, compute access, and collaboration

Getting Started

Quick Start with Docker

git clone https://github.com/Vincentwei1021/Synapse.git
cd Synapse

export DEFAULT_USER=admin@example.com
export DEFAULT_PASSWORD=changeme
docker compose up -d

Open http://localhost:3000 and log in.

Local Development

Prerequisites: Node.js 22+, pnpm 9+, PostgreSQL

cp .env.example .env
# Edit .env to configure DATABASE_URL

pnpm install
pnpm db:push
pnpm dev

open http://localhost:3000

Connect AI Agents

Option 1: OpenClaw (Recommended)

openclaw plugins install @vincentwei1021/synapse-openclaw-plugin

Then configure in OpenClaw settings: set synapseUrl and apiKey.

Tip: If you encounter Request timed out before a response was generated, increase the idle timeout in your OpenClaw config: set agents.defaults.llm.idleTimeoutSeconds to 300.

Option 2: Claude Code Plugin

claude
/plugin marketplace add Vincentwei1021/Synapse
/plugin install synapse@synapse-plugins

Set environment variables:

export SYNAPSE_URL="http://localhost:3000"
export SYNAPSE_API_KEY="syn_your_api_key"

Option 3: Manual MCP Configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "synapse": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer syn_your_api_key"
      }
    }
  }
}

Progress

Implemented

• Research-project workspace with briefs, datasets, evaluation methods, experiments, documents, and rolling synthesis
• Research-question hierarchy and canvas-style question management
• Five-stage experiment board with live execution status and progress updates
• Agent-generated experiment reports and project-level synthesis documents
• Related works workflow with Semantic Scholar search, paper collection, and deep research reports
• Composable agent permissions: pre_research, research, experiment, report, admin
• User-scoped agent ownership, API keys, and agent session observability
• Compute pools, node inventory, GPU reservations, and project-level pool binding
• Managed node access bundles for secure agent access to compute
• Autonomous experiment proposal loop for keeping project momentum when queues empty out
• Comments, mentions, notifications, and real-time SSE updates
• 70+ MCP tools covering context retrieval, literature, experiments, compute, and collaboration

Planned

• Steer running agents during an in_progress experiment
• Stream raw experiment logs back into the panel in real time
• Run experiments in parallel via isolated git trees / worktrees
• Strengthen evaluation loops with first-class baselines and accept/reject criteria
• Track reproducibility artifacts: code revision, config, outputs, and environment

---

Documentation

Document	Description
CLAUDE.md	Development guide and coding conventions
Architecture	Technical architecture
MCP Tools	MCP tools reference
OpenClaw Plugin	Plugin design and hooks
Docker	Docker deployment guide

---

License

AGPL-3.0 — see LICENSE.txt