OmniScientist V2

# OmniScientist V2

> **A local-first, CLI-first open-source personal research agent.**
> Chat in your terminal (like Codex / Claude Code) to do **grounded, cited** literature Q&A,
> research ideation, scientific figures, paper writing & review — with an auditable
> hypothesis→claim→evidence trail, a reproducible run ledger, and an honesty `--verify` pass.
> Durable state is stored locally (no MySQL/Redis); configured model, connector, and IM providers
> still receive the data required for each request. Skills use a portable SKILL.md baseline for
> Claude Code, Codex & OpenClaw (and MCP), and the same agent is reachable from
> **WeChat / Feishu / DingTalk**.

This repository is the **official next-generation (V2) implementation** of the OmniScientist
project introduced in [*OmniScientist: Toward a Co-evolving Ecosystem of Human and AI
Scientists*](https://doi.org/10.48550/arXiv.2511.16931) (Shao et al., arXiv:2511.16931). V2
distills the earlier HelixForge research-agent OS into a local-first, single-machine agent while
preserving auditable research objects, workflows, and provenance. See [`CITATION.cff`](CITATION.cff)
for software and paper citation metadata.

For the full design and how it compares to Claude Code/Codex and other open-source research
agents, see [`cli/docs/research-agent-design.md`](cli/docs/research-agent-design.md).

The current repository metadata reports package version `2.0.0rc8` (Git tag `v2.0.0rc8`). This is
a temporary prerelease identity, not the stable release line: the first stable V2 release will be
`2.0.0`, followed by compatible `2.0.x` patch releases. Once the stable release is published,
normal installations and updates should not pin a version; the package manager resolves the latest
stable release. Pin `==<version>` only for reproducibility, rollback, or release verification.
Release artifacts are published to the public index by `cli/scripts/release.sh`.

## Install and initialize

### Requirements

- macOS, Linux, or Windows 10/11
- Python 3.11 or newer
- [`uv`](https://docs.astral.sh/uv/) or [`pipx`](https://pipx.pypa.io/) for an isolated installation
- Node.js 20.9 or newer to run the bundled research-pptx renderer; npm is required only for the first `omni skills setup research-pptx` (pnpm is not a substitute)
- A model endpoint is optional for installation: the bundled `mock` provider supports offline
  setup and deterministic evaluation

### Quick install

PyPI is the stable package authority. Install one isolated copy, then launch Omni:

```bash
uv tool install OmniScientist-V2
# or
pip install OmniScientist-V2
# or
pipx install OmniScientist-V2

omni
```

The browser surface is an optional package extra for direct package-manager installs:

```bash
uv tool install "OmniScientist-V2[web]"
# or: pip install "OmniScientist-V2[web]"
omni web
```

On the Web home screen, **Scientist persona** lets you choose an installed
SoulAgent persona and describe the current research task. The same controls are
available under **Settings → Scientist personas** for search, activation,
task-specific refresh, switching, and restoring standard Omni. Web and CLI read
the same workspace-scoped persona catalog and active state; every change runs as
a normal, auditable SoulAgent Task, and an in-progress change is resumed after a
page refresh instead of being submitted twice.

These unpinned commands install the latest stable release. Until `2.0.0` is published, use the
checkout installer below or intentionally select a prerelease for testing. An exact stable version
is optional and should be used only when it is intentionally required, for example
`pip install 'OmniScientist-V2==2.0.0'`.

The first `omni` launch runs setup, prepares the lockfile-pinned Node runtime, and starts or repairs
the single Home Service. Later launches are fast local checks. If a package manager replaces the
package directly (`uv tool upgrade OmniScientist-V2` or `pipx upgrade OmniScientist-V2`), the next
`omni` detects the new installation fingerprint and completes runtime/config/service convergence
without downloading the Python package again.

Use one product command for normal updates:

```bash
omni update
```

It delegates the Python package step to the owning package manager, then converges managed runtime
state, retires legacy daemons, refreshes the supervisor launcher, restores the Home Service, and
verifies readiness. SQLite schema changes remain data-preserving and run with backups when each
store is first opened by the new version.

`omni update` updates to the latest stable release. If the installation is managed directly by a
package manager, use its ordinary unpinned upgrade command instead:

```bash
uv tool upgrade OmniScientist-V2
pip install --upgrade OmniScientist-V2
pipx upgrade OmniScientist-V2
```

### Install from a checkout

From a downloaded/cloned source tree, the repository installer deploys the local checkout snapshot,
including uncommitted work. It creates an isolated `uv tool` and boot

... (truncated)