Getting Started

March 16, 2026 · View on GitHub

Complete installation and first-run guide for Sibyl Research System.

Fastest path: Open the cloned repo in Claude Code and say "Read docs/setup-guide.md and help me set up Sibyl". Claude will automatically check your environment and configure everything, only asking for info it can't detect. See setup-guide.md for the full checklist Claude follows.

Prerequisites

RequirementVersionNotes
Python3.12+Used for orchestrator and experiments
Claude Code CLILatestCore runtime for all agents
Node.js18+Required for npm-based MCP servers
GitAnyVersion control for workspaces
GPU ServerSSH accessibleFor experiment execution
tmuxAnyStrongly recommended — persistent sessions + Sentinel auto-recovery

tmux enables the Sentinel watchdog to automatically restart Claude Code if it crashes or goes idle during long experiments. Install: brew install tmux (macOS) / apt install tmux (Linux). Always run Sibyl inside a tmux session: tmux new -s sibyl.

API Keys

VariableRequiredDescription
ANTHROPIC_API_KEYYesClaude API key, required by Claude Code CLI
OPENAI_API_KEYIf codex_enabled: trueOpenAI API key for Codex cross-review

Environment Variable

Agent team features require:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your ~/.zshrc or ~/.bashrc for persistence.

Installation

Option 1: Automated Setup

git clone https://github.com/Sibyl-Research-Team/sibyl-research-system.git
cd sibyl-research-system
chmod +x setup.sh && ./setup.sh

setup.sh will:

  • Find Python 3.12+ and create a virtual environment (.venv/)
  • Install Sibyl into the repo venv (pip install -e .)
  • Install required MCP servers (arXiv)
  • Interactively configure SSH MCP server (GPU server host, user, SSH key)
  • Create a manual MCP JSON config only when no existing MCP JSON config is present
  • Create config.yaml with GPU server settings
  • Add or update export SIBYL_ROOT="..." in your shell rc file (~/.zshrc / ~/.bashrc)
  • Check for required environment variables (ANTHROPIC_API_KEY, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS)

Option 2: Manual Setup

git clone https://github.com/Sibyl-Research-Team/sibyl-research-system.git
cd sibyl-research-system

# Create Python virtual environment
python3.12 -m venv .venv
.venv/bin/pip install -e .

MCP Server Setup

Sibyl relies on several MCP servers. setup.sh configures the required ones automatically when possible. For manual setup, prefer claude mcp add --scope local ... so the configuration stays repo-scoped by default. See MCP Servers for full installation and configuration instructions.

Required (configured by setup.sh):

  • SSH MCP — remote GPU execution (@fangjunjie/ssh-mcp-server)
  • arXiv MCP — literature search (pip install arxiv-mcp-server)

Recommended:

  • Google Scholar MCP — academic search (used by 10+ agents): 
    git clone https://github.com/JackKuo666/Google-Scholar-MCP-Server.git ~/.local/share/mcp-servers/Google-Scholar-MCP-Server
.venv/bin/pip install -r ~/.local/share/mcp-servers/Google-Scholar-MCP-Server/requirements.txt
claude mcp add --scope local google-scholar -- .venv/bin/python3 ~/.local/share/mcp-servers/Google-Scholar-MCP-Server/google_scholar_server.py
  • Codex MCP — GPT-5.4 independent cross-review (enable with codex_enabled: true after installation)

Optional:

GPU Server Setup

setup.sh handles SSH MCP configuration interactively. For server-side setup (conda environments, GPU polling, shared resources), see SSH & GPU Setup.

Load Plugin

Sibyl is provided as a Claude Code Plugin. Always run inside tmux for persistent sessions:

# `setup.sh` normally writes this for you; set it manually only if you skipped setup.sh
export SIBYL_ROOT=/path/to/sibyl-research-system

# Repo root: setup / init / status / migrate / evolve
cd "$SIBYL_ROOT"
tmux new -s sibyl-admin
claude --plugin-dir "$SIBYL_ROOT/plugin" --dangerously-skip-permissions

# Workspace root: actual project execution (recommended)
cd "$SIBYL_ROOT/workspaces/my-project"
tmux new -s sibyl-my-project
claude --plugin-dir "$SIBYL_ROOT/plugin" --dangerously-skip-permissions

Replace /path/to/sibyl-research-system with your actual local path.

For active research runs, start Claude from the target workspace root workspaces/<project>/, not from the repo root and not from workspaces/<project>/current. This loads the workspace-specific CLAUDE.md, project memory, Ralph prompt, and .claude/ runtime links directly.

For multi-project parallel execution, use one tmux session/window/pane per project and launch one Claude instance inside each workspace root. Do not reuse the same Claude pane/session across projects.

--dangerously-skip-permissions is strongly recommended for Sibyl to function as designed. Without it, Claude Code will prompt for permission on every tool call — file reads, SSH commands, MCP calls, agent spawns — making autonomous multi-stage research impractical (hundreds of manual approvals per iteration).

⚠️ Security trade-off: This flag grants Claude Code unrestricted access to execute commands, read/write files, and call MCP tools without confirmation. Only use it on machines dedicated to research, and consider running inside a container or VM. Do not use on systems with sensitive credentials or data outside the project scope.

Verify plugin loaded: After starting Claude Code, type /sibyl-research:status — if the plugin is loaded, it will execute the status command.

First Research Project

Need a realistic end-to-end smoke test first? Use the fixed tiny demo in ../demos/remote_parallel_smoke/README.md. It scaffolds a project that exercises remote SSH execution, GPU polling, experiment monitoring, parallel tasks, and the writing/LaTeX chain against pre-existing remote checkpoints.

1. Initialize

/sibyl-research:init

This interactive command will:

  • Ask for your research topic
  • Generate a spec.md requirements file
  • Create a workspace under workspaces/<project>/

2. Configure

Create a root-level config file for machine-level defaults (git-ignored):

cp config.example.yaml config.yaml

Edit the key fields:

ssh_server: "default"               # Use "default" when ssh-mcp-server was added with --host/--username directly
# ssh_server: "my-gpu-server"       # Use your SSH host alias only if the MCP setup resolves one
remote_base: "/home/you/sibyl"      # Base directory on GPU server
max_gpus: 4                         # Max GPUs to use
language: zh                        # Default control-plane language; paper writing still stays English
codex_enabled: false                # Opt in only after Codex MCP + OPENAI_API_KEY are configured

You can also create project-specific overrides in workspaces/<project>/config.yaml — these take priority over root config. See Configuration Reference for all options.

3. Start Research

/sibyl-research:start spec.md

This enters the autonomous research loop. The system will:

  1. Search literature (arXiv + Web)
  2. Generate and debate ideas (6-agent team)
  3. Plan and execute experiments (GPU-parallel)
  4. Analyze results (6-agent debate)
  5. Write and review paper (multi-agent)
  6. Iterate until quality gate passes

4. Monitor Progress

/sibyl-research:status          # View all projects
/sibyl-research:debug <project> # Single-step mode

All Plugin Commands

See Plugin Commands Reference for the complete list of 12 commands.

Next Steps