Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/drpedapati/sciclaw

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

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

Last synced: 28 days ago
JSON representation

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

Awesome Lists containing this project

README 

          



sciClaw: A Partnership, Not a Platform







**A paired-scientist agent for reproducible research workflows.**



[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white)](https://go.dev)

[![Platforms](https://img.shields.io/badge/Platforms-macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-blue)](https://github.com/drpedapati/sciclaw/releases)

[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

[![Discord](https://img.shields.io/discord/1488473301889191977?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/UwGGGqU7yf)



[Website](https://sciclaw.dev) ·

[Documentation](https://sciclaw.dev/docs.html) ·

[Manuscript (pending arXiv submission #7284050)](docs/assets/sciclaw-arxiv.pdf) ·

[YouTube Tutorial](https://www.youtube.com/watch?v=P3pDulPnCzU) ·

[Releases](https://github.com/drpedapati/sciclaw/releases) ·

[Discord](https://discord.gg/UwGGGqU7yf) ·

[Discussions](https://github.com/drpedapati/sciclaw/discussions)



📬 [**Get email updates**](https://list.sciclaw.dev/subscription/form) — 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](https://github.com/sipeed/picoclaw) runtime (a Go rewrite of [nanobot](https://github.com/HKUDS/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](#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:



```bash

sciclaw addon install  --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](docs/devlog.html) for implementation details.



## Install



### Homebrew (recommended)



```bash

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:



```bash

brew untap drpedapati/sciclaw

```



### Homebrew (development channel)



```bash

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:

```bash

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](https://github.com/drpedapati/sciclaw/releases).



### From source



```bash

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:

```bash

# Recommended: interactive app with first-run setup wizard

sciclaw app



# CLI alternative (headless/non-TUI)

sciclaw onboard

```



## Quick Start



**1. Initialize** — choose one:



```bash

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

sciclaw app



# CLI alternative (headless/non-TUI)

sciclaw onboard

```



**2. Authenticate** with your AI provider:



```bash

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:



```bash

sciclaw channels setup telegram

sciclaw service install && sciclaw service start

```



See [Authentication docs](https://sciclaw.dev/docs.html#authentication) for all providers. See [Chat Channels](#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](https://sciclaw.dev/security.html).



## 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.5, gpt-5.2 (primary), gpt-5.2-chat-latest, gpt-5.2-pro | 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](https://github.com/drpedapati/pubmed-cli))

- **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](https://github.com/drpedapati/docx-review))

- For clean first-draft Word output, use `pandoc ... -o file.docx`; sciClaw injects `--defaults ` 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](https://github.com/drpedapati/sciclaw-skills) — install with `sciclaw skills install drpedapati/sciclaw-skills/`



## 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`:



```json

{

  "channels": {

    "telegram": {

      "enabled": true,

      "token": "YOUR_BOT_TOKEN",

      "allow_from": ["YOUR_USER_ID"]

    }

  }

}

```



Discord setup



1. Create app at [discord.com/developers](https://discord.com/developers/applications)

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):

```bash

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 `@mention`s it, so collaborators can talk freely without triggering responses. DMs always work without a mention.



Example:



```bash

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`:



```bash

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  --chat-id  --sender  [--mention] [--dm]`

- `sciclaw routing set-users --channel  --chat-id  --allow `

- `sciclaw routing remove --channel  --chat-id `

- `sciclaw routing export --out routing.json` / `sciclaw routing import --in routing.json [--replace]`



Session isolation is namespaced as `:@` 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](https://github.com/drpedapati/irl-template) (Idempotent Research Loop) for project lifecycle management. IRL is installed automatically as a Homebrew dependency.



The agent manages projects through natural conversation:



```bash

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



```bash

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.



```bash

sciclaw doctor            # human-readable report

sciclaw doctor --fix      # auto-fix common issues

```



Common issues



**"no credentials for openai/anthropic"**

```bash

sciclaw auth login --provider openai

```



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

```bash

sciclaw service restart

```



**Web search "API configuration problem"** — get a free key at [brave.com/search/api](https://brave.com/search/api) and add to config under `tools.web.search.api_key`.



## Updating



```bash

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: 

- 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 ` | Override model |

| `sciclaw agent --effort ` | Set reasoning effort (`none` through `xhigh`) |

| `sciclaw models list` | Show current model and providers |

| `sciclaw models set ` | Change default model |

| `sciclaw models effort ` | 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 ` | 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 ` | 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](https://sciclaw.dev/docs.html#ctxclaw) for details.



## License



MIT — see [LICENSE](LICENSE).



sciClaw is a fork of [PicoClaw](https://github.com/sipeed/picoclaw) by Sipeed, which is based on [nanobot](https://github.com/HKUDS/nanobot) by HKUDS.