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

A paired-scientist agent for reproducible research workflows.

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]

After install, connect a chat app and start the gateway:

sciclaw channels setup telegram    # or: sciclaw channels setup discord
sciclaw service install && sciclaw service start

That's it. sciClaw runs in the background and responds to your messages. See the Scientist Setup Guide for a walkthrough.

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

Then run the interactive setup wizard:

sciclaw onboard

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, pubmed-cli). For binary/source installs, run sciclaw doctor for hints.

Quick Start

1. Initialize — the wizard walks you through everything:

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

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)

Open Telegram, search @BotFather, send /newbot, copy the token
Run sciclaw channels setup telegram (pairs your account and writes config)
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

Create app at discord.com/developers
Enable MESSAGE CONTENT INTENT in Bot settings
Copy bot token, get your User ID (Developer Mode → right-click → Copy User ID)
Run sciclaw channels setup discord or add to config manually
Generate invite URL (scopes: bot; permissions: Send Messages, Read Message History)
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

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

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

sciClaw Fork Patch Changelog (Curated)

This is a curated, code-grounded changelog of sciClaw-specific patches on top of upstream PicoClaw.

Source of truth:

git log --oneline upstream/main..main

Last refreshed:

2026-02-19

Identity, Workspace, and Baseline Skilling

1028a75 Dual-binary rebrand (sciclaw primary, picoclaw alias) (cmd/picoclaw/main.go, Makefile).
116dba4 Rebranded CLI display surfaces while preserving picoclaw compatibility (cmd/picoclaw/main.go).
411ec69 Added git commit hash to runtime version output (cmd/picoclaw/main.go, Makefile).
d4b4d2f Switched default workspace to visible ~/sciclaw and updated migration behavior (pkg/config/config.go, pkg/migrate/config.go).
f7db953 Externalized workspace bootstrap templates via embed for predictable onboarding (pkg/workspacetpl/templates.go, pkg/workspacetpl/templates/workspace/).
d577877 Added baseline science-skill policy and auto-install on onboard (cmd/picoclaw/main.go, pkg/workspacetpl/templates/workspace/AGENTS.md).
70dc430 Replaced old docx / pubmed-database skills with CLI-powered docx-review / pubmed-cli flows (skills/docx-review/SKILL.md, skills/pubmed-cli/SKILL.md).
3f64ec6 Added baseline pandoc-docx skill for NIH-templated Word drafting (skills/pandoc-docx/SKILL.md, cmd/picoclaw/main.go).
c3f8f90 Added explainer-site as baseline onboard skill (skills/explainer-site/SKILL.md, cmd/picoclaw/main.go).
8c19e46 Added imagemagick as baseline skill plus runtime/packaging dependency checks (skills/imagemagick/SKILL.md, cmd/picoclaw/doctor_cmd.go, deploy/update-tap.sh).
c49ede1 Added optional phi-cleaner skill for PHI de-identification workflows (skills/phi-cleaner/SKILL.md, README.md).

Providers, OAuth, and Cloudflare/NAT Resilience

349af96 Added --model and --effort, plus sciclaw models subcommands and reasoning-effort wiring (cmd/picoclaw/main.go, pkg/models/models.go).
fee0fc5 Changed default model lineage to GPT-5.2 (pkg/models/models.go, config/config.example.json).
2f0f059 Added Azure OpenAI endpoint/provider support (pkg/providers/azure_provider.go, pkg/config/config.go).
f9819bf Made OpenAI auth login device-code-first and reduced browser-flow friction (cmd/picoclaw/main.go).
6d6d23c Added OAuth retries and TLS tuning for VM/NAT stability (pkg/auth/oauth.go).
36511b2 Capped OAuth auth transport at TLS 1.2 during Cloudflare-reset mitigation (pkg/auth/oauth.go).
ad5970f Added Chrome-like uTLS client fingerprinting for OAuth reliability behind restrictive networks (pkg/auth/oauth.go).
b19da1e Added Cloudflare-focused transport path (uTLS + compression) for Codex/API access hard cases (pkg/auth/oauth.go, pkg/providers/codex_provider.go, pkg/providers/http_provider.go).
f4cb049 Restored TLS 1.2 floor and scoped custom transport to Cloudflare-only paths to avoid broader regression (pkg/transport/transport.go, pkg/providers/http_provider.go).

Tool Execution, Guardrails, and Document Pipeline

2f57030 Hardened skill installer with size limits, text validation, and provenance checks (pkg/skills/installer.go, pkg/skills/installer_test.go).
65be47a Enforced CLI-first workspace policy and reduced guard false positives (cmd/picoclaw/tools_policy.go, pkg/tools/shell.go).
39baacd Fixed heredoc URL payload false positives in shell safety guard (pkg/tools/shell.go).
eeb3928 Allowed PubMed field-tag query forms through path guard (pkg/tools/shell.go).
7ef63f0 Relaxed path guard for safe temp outputs and /dev/null workflows (pkg/tools/shell.go).
6b7ad2e Removed default hard task-iteration cap (0 = unbounded) for long scientific jobs (pkg/agent/loop.go, pkg/tools/toolloop.go).
155b861 Added automatic NIH template application for pandoc DOCX generation (pkg/tools/shell.go, cmd/picoclaw/tools_policy.go).
eb45a38 Decoupled NIH pandoc template from docx-review and aligned docs/policy (pkg/tools/assets/nih-standard.docx, pkg/tools/shell.go, pkg/workspacetpl/templates/workspace/TOOLS.md).
f7aeb98 Switched to pandoc --defaults injection for robust template application (pkg/tools/shell.go, pkg/tools/shell_test.go).

Channels and Agent Output UX

cb566d5 Added first-class channel setup wizard for Telegram/Discord (cmd/picoclaw/channels_cmd.go).
1f313e2 Enforced Discord allowlist-first onboarding and confirmation before save (cmd/picoclaw/channels_cmd.go).
73711b2 Added Discord typing indicator support (pkg/channels/discord.go).
2ba9543 Added Discord long-response chunking and scientific export/count tools (pkg/channels/discord.go, pkg/tools/pubmed_export.go, pkg/tools/word_count.go).
87f8b67 Added message-tool attachment support over Discord/Telegram channels (pkg/tools/message.go, pkg/channels/discord.go, pkg/channels/telegram.go).
b800cac Improved Telegram attachment routing and expanded adapter attachment tests (pkg/channels/telegram.go, pkg/channels/telegram_test.go).
d33e77e Made onboard reruns idempotent and added docs-linked guidance (cmd/picoclaw/main.go).
b8c456a Made onboard next-step messaging dynamic from real setup state (cmd/picoclaw/main.go).

Service Lifecycle, Doctor, and Homebrew Delivery

4f1bf53 Introduced sciclaw doctor for deployment verification (cmd/picoclaw/doctor_cmd.go).
774fb96 Added doctor install hints for missing dependencies (cmd/picoclaw/doctor_cmd.go).
452aba0 Reduced false Telegram 409 conflict reports in doctor checks (cmd/picoclaw/doctor_cmd.go).
63ca0ef Added service lifecycle command (install/start/stop/restart/logs) with launchd/systemd support (cmd/picoclaw/service_cmd.go, pkg/service/).
3b8eac2 Added service refresh and doctor stale executable-path auto-fix logic (cmd/picoclaw/service_cmd.go, cmd/picoclaw/doctor_service_path_test.go).
81e0073 Added Homebrew post-upgrade service auto-refresh with caveat fallback (deploy/update-tap.sh, .github/workflows/release.yml).
df478a6 Fixed systemd user service PATH handling for Homebrew-installed tools (pkg/service/systemd_linux.go, pkg/service/path.go).
7060db0 Bound service install to stable PATH-resolved binary to survive upgrades (cmd/picoclaw/service_cmd.go).
0310233 Bootstrapped Linux workspace Python environment with uv and service PATH wiring (cmd/picoclaw/python_setup.go, cmd/picoclaw/service_cmd.go).
b37030f Added local release pipeline target for faster binary + tap publishing (Makefile, deploy/update-tap.sh).
a1192fc Switched Homebrew formula generation to pre-compiled binary distribution path (.github/workflows/release.yml).

Security and IRL Integration

61b15cd Blocked symlink-based workspace escape paths in filesystem tooling (pkg/tools/filesystem.go, pkg/tools/filesystem_test.go).
ce7d05b Tightened file permissions and enforced Slack ACL checks (pkg/channels/slack.go, pkg/config/config.go, cmd/picoclaw/main.go).
f19420b Tightened config/channel state handling and disabled heartbeat default for safer baseline posture (pkg/config/config.go, pkg/channels/base.go).
4095251 Pinned skills catalog ref and hardened QQ dedup cache handling (pkg/skills/installer.go, pkg/channels/qq.go).
449ed15 Added external IRL adapter with command-store auditing (pkg/irl/client.go, pkg/irl/store.go).
d3b7078 Added internal irl_project tool for agent-mediated IRL workflows (pkg/tools/irl_project.go, pkg/agent/loop.go).
d691b11 Added cross-platform IRL binary fallback resolution (pkg/irl/client.go).
be9cd3d Added IRL project-list fallback behavior when JSON/list commands fail (pkg/irl/client.go).
e6e8ff3 Made runtime IRL status detection independent of PATH assumptions (cmd/picoclaw/main.go, pkg/irl/client.go).

Docs and Scientist UX Surfaces

65f032e Overhauled landing page for non-technical academic/scientist audience (docs/index.html).
ed9ca89 Shifted docs/landing to messaging-first setup framing (docs/index.html).
6a8e442 Added dedicated security page and restructured README around messaging-first operations (docs/security.html, README.md).
af32c3d Unified top navigation across docs surfaces for consistency (docs/index.html, docs/docs.html, docs/philosophy.html, docs/biography.html).

CLI reference

Command	Description
`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\|status`	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.

Name		Name	Last commit message	Last commit date
Latest commit History 373 Commits
.github/workflows		.github/workflows
cmd/picoclaw		cmd/picoclaw
config		config
deploy		deploy
docs		docs
pkg		pkg
skills		skills
vendor		vendor
workspace		workspace
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
spec.md		spec.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

How You Talk to sciClaw

Install

Homebrew (recommended)

Download a binary

From source

Quick Start

Security

Providers

Built-in Skills

Research & Literature

Authoring & Visualization

Evidence & Provenance

Office & Documents

Polish

Optional

Chat Channels

IRL Integration

Workspace Layout

Docker

Troubleshooting

Updating

sciClaw Fork Patch Changelog (Curated)

Identity, Workspace, and Baseline Skilling

Providers, OAuth, and Cloudflare/NAT Resilience

Tool Execution, Guardrails, and Document Pipeline

Channels and Agent Output UX

Service Lifecycle, Doctor, and Homebrew Delivery

Security and IRL Integration

Docs and Scientist UX Surfaces

License

About

Uh oh!

Releases 25

Packages

Contributors 5

Languages

License

drpedapati/sciclaw

Folders and files

Latest commit

History

Repository files navigation

How You Talk to sciClaw

Install

Homebrew (recommended)

Download a binary

From source

Quick Start

Security

Providers

Built-in Skills

Research & Literature

Authoring & Visualization

Evidence & Provenance

Office & Documents

Polish

Optional

Chat Channels

IRL Integration

Workspace Layout

Docker

Troubleshooting

Updating

sciClaw Fork Patch Changelog (Curated)

Identity, Workspace, and Baseline Skilling

Providers, OAuth, and Cloudflare/NAT Resilience

Tool Execution, Guardrails, and Document Pipeline

Channels and Agent Output UX

Service Lifecycle, Doctor, and Homebrew Delivery

Security and IRL Integration

Docs and Scientist UX Surfaces

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 25

Packages 0

Contributors 5

Languages

Packages