Skip to content

drpedapati/sciclaw

BranchesTags

Repository files navigation

sciClaw: A Partnership, Not a Platform

A paired-scientist agent for reproducible research workflows.

Go Platforms License

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

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.

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.

Provider Models Auth
OpenAI gpt-5.2 (primary), gpt-5.2-chat-latest, gpt-5.2-pro API key or device-code OAuth
Anthropic claude-opus-4-6, claude-sonnet-4-5 API key or token paste
Gemini gemini-2.5-pro, gemini-2.5-flash API key
OpenRouter All models via openrouter/ prefix API key
DeepSeek deepseek-chat, deepseek-reasoner API key
Groq Fast inference + Whisper voice transcription API key
Zhipu GLM models API key

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

Built-in Skills

Fifteen skills are installed during sciclaw onboard:

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).
  • 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.

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

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:

sciclaw routing add \
  --channel discord \
  --chat-id 1467290563052048476 \
  --workspace /absolute/path/to/project-a \
  --allow 8535331528,1467290563052048476 \
  --label project-a

sciclaw routing enable
sciclaw routing validate
sciclaw routing reload

To let the bot respond to every message (no @mention needed), add --no-mention:

sciclaw routing add \
  --channel discord \
  --chat-id 1467290563052048476 \
  --workspace /absolute/path/to/project-a \
  --allow 8535331528 \
  --no-mention

Useful operations:

  • sciclaw routing status
  • sciclaw routing list
  • sciclaw routing explain --channel <channel> --chat-id <id> --sender <id> [--mention] [--dm]
  • sciclaw routing set-users --channel <channel> --chat-id <id> --allow <id1,id2>
  • sciclaw routing remove --channel <channel> --chat-id <id>
  • sciclaw routing export --out routing.json / sciclaw routing import --in routing.json [--replace]

Session isolation is namespaced as <channel>:<chat_id>@<workspace_hash> to prevent cross-workspace context bleed. Each routed workspace gets its own sessions, memory, and state, but inherits your personality files (AGENTS.md, SOUL.md, etc.) and skills from the shared workspace (~/sciclaw).

IRL Integration

sciClaw integrates with IRL (Idempotent Research Loop) for project lifecycle management. IRL is installed automatically as a Homebrew dependency.

The agent manages projects through natural conversation:

sciclaw agent -m "Create a new project for ERP correlation analysis"
sciclaw agent -m "What projects do I have?"

Every IRL command is recorded in ~/sciclaw/irl/commands/ for auditability.

Workspace Layout

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

Docker

git clone https://github.com/drpedapati/sciclaw.git && cd sciclaw
cp config/config.example.json config/config.json   # edit with your credentials
docker compose --profile gateway up -d              # gateway mode
docker compose run --rm sciclaw-agent -m "Hello"    # one-shot

The Docker image is a full runtime and includes: python3, uv, ripgrep, imagemagick, pandoc, quarto, docx-review, xlsx-review, pptx-review, pubmed-cli, and irl.

Troubleshooting

Run sciclaw doctor to diagnose issues — it checks config, auth, tools, skills, gateway, and service health.

sciclaw doctor            # human-readable report
sciclaw doctor --fix      # auto-fix common issues
Common issues

"no credentials for openai/anthropic"

sciclaw auth login --provider openai

Telegram "Conflict: terminated by other getUpdates" — only one gateway instance can run at a time:

sciclaw service restart

Web search "API configuration problem" — get a free key at brave.com/search/api and add to config under tools.web.search.api_key.

Updating

brew upgrade sciclaw     # update the binary
sciclaw onboard          # refresh skills to latest
sciclaw doctor           # verify everything

Release Notes

The old curated patch ledger was removed because it kept drifting behind the codebase.

Current sources of truth:

CLI reference
Command Description
sciclaw app Open the graphical dashboard (alias: tui)
sciclaw onboard Initialize config, workspace, and baseline skills
sciclaw agent -m "..." One-shot message
sciclaw agent Interactive chat
sciclaw agent --model <m> Override model
sciclaw agent --effort <level> Set reasoning effort (none through xhigh)
sciclaw models list Show current model and providers
sciclaw models set <model> Change default model
sciclaw models effort <level> Change default effort
sciclaw status System status
sciclaw doctor Verify deployment
sciclaw doctor --fix Auto-fix common issues
sciclaw gateway Start chat gateway
sciclaw service install|start|stop|restart|logs|uninstall Manage background service
sciclaw channels setup <channel> Configure a chat channel
sciclaw auth login|logout|status|import-op Manage credentials
sciclaw skills list|install Manage skills
sciclaw cron list|add Manage scheduled jobs

License

MIT — see LICENSE.

sciClaw is a fork of PicoClaw by Sipeed, which is based on nanobot by HKUDS.

About

Paired-scientist AI assistant for reproducible research — lightweight Go runtime, lifecycle hooks, manuscript integration, 12 baseline scientific skills. PicoClaw-compatible.

sciclaw.dev

Topics

golang reproducible-research lifecycle-hooks quarto scientific-workflow ai-assistant paired-programming llm picoclaw sciclaw

Resources

Readme

License

View license
Activity

Stars

5 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 142

v0.2.3 Latest
Mar 11, 2026
+ 141 releases

Packages

 
 
 

Contributors

Languages