CrowdResearch

CrowdResearch is under active development. Star this repo to follow updates.

An open protocol for structured research knowledge — plans, reflections, and experiment context — stored as a time-ordered stream, synced across humans and AI agents.

Why

AI agents can now run hundreds of experiments autonomously (autoresearch, autoresearch@home). The bottleneck is no longer execution — it's knowledge alignment. When multiple agents and humans iterate on the same project, there's no shared memory: insights get lost, experiments get repeated, and sync meetings become the real drag.

CrowdResearch gives every participant — human or agent — a common place to record what was tried, why, and what was learned.

Design Principles

AI-native protocol, not a product. We trust agents to read, grep, and retrieve what matters. CrowdResearch only provides a standard file structure for storage and sync — no assumptions about how you summarize or analyze.

Build on top of it. CrowdResearch is the underlying layer. You can add a UI, a dashboard, or plug it into your own workflow. Think of it as a common law for how humans and agents communicate research context.

Permissions, Local and Cloud Sync
CrowdResearch uses git to manage permissions and to enable seamless local and cloud synchronization. This approach supports a wide range of use cases: keep your research knowledge private, share it within a team, or publish it publicly for the world to access. Imagine a global knowledge base where insights from diverse researchers are easily discoverable and reusable.

Install

Requires Python 3.10+

pip install git+https://github.com/A-EVO-Lab/CrowdResearch.git

Setup

In your git project repo:

crowdresearch init                    # default: installs Cursor skill
crowdresearch init --claude           # installs CLAUDE.md for Claude Code
crowdresearch init --codex            # installs AGENTS.md + skill for Codex
crowdresearch init --all-agents       # installs rules for all agents
crowdresearch init --remote <url>     # enable cloud sync

This creates .crowdresearch/, installs a git hook, and injects agent rules so your AI agent knows how to use CrowdResearch automatically.

Usage

1. Store knowledge

For humans

crowdresearch draft "Increase LR from 0.01 to 0.04. Hypothesis: faster convergence."
crowdresearch reflect "val_bpb improved from 1.00 to 0.993. Higher LR helps."
crowdresearch status

For AI agents

After crowdresearch init, your agent (Cursor, Claude Code, Codex) automatically knows how to:

1. Read history — .crowdresearch/knowledge.jsonl for past plans and reflections
2. Read config — crowdresearch.yaml for project-specific guidance
3. Record plans — crowdresearch draft "..."
4. Record reflections — crowdresearch reflect "..."

No extra setup needed — the agent uses the same CLI as humans. Just mention it in your prompt, e.g. "follow program.md to run experiments, log your plan and results using crowdresearch", or add it directly to your project's instructions file.

2. Retrieve & analyze knowledge

All knowledge lives in plain JSONL files that any agent can read directly:

• This project: .crowdresearch/knowledge.jsonl
• All contributors (with cloud sync): .crowdresearch/.cloud_storage/{project}/{author}/knowledge.jsonl

Just ask your agent: "Read the crowdresearch logs and summarize what experiments have been tried and what we've learned so far."

Supported agents

Agent	init flag	What gets installed
Cursor	--cursor (default)	.cursor/skills/crowdresearch/SKILL.md
Claude Code	--claude	CLAUDE.md
Codex	--codex	AGENTS.md + .agents/skills/crowdresearch/SKILL.md
All	--all-agents	All of the above

If the target file already exists (e.g. you have a CLAUDE.md), CrowdResearch appends its instructions instead of overwriting.

Demo & Examples

As a demonstration, I used the Cursor agent to run the autoresearch experiment, enabling it to automatically manage and log its learning process with the CrowdResearch skill. The resulting knowledge and experiment logs were auto-saved at:
https://github.com/A-EVO-Lab/CrowdResearch-demo-logs

CrowdResearch.mp4

To showcase collaboration, I then used another Cursor agent on a different device to access these logs and generate a summary. This demo illustrates how humans and AI agents can seamlessly collaborate using CrowdResearch to document, share, and analyze experimental knowledge.

Data format

Knowledge is stored as a JSONL stream in .crowdresearch/knowledge.jsonl:

{"type": "plan", "ts": "...", "author": "Tom", "project": "autoresearch", "content": "Increase LR to 0.04.", "commit": "abc1234"}
{"type": "reflection", "ts": "...", "author": "Tom", "project": "autoresearch", "content": "val_bpb improved from 1.00 to 0.993."}
{"type": "commit", "ts": "...", "author": "Tom", "project": "autoresearch", "content": "change lr", "commit": "abc1234"}

Three item types: commit (auto from hook), plan (via draft), reflection (via reflect).

Configuration

Optional crowdresearch.yaml in your project root:

project_id: "my-project-id"

reflection:
  context:
    - "run.log"
    - "results.tsv"
  prompt: "Summarize: what was tried, outcome with metrics, what was learned."

These fields guide agents on what files to read and how to write reflections.

Cloud sync

Knowledge syncs to a shared repository, organized by project and author, and it inherits git's permission management:

cloud-repo/
├── autoresearch/
│   ├── Tom/
│   │   └── knowledge.jsonl
│   └── Jerry/
│       └── knowledge.jsonl

Each contributor writes to their own file — no merge conflicts.

crowdresearch init --remote https://github.com/org/research-logs.git

Commands

Command	Description
crowdresearch init	Initialize in current git repo
crowdresearch draft "text"	Record a plan
crowdresearch reflect "text"	Record a reflection
crowdresearch sync	Sync knowledge to/from cloud repo
crowdresearch status	Show current status
crowdresearch config show/get/set	Manage project configuration