github.com/drpedapati/sciclaw @v0.3.4

A paired-scientist agent for reproducible research workflows.

Website · Documentation · Manuscript (pending arXiv submission #7284050) · YouTube Tutorial · Releases · Discord · Discussions

📬 Get email updates — occasional release notes, no spam.

sciClaw is a paired-scientist agent for rigorous research work. It connects to major LLM providers, proposes and executes hypothesis-driven loops, runs real tools (literature, documents, shell), and keeps an auditable evidence trail in your workspace.

Built on the PicoClaw runtime (a Go rewrite of nanobot), sciClaw keeps a single-binary footprint while adding a paired-scientist operating model: plan, evidence, review, iterate.

How You Talk to sciClaw

The most natural way to use sciClaw is through Telegram or Discord. You message it like you'd message a colleague. Ask a question, attach a file, get results back. No terminal, no special syntax.

You:      "Find recent papers on TDP-43 proteinopathy in ALS"
sciClaw:  [searches PubMed, returns 47 papers with citations, saves to workspace]

You:      "Draft a methods section using the attached protocol"
sciClaw:  [produces a Word doc with tracked changes you review in Microsoft Word]

New users should follow Quick Start below for the canonical setup path (install -> initialize -> authenticate -> connect chat).

Prefer a visual interface? Run sciclaw app to open an interactive dashboard in your terminal — no CLI knowledge needed. A CLI is also available for power users: sciclaw agent -m "your question" or sciclaw agent for interactive mode.

Discord on current main/dev builds also supports: - queued background jobs with status/cancel cards - /btw for explicit read-only side questions in the current workspace - /skill with workspace-aware autocomplete for explicit skill use - /theme to pick a response style (Clear, Formal, or Brief) that persists per user across sessions

Addons

Addons are optional capabilities installed separately from the core binary. Each addon is a standalone repo with a manifest, a sidecar binary, and optional install scripts. The gateway reconciler spawns addon sidecars automatically and keeps them in sync.

Two reference addons ship under the sciclaw org (private repos): - sciclaw-addon-webtop: per-user Ubuntu XFCE browser desktops via Docker. - sciclaw-addon-jupyter: per-user Jupyter Lab servers with rotating token auth.

Addons share the same workspace and user identity as your chat channels. Install with:

sciclaw addon install <url> --version v0.1.0

Ten lifecycle commands: install, enable, disable, uninstall, upgrade, verify, rollback, sbom, list, status. The web UI injects sidebar tabs for each enabled addon. See the dev log for implementation details.

Install

Homebrew (recommended)

brew tap drpedapati/tap && brew install sciclaw

Install surfaces are split intentionally: - sciclaw.dev is the website and documentation - drpedapati/sciclaw is the source repo and release binaries - drpedapati/tap is the Homebrew tap for sciclaw, sciclaw-dev, irl, and sciclaw-* companion formulas - drpedapati/tools is the Homebrew tap for standalone tools like docx-review, pubmed-cli, pdf-form-filler, and phi-cleaner

If you still have the old legacy tap installed, remove it to avoid ambiguity:

brew untap drpedapati/sciclaw

Homebrew (development channel)

brew tap drpedapati/tap && brew install sciclaw-dev

sciclaw-dev tracks development branch releases. If stable sciclaw is already installed, uninstall it first to avoid binary name collisions.

macOS only:

brew install --cask quarto

Download a binary

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

From source

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

Homebrew pulls companion tools automatically (ImageMagick, IRL, ripgrep, docx-review, xlsx-review, pptx-review, pubmed-cli). For binary/source installs, run sciclaw doctor for hints. VM/bootstrap provisioning uses deploy/toolchain.env and installs the same core review companions.

After any install method, initialize once:

# Recommended: interactive app with first-run setup wizard
sciclaw app

# CLI alternative (headless/non-TUI)
sciclaw onboard

Quick Start

1. Initialize — choose one:

# Recommended: launches the app and starts first-run setup
sciclaw app

# CLI alternative (headless/non-TUI)
sciclaw onboard

2. Authenticate with your AI provider:

sciclaw auth login --provider openai     # OAuth device code — works with your ChatGPT account
sciclaw auth login --provider anthropic  # Token paste

# Optional: import from 1Password item JSON (requires OP_SERVICE_ACCOUNT_TOKEN)
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
sciclaw auth import-op --provider openai --item "OpenAI Credentials"
sciclaw auth import-op --provider anthropic --item "Anthropic Token" --vault "AI" --auth-method token

3. Connect a chat app and start messaging:

sciclaw channels setup telegram
sciclaw service install && sciclaw service start

See Authentication docs for all providers. See Chat Channels below for Telegram and Discord setup details.

Security

sciClaw's default posture is local, private, and locked down. Here's what that means in practice:

• Runs on your machine. sciClaw is a program on your computer, not a cloud service. There's no account to create with us, no server to connect to, nothing hosted anywhere.
• Your data stays in one folder. Everything sciClaw produces lives in ~/sciclaw — a folder on your machine that you own and control. You can open it, back it up, or delete it anytime.
• Nothing is exposed to the internet. sciClaw doesn't open any ports or listen for incoming connections. It reaches out only when you send a message, and only to the AI provider you chose (OpenAI, Anthropic, etc.) and any tools you explicitly enable (like PubMed).
• Messages go through your private bot. When you chat via Telegram or Discord, messages travel through a bot that only you control. Nobody else can talk to it unless you explicitly allow them.
• No telemetry, no analytics, no tracking. sciClaw sends nothing back to us. No usage data, no error reports, no phone-home behavior. We don't know you're running it.
• API keys stay local. Your credentials are stored in a config file on your machine (~/.picoclaw/config.json). They're never transmitted to anyone except the provider they belong to.
• Skills are validated before install. Every skill goes through size limits, binary rejection, frontmatter validation, and SHA-256 provenance logging. Catalog fetches use pinned commit refs for supply-chain hardening.

For the full security model, see Security.

Providers

sciClaw auto-detects the provider from the model name. Set credentials via the onboard wizard or sciclaw auth login.

Groq provides free voice transcription via Whisper. When configured, Telegram voice messages are automatically transcribed.

Built-in Skills

Bundled skills include:

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
• pandoc-docx — Clean .docx manuscript generation from Markdown with NIH template auto-apply
• imagemagick — Reproducible image preprocessing (resize, crop, convert, DPI normalization) via magick
• beautiful-mermaid — Publication-grade Mermaid diagrams
• explainer-site — Technical, single-page "How X Works" explainer site generation

Evidence & Provenance

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

Office & Documents

• docx-review — Word tracked-change review, comments, semantic diff, and template population (--create, v1.3.0+) (CLI tool)
• For clean first-draft Word output, use pandoc ... -o file.docx; sciClaw injects --defaults <generated-file> at runtime to apply a bundled NIH reference template (no global ~/.pandoc/defaults.yaml required).
• acroform-fill — Fill structured PDF/AcroForm fields safely from typed inputs
• 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

• phi-cleaner — Clinical text de-identification for PHI-safe sharing (brew install drpedapati/tools/phi-cleaner)

Additional skills: skills catalog — install with sciclaw skills install drpedapati/sciclaw-skills/<name>

Chat Channels

Telegram and Discord are the recommended way to interact with sciClaw. You message it from the app you already have open. When the agent generates deliverables (for example .docx), it can now send real file attachments back through Discord/Telegram via the message tool.

Discord-specific features on current main/dev builds: - background jobs for long-running requests, with queue-aware progress cards - /btw slash command for read-only side questions in the same workspace - /skill slash command with workspace-aware skill autocomplete - /theme slash command to pick Clear, Formal, or Brief response styles (persists per user)

Telegram setup (easiest)

1. Open Telegram, search @BotFather, send /newbot, copy the token
2. Run sciclaw channels setup telegram (pairs your account and writes config)
3. Start the gateway: sciclaw service install && sciclaw service start

Manual config (advanced) in ~/.picoclaw/config.json:

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

Discord setup

1. Create app at discord.com/developers
2. Enable MESSAGE CONTENT INTENT in Bot settings
3. Copy bot token, get your User ID (Developer Mode → right-click → Copy User ID)
4. Run sciclaw channels setup discord or add to config manually
5. Generate invite URL (scopes: bot; permissions: Send Messages, Read Message History)
6. Start the gateway: sciclaw service install && sciclaw service start

Background service (recommended — keeps sciClaw running):

sciclaw service install    # register with launchd (macOS) or systemd (Linux)
sciclaw service start
sciclaw service status     # check it's running

For long-running Discord work, sciClaw now keeps the channel responsive: - one main job runs per workspace - additional main jobs queue instead of being silently downgraded - /btw stays read-only and does not mutate the workspace

Platform notes: - macOS: per-user launchd (~/Library/LaunchAgents/io.sciclaw.gateway.plist) - Linux: systemd --user (~/.config/systemd/user/sciclaw-gateway.service) - WSL: service mode works when systemd is enabled; otherwise sciclaw gateway in a terminal

Collaborative Routing (Channel -> Workspace)

Give each project its own chat room. Routing maps a Discord or Telegram channel to a specific data folder so the agent only sees that project's files — while still having access to your shared personality, skills, and memory from ~/sciclaw.

Mention to activate. In routed channels the bot stays quiet unless someone @mentions it, so collaborators can talk freely without triggering responses. DMs always work without a mention.

Example:

```bash sciclaw routing add \