Installation

Get sciClaw running in minutes. Choose the method that fits your workflow.

Prerequisites: install Homebrew

If you don't already have Homebrew, install it first. Open Terminal (macOS) or your shell (Linux) and paste:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen prompts. When it finishes, confirm Homebrew is available:

brew --version

Step 1 — Install sciClaw

Add the sciClaw tap and install the package:

brew tap drpedapati/tap && brew install sciclaw

This installs sciclaw as the primary command and picoclaw as a compatibility alias. Homebrew also installs companion tools used by built-in skills (including irl, rg, docx-review, and pubmed-cli) as dependencies.

Step 2 — Onboard

sciclaw onboard --yes

onboard creates the default configuration directory (~/.config/sciclaw/), writes starter config files, and registers the built-in skill pack. The --yes flag accepts defaults so it runs non-interactively. You can re-run sciclaw onboard at any time without losing existing settings.

Step 3 — Doctor

sciclaw doctor

doctor checks that everything is wired up correctly: it verifies the config directory exists, all companion tools are reachable on your PATH, skill definitions are valid, and your shell environment is ready. If anything is missing or misconfigured it prints a clear explanation and suggested fix.

Finally, confirm the installed version:

sciclaw --version

On Linux, the tap also installs Quarto for reproducible manuscript rendering. On macOS, install Quarto via brew install --cask quarto. Stable releases auto-update via the GitHub release workflow.

Download a binary

Pre-compiled binaries for Linux (amd64, arm64, riscv64), macOS (arm64), and Windows (amd64) are available on the releases page.

Install from source

git clone https://github.com/drpedapati/sciclaw.git
cd sciclaw
make deps

# Build for your platform
make build

# Or build and install to ~/.local/bin
make install

Updating

Keep sciClaw and its components current.

sciClaw is distributed as a single binary with two bundled sub-components: the IRL runtime (Idempotent Research Loop) and baseline scientific skills. How you update depends on how you installed.

Homebrew (recommended)

If you installed via Homebrew, a single command updates sciClaw and all its dependencies, including the IRL runtime:

brew upgrade sciclaw

This pulls the latest formula from the drpedapati/tap tap, rebuilds the binary, and upgrades the irl dependency if a newer version is available.

Note: on macOS, Quarto is typically installed via a Homebrew cask, so update it separately with brew upgrade --cask quarto.

To check what version you're running before and after:

sciclaw --version
sciclaw status

Binary releases

If you installed from a downloaded binary, replace it with the latest from the releases page. The IRL binary must be updated separately — download it from the IRL releases page and place it on your PATH.

From source

cd sciclaw
git pull
make deps
make install

This rebuilds and reinstalls to ~/.local/bin. For IRL, pull and rebuild its repo separately.

Updating skills

Baseline scientific skills are installed during sciclaw onboard and live in ~/sciclaw/skills/ by default. They are not automatically updated when you upgrade the binary. To refresh them to the latest built-in versions:

# Re-install all built-in skills (overwrites existing)
sciclaw skills install-builtin

# Or re-run onboard to refresh workspace templates + skills
sciclaw onboard

Third-party skills installed from GitHub can be updated by re-installing them:

# Re-install a GitHub skill to get the latest version
sciclaw skills install username/repo/skill-name

Updating configuration

New sciClaw versions may add config fields (like reasoning_effort). Your existing config.json continues to work — new fields use sensible defaults when absent. To see what's available, compare with the default config:

# View current config
sciclaw status

# Check model and provider details
sciclaw models status

Verifying the update

After updating, verify all components are working:

# Check version
sciclaw --version

# Check all components: config, workspace, providers, IRL runtime
sciclaw status

# Verify skills are loaded
sciclaw skills list

# Quick smoke test
sciclaw agent -m "Hello, what version are you?"

Quick Start

From zero to a working paired-scientist assistant in four steps.

1. Initialize

sciclaw onboard

This creates ~/.picoclaw/config.json, scaffolds the workspace at ~/sciclaw/ by default, and installs baseline scientific skills. In interactive mode, onboard also offers a short wizard (optional OpenAI OAuth login, optional PubMed API key, optional chat smoke test). Use sciclaw onboard --yes to skip all prompts.

2. Configure a provider

Edit ~/.picoclaw/config.json with your LLM provider credentials:

{
  "agents": {
    "defaults": {
      "model": "gpt-5.2",
      "max_tokens": 8192,
      "temperature": 0.7
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-..."
    }
  }
}

3. Authenticate (alternative to API keys)

# OpenAI OAuth (device code)
sciclaw auth login --provider openai

# Anthropic token paste
sciclaw auth login --provider anthropic

# Check status
sciclaw auth status

4. Chat

# One-shot
sciclaw agent -m "What pathways are implicated in ALS?"

# Interactive mode
sciclaw agent

That's it. You have a working paired-scientist assistant.

Scientist Setup Guide

The intended workflow for non-technical scientific users: chat in Telegram/Discord, keep an auditable workspace.

What this feels like

You talk to sciClaw in your normal chat app. sciClaw proposes a plan, runs tools, and writes evidence and drafts into a visible workspace folder. You review outputs and iterate.

Recommended setup (Telegram)

1. Install (Homebrew recommended)

brew tap drpedapati/tap && brew install sciclaw

2. Initialize (creates config + workspace + baseline skills)

sciclaw onboard

3. Connect a provider (OAuth for ChatGPT subscribers, or API keys)

# OpenAI OAuth (device code)
sciclaw auth login --provider openai

# Optional: PubMed rate limits (the onboard wizard can save this too)
export NCBI_API_KEY="your-key"

4. Pair Telegram (writes an allowlist so only you can talk to the bot)

sciclaw channels setup telegram

5. Start the gateway (background mode recommended for daily use)

# Background mode
sciclaw service install
sciclaw service start

# Foreground mode
sciclaw gateway

Discord instead of Telegram

Discord setup is also first-class:

sciclaw channels setup discord
sciclaw service install
sciclaw service start

Discord requires enabling MESSAGE CONTENT INTENT in the Developer Portal.

Keep it up to date

brew upgrade sciclaw
sciclaw doctor

If doctor reports missing companion tools (docx-review, pubmed-cli, IRL, ripgrep), install via Homebrew or follow the install hints in the report.

Configuration

All settings live in ~/.picoclaw/config.json.

The config file controls agent defaults, provider credentials, channel integrations, tool settings, and heartbeat behavior. A complete example is shipped at config/config.example.json in the repository.

{
  "agents": {
    "defaults": {
      "workspace": "~/sciclaw",
      "model": "gpt-5.2",
      "reasoning_effort": "high",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": { ... },
  "channels": { ... },
  "tools": {
    "web": {
      "brave": {
        "enabled": true,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      }
    },
    "pubmed": {
      "api_key": "YOUR_NCBI_API_KEY"
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

Providers

sciClaw supports multiple LLM providers. Configure one or more in the providers section.

Authentication

Two paths: paste an API key into config.json, or use the auth commands for OAuth/token flows.

# OpenAI OAuth (device code; default)
sciclaw auth login --provider openai

# Anthropic token paste
sciclaw auth login --provider anthropic

# Check status
sciclaw auth status

# Remove stored credential
sciclaw auth logout --provider openai

Credentials are stored in ~/.picoclaw/auth.json with user-only file permissions. A successful login sets providers.<name>.auth_method in the config (oauth or token).

Workspace Layout

The workspace lives at the path configured in agents.defaults.workspace (default ~/sciclaw).

~/sciclaw/
├── sessions/          # Conversation history
├── memory/            # Long-term memory (MEMORY.md)
├── state/             # Persistent state
├── cron/              # Scheduled jobs database
├── skills/            # Installed skills
├── hooks/             # Hook audit log (hook-events.jsonl)
├── irl/
│   └── commands/      # IRL command execution audit records
├── AGENTS.md          # Agent behavior guide
├── HEARTBEAT.md       # Periodic task prompts
├── HOOKS.md           # Hook policy (plain-language)
├── IDENTITY.md        # sciClaw identity
├── SOUL.md            # Agent values & guardrails
├── TOOLS.md           # Tool descriptions
└── USER.md            # User preferences

Bootstrap templates are versioned at pkg/workspacetpl/templates/workspace/ and also installed to ~/.picoclaw/templates/workspace/ for review and customization.

CLI Reference

Agent

The agent command is the primary way to interact with sciClaw.

# One-shot query
sciclaw agent -m "Summarize recent ALS biomarker literature"

# Interactive session
sciclaw agent

# Override model for one invocation (config unchanged)
sciclaw agent --model gpt-5.2 -m "Quick question"

# Set reasoning effort for GPT-5.2 (quality/latency/cost control)
sciclaw agent --effort high -m "Analyze this complex dataset"

# Combine both overrides
sciclaw agent --model gpt-5.2 --effort xhigh -m "Deep analysis"

In interactive mode the agent maintains session context, uses tools (filesystem, shell, web search, spawn), and follows the paired-scientist loop defined in AGENTS.md.

Model Switching

Previously, switching models required editing ~/.picoclaw/config.json by hand and restarting. sciClaw now supports three ways to change models — a one-shot CLI flag, a persistent subcommand, and the config file. In practice, use gpt-5.2 as the primary path and tune reasoning effort per task.

1. Per-invocation override (--model)

The --model flag overrides the model for a single command. Your config file is not changed, so the next invocation returns to your default. Use this when testing a model, when your primary provider is down, or when a specific task needs a different model.

# Quick task with GPT-5.2 (config unchanged)
sciclaw agent --model gpt-5.2 -m "Summarize this CSV"

# Deep analysis with maximum GPT-5.2 effort
sciclaw agent --model gpt-5.2 --effort xhigh -m "Review this manuscript draft"

# Interactive session with a specific model
sciclaw agent --model gpt-5.2

2. Persistent change (sciclaw models)

The models subcommand lets you inspect and change your default model without opening a text editor.

# See current model, resolved provider, auth method, and effort
sciclaw models status

# List all configured providers and their available models
sciclaw models list

# Switch default model (writes to config.json)
sciclaw models set gpt-5.2
# Output: Model changed: <previous> → gpt-5.2
#         Provider: openai

3. Config file

You can also set the model directly in ~/.picoclaw/config.json. This is the same file that sciclaw models set writes to.

{
  "agents": {
    "defaults": {
      "model": "gpt-5.2",
      "reasoning_effort": "high"
    }
  }
}

You can also use the environment variable PICOCLAW_AGENTS_DEFAULTS_MODEL to override the model, and PICOCLAW_AGENTS_DEFAULTS_REASONING_EFFORT for effort.

Provider auto-detection

sciClaw resolves the provider from the model name automatically. You generally do not need to set agents.defaults.provider explicitly.

If the provider has an API key or OAuth credential configured, the model is routed to it automatically. If you use OpenRouter, any openrouter/-prefixed model works without additional setup.

Reasoning effort

Reasoning effort controls how deeply gpt-5.2 thinks before answering. This is critical because effort directly controls quality, latency, and cost. Without setting it, the provider default is used.

Per-invocation: use --effort to set effort for a single command.

# High reasoning for a complex analysis
sciclaw agent --effort high -m "Analyze the statistical methods in this paper"

# Maximum reasoning for hardest tasks
sciclaw agent --model gpt-5.2 --effort xhigh -m "Prove this theorem"

# Minimal reasoning for fast, cheap responses
sciclaw agent --effort low -m "What day is it?"

Persistent: save a default effort level so you don't have to pass --effort every time.

# Save effort to config.json
sciclaw models effort high

# Check current setting
sciclaw models status
# Output: Model:            gpt-5.2
#         Provider:         openai
#         Auth:             oauth
#         Reasoning Effort: high

Precedence

When multiple sources set the model or effort, the most specific wins:

1. --model / --effort CLI flags (highest priority, single invocation)
2. Environment variables (PICOCLAW_AGENTS_DEFAULTS_MODEL, PICOCLAW_AGENTS_DEFAULTS_REASONING_EFFORT)
3. config.json values (lowest priority, persistent default)

Gateway

The gateway bridges sciClaw to chat channels (Telegram, Discord, Slack, etc.).

sciclaw gateway

It reads channel configuration from config.json, starts listeners for each enabled channel, and routes messages through the agent loop. The heartbeat service also starts with the gateway.

Service

Use service to run the gateway in the background and control lifecycle from one command.

# Install + start background gateway
sciclaw service install
sciclaw service start

# Lifecycle
sciclaw service status
sciclaw service restart
sciclaw service stop
sciclaw service logs --lines 200
sciclaw service uninstall

Backend by platform

• macOS: per-user launchd at ~/Library/LaunchAgents/io.sciclaw.gateway.plist
• Linux: systemd --user unit at ~/.config/systemd/user/sciclaw-gateway.service
• WSL: supported when systemd is enabled in the distro; otherwise run sciclaw gateway in a terminal

Skills

# List installed skills
sciclaw skills list

# Install a skill from a directory or URL
sciclaw skills install ./my-skill

Skills extend the agent with specialized knowledge and workflows. Each skill is a directory containing a SKILL.md with name, description, and instructions.

Doctor

The doctor command verifies your entire sciClaw deployment in one shot — config, workspace, auth credentials, companion CLI tools, baseline skills, gateway health, service health, and Homebrew update status.

# Human-readable report
sciclaw doctor

# Machine-readable output
sciclaw doctor --json

# Auto-fix: sync baseline skills, remove legacy skill names
sciclaw doctor --fix

What it checks

The --fix flag

When --fix is passed, doctor applies safe, non-destructive fixes:

• Syncs baseline skills from the bundled Homebrew share directory to your workspace
• Removes legacy skill directories (docx, pubmed-database) that were replaced by docx-review and pubmed-cli
• Creates a pubmed-cli symlink if only pubmed is found on PATH

Exit code 0 = all checks pass. Exit code 1 = at least one error.

Paired-Scientist Model

sciClaw acts as a research collaborator, not a general-purpose assistant.

Every interaction follows principles of epistemic humility, reproducibility, and evidence-based reasoning. The agent separates hypotheses from verified findings, cites commands and files for every claim, and escalates when evidence is missing or conflicting.

Research Loop

Each iteration follows a four-phase protocol defined in AGENTS.md:

1. Frame — State the question, objective, and hypothesis explicitly.
2. Plan — Propose a reproducible execution plan with specific commands and expected outputs.
3. Execute — Run tools, capture evidence and logs. Prefer idempotent and reversible operations.
4. Record — Update manuscript sections, plan logs, and rendered outputs. Commit together.

Baseline Scientific Skills

During sciclaw onboard, twelve skills are installed into ~/sciclaw/skills/ by default:

Research & Literature

• scientific-writing — Manuscript drafting with claim-evidence alignment
• pubmed-cli — PubMed search, article fetch, citation graphs, MeSH lookup (CLI tool)
• biorxiv-database — bioRxiv/medRxiv preprint surveillance

Authoring & Visualization

• quarto-authoring — Loop-driven .qmd authoring and rendering
• beautiful-mermaid — Publication-grade diagram workflows

Evidence & Provenance

• experiment-provenance — Reproducible experiment evidence capture
• benchmark-logging — Benchmark records with acceptance criteria

Office & Documents

• docx-review — Word documents with tracked changes, comments, and semantic diff (CLI tool)
• pptx — PowerPoint creation and editing
• pdf — PDF creation, merging, splitting, and extraction
• xlsx — Spreadsheet creation, analysis, and conversion

Polish

• humanize-text — Final-pass language polishing for natural tone

Optional Bundled Skill (Manual Install)

• phi-cleaner — Clinical text de-identification helper for PHI-safe sharing workflows (phi-clean CLI)

This skill is bundled with sciClaw and available to the agent. Install the companion CLI only if needed:

brew tap drpedapati/tools
brew install drpedapati/tools/phi-cleaner

Office Tool Repo Migration

Office companion tools were transferred from henrybloomingdale/* to drpedapati/*. If you install those tools directly, use the new tap:

brew tap drpedapati/tools
brew install drpedapati/tools/docx-review
brew install drpedapati/tools/pptx-review
brew install drpedapati/tools/xlsx-review

Companion CLI Tools

Two skills are powered by standalone CLI tools that provide native file format support. Install them alongside sciClaw for full functionality:

brew install drpedapati/tools/docx-review   # Word docs with tracked changes (Open XML SDK)
brew install drpedapati/tools/pubmed-cli     # PubMed search & citation graphs

Skills Catalog

Additional skills are available from the skills catalog:

sciclaw skills install drpedapati/sciclaw-skills/<skill-name>

The skills installer validates all content before writing to disk: size limits (256KB per skill), binary content rejection, YAML frontmatter validation, and SHA-256 provenance logging.

IRL Integration

The Idempotent Research Loop manages the project lifecycle layer that sits above sciClaw's per-loop reproducibility.

sciClaw enforces rigor inside each research loop — evidence capture, manuscript updates, plan logs. But what about the layer above? Creating new projects, organizing them consistently, rediscovering past work, and switching context between studies. That's where IRL comes in.

Why IRL

Without project lifecycle management, common problems accumulate:

• Project sprawl — Research directories pile up with inconsistent names and scattered locations. Finding last month's ERP analysis means grepping through your home directory.
• Boilerplate friction — Every new study starts with the same manual work: creating directories, plan files, config, and manuscript scaffolding before the real work begins.
• Lost context — The agent has no structured way to discover what projects exist or switch between them. You end up pasting paths manually.
• No adoption path — Existing messy folders can't be retroactively brought under management without starting over.

IRL solves these by providing a thin, idempotent project lifecycle layer:

• Auto-named, datestamped projects — irl init "ERP correlation analysis" creates a consistent 260214-erp-correlation-analysis/ directory with plans, data, and manuscript scaffolding built in.
• Discoverability — irl list --json gives the agent a structured view of all managed projects for context-switching without remembering paths.
• Adopt existing work — irl adopt ./messy-folder brings existing directories under management without starting over.
• Templates — Different study types get different scaffolding from day one.
• Safe by default — Operations are idempotent and non-destructive. No accidental overwrites, explicit flags for renames.

How It Works in sciClaw

IRL is bundled as a Homebrew dependency — when you install sciClaw, irl is installed alongside it automatically. There is no sciclaw irl subcommand. Instead, the agent mediates all IRL interactions internally, shelling out to the irl binary and consuming its machine-readable outputs.

Four operations are available through the agent:

You interact with these through natural conversation with the agent. For example:

sciclaw agent -m "Create a new project for ERP correlation analysis"

sciclaw agent -m "What projects do I have?"

sciclaw agent -m "Adopt my old als-biomarker folder as a managed project"

To verify IRL is available:

sciclaw status
# Output includes: IRL Runtime: ✓ /opt/homebrew/bin/irl

Provenance

Every IRL command the agent executes is recorded as a timestamped JSON entry in ~/sciclaw/irl/commands/ by default. Each record captures:

• Full command argv and working directory
• Timestamp and IRL version
• stdout, stderr, and exit code
• Parsed payload (for JSON-returning commands)
• Normalized status (success, failure, partial)
• Correlation IDs linking to unified runtime logs

# View recent IRL command records
ls ~/sciclaw/irl/commands/

The command store is append-only audit material — no in-place mutation. This gives you a complete trail of every project created, adopted, or discovered through the agent.

Chat Channels

Talk to sciClaw through your preferred messaging app.

Telegram

1. Create a bot — Open Telegram, search @BotFather, send /newbot, and copy the token.

2. Run the setup wizard

sciclaw channels setup telegram

The wizard prompts for your bot token, then pairs your account by asking you to message the bot once. It will add your user to allow_from automatically (recommended).

Manual config (advanced)

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

3. Run

# Always-on background mode (recommended)
sciclaw service install
sciclaw service start

# Or foreground mode
sciclaw gateway

Discord

1. Go to discord.com/developers and create an application.
2. In Bot settings, enable MESSAGE CONTENT INTENT.
3. Copy the bot token.
4. Get your User ID (Developer Mode → right-click avatar → Copy User ID).
5. Run the setup wizard:

sciclaw channels setup discord

Run

# Always-on background mode (recommended)
sciclaw service install
sciclaw service start

# Or foreground mode
sciclaw gateway

6. Generate an invite URL via OAuth2 (scopes: bot; permissions: Send Messages, Read Message History).
7. Use sciclaw service status to confirm the gateway is running in background mode.

Hooks

Lifecycle hooks let you capture context, enforce policy, and build an audit trail at every stage of the agent loop.

sciClaw fires hooks at seven points in the agent lifecycle. Each hook receives an immutable snapshot of the current turn — session, channel, tool call, LLM response — and returns a result that is written to the audit log.

Two built-in handlers ship by default:

• policy — Reads HOOKS.md and hooks.yaml from your workspace, enables/disables events, and injects per-event instructions.
• provenance — Records normalized event metadata (turn ID, session, tool name) for reproducibility.

Events

Each handler receives a Context snapshot containing the turn ID, session key, channel, model, user message, tool name/args/result, LLM response summary, and error message as applicable.

Policy

Hook behavior is configured through workspace files. The policy loader checks two sources in order:

1. HOOKS.md — Plain-language instructions per event, written so non-technical users can maintain them.
2. hooks.yaml — Structured policy with per-event enable/disable, verbosity levels, capture fields, and redaction keys.

Example HOOKS.md (installed during sciclaw onboard):

## before_turn
- Capture project context needed for reproducibility.

## after_turn
- Summarize completed actions and unresolved risks.
- Record what should be updated in manuscript and logs.

## before_tool
- Record the intent of the tool call and key parameters (redacting secrets).

## after_tool
- Record tool outcomes and where artifacts were written.

## on_error
- Capture failure context, likely cause, and the next recovery step.

The default policy automatically redacts sensitive fields: api_key, token, secret, authorization, and password.

Audit Log

Every hook execution is appended to a JSONL audit log at hooks/hook-events.jsonl inside your workspace. Each entry records:

• Turn ID, event name, and handler name
• Status (ok or error) and duration in milliseconds
• Session key, channel, and chat ID
• Handler-specific metadata and any error messages

# View recent hook events
tail -5 ~/sciclaw/hooks/hook-events.jsonl | jq .

The audit log is designed for reproducibility — every claim the agent makes can be traced back to the tool calls and LLM responses that produced it.

Heartbeat

Automatic periodic tasks, checked every 30 minutes (disabled by default).

Create a HEARTBEAT.md file in your workspace with tasks the agent should execute periodically:

# Periodic Tasks

## Quick Tasks (respond directly)
- Report current time

## Long Tasks (use spawn for async)
- Search the web for AI news and summarize
- Check email and report important messages

For long-running work, the agent uses the spawn tool to create async subagents that run independently and communicate results via the message tool.

{
  "heartbeat": {
    "enabled": false,
    "interval": 30
  }
}

Override via environment variables: PICOCLAW_HEARTBEAT_ENABLED=false or PICOCLAW_HEARTBEAT_INTERVAL=60.

Scheduled Tasks

sciClaw supports cron-style scheduled tasks for reminders and recurring jobs.

• One-time reminders — "Remind me in 10 minutes"
• Recurring tasks — "Remind me every 2 hours"
• Cron expressions — "Remind me at 9am daily"

sciclaw cron list
sciclaw cron add "Check email" --every 2h

Jobs are stored in ~/sciclaw/cron/ by default and processed automatically by the gateway.

Docker

Run sciClaw in Docker without installing anything locally.

# Clone and configure
git clone https://github.com/drpedapati/sciclaw.git
cd sciclaw
cp config/config.example.json config/config.json

# Start gateway mode
docker compose --profile gateway up -d

# Or run agent one-shot
docker compose run --rm sciclaw-agent -m "Hello"

# Check logs
docker compose logs -f sciclaw-gateway

# Stop
docker compose --profile gateway down

The Docker image uses a multi-stage build (Go builder → Alpine) and ships with all baseline skills pre-installed.