sciclaw

---

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:      "Image, generate a schematic of TDP-43 condensate formation under stress"
sciClaw:  [generates a figure via OpenAI image gen, saves it, attaches the PNG in chat]

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.

Provider	Models	Auth
OpenAI	gpt-5.6-sol (primary @ low), gpt-5.6-terra (cheaper peer), gpt-5.5, gpt-5.4, gpt-5.2	API key or device-code OAuth
Anthropic	claude-sonnet-4.6, claude-opus-4-6, claude-haiku-4-5-20251001	API key, token paste, or Claude.ai oat-token bridge
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

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
• Chat image generation — On OpenAI Codex/OAuth + GPT-5.x, ask “Image, generate …” to create figures via the Responses image_generation tool; PNGs are saved under artifacts/generated/ and attached in Discord/Telegram
• 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:

sciclaw routing add \
  --channel discord \
  --chat-id 123456789012345678 \
  --workspace /absolute/path/to/project-a \
  --allow 987654321098765432,123456789012345678 \
  --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 123456789012345678 \
  --workspace /absolute/path/to/project-a \
  --allow 987654321098765432 \
  --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:

• GitHub releases: https://github.com/drpedapati/sciclaw/releases
• local history: git log --oneline v0.2.3..HEAD
• current binary: sciclaw --version

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 web	Open the web management UI (routing, system config)
sciclaw prompt inspect --session <key>	Token/turn breakdown of a session's prompt
sciclaw cron list|add	Manage scheduled jobs

ctxclaw

ctxclaw is a standalone context-window optimizer installed automatically with sciClaw. It sits between the agent runtime and the model, compressing stale history to reclaim tokens in long-running sessions. Use sciclaw prompt inspect to see where tokens are going before optimizing. See docs for details.

License

MIT — see LICENSE.

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