Skip to content

docs: overhaul README + add social preview #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
criptogus merged 1 commit into from
Aug 13, 2026
Merged

docs: overhaul README + add social preview #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added .github/social-preview.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
175 changes: 85 additions & 90 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,100 +1,97 @@
# HermesOffice
<div align="center">

An AI-native office suite for macOS and Windows: word processor, spreadsheet,
presentations, and PDF — five Electron apps sharing one engine layer, built
around AI editing as a first-class workflow rather than a bolted-on chat box.
<img src="apps/shell/src/renderer/src/assets/hermesoffice-logo.svg" alt="HermesOffice" width="340"/>

[![Meet HermesOffice — the world's first full-featured open-source AI Office (video)](https://img.youtube.com/vi/B2pLdMX95v4/maxresdefault.jpg)](https://www.youtube.com/watch?v=B2pLdMX95v4)
# HermesOffice — the office where humans and agents work as one team

[Watch the demo video on YouTube](https://www.youtube.com/watch?v=B2pLdMX95v4)
**AI-native office suite for macOS and Windows.** Docs, Sheets, Slides and PDF — built on open standards (`.docx`, `.xlsx`, `.pptx`), byte-preserving round-trip, with the **Hermes Agent** as the native brain. No cloud. No account. No lock-in.

## Download
[![License](https://img.shields.io/github/license/criptogus/HermesOffice)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/criptogus/HermesOffice?style=social)](https://github.com/criptogus/HermesOffice/stargazers)
[![CI](https://img.shields.io/github/actions/workflow/status/criptogus/HermesOffice/ci.yml?label=CI)](https://github.com/criptogus/HermesOffice/actions)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey)](<>)
[![Version](https://img.shields.io/badge/version-0.7.0-blue)](<>)

| Platform | Requirements | Download |
| ------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **macOS** (Apple Silicon) | macOS 11+ | [HermesOffice-0.5.83-arm64.dmg](https://github.com/genspark-ai/hermesoffice/releases/download/v0.5.83/HermesOffice-0.5.83-arm64.dmg) |
| **Windows** (x64) | Windows 10+ | [HermesOfficeSetup-v0.5.79.exe](https://github.com/genspark-ai/hermesoffice/releases/download/v0.5.83/HermesOfficeSetup-v0.5.79.exe) |
| **Linux** — Debian / Ubuntu | x86_64, glibc 2.34+ (Ubuntu 22.04 or newer) | [hermesoffice_0.5.149_amd64.deb](https://github.com/genspark-ai/hermesoffice/releases/download/linux-v0.5.149/hermesoffice_0.5.149_amd64.deb) |
| **Linux** — other distributions | x86_64, glibc 2.34+, FUSE 2 | [HermesOffice-0.5.149.AppImage](https://github.com/genspark-ai/hermesoffice/releases/download/linux-v0.5.149/HermesOffice-0.5.149.AppImage) |
[Watch the demo](https://www.youtube.com/watch?v=B2pLdMX95v4) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

All builds come from `main`; the macOS and Windows installers are signed.
Older versions are on the [Releases](https://github.com/genspark-ai/hermesoffice/releases) page.
</div>

### Installing on Linux
---

The deb installs with apt — it pulls in the dependencies and adds HermesOffice
to the applications menu:
## Why HermesOffice

```bash
sudo apt install ./hermesoffice_0.5.149_amd64.deb
```
Most "AI office" tools bolt a chat panel onto a document. We inverted the model: **the document is the interface, and the agent is a collaborator** — with real context, memory and the ability to act.

The AppImage instead runs in place: install the FUSE 2 runtime
(`sudo apt install libfuse2`; on Ubuntu 24.04 the package is `libfuse2t64`),
make the file executable, then run it:

```bash
chmod +x HermesOffice-0.5.149.AppImage
./HermesOffice-0.5.149.AppImage
```
- **Local-first by default.** Board material, CISO-grade conversations and NDAs never leave your machine. The Hermes Agent gateway runs on your computer — no API key, no cloud account.

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Document the required Hermes gateway setup

For a fresh installation following these instructions, the AI functionality is unusable as described: docs/hermes-integration.md says Hermes must be installed separately, its API server must be enabled and running, and the user must configure and enter an API_SERVER_KEY; packages/ai-provider/src/stream.ts sends that key as the bearer token. Remove the “no API key” claim and link the required setup steps from the install section so users do not end up with a permanently failing AI panel.

Useful? React with 👍 / 👎.

- **Open standards, byte-preserving.** Opening and saving never breaks layout in Word, Excel or PowerPoint. Only the blocks you (or the agent) touched are regenerated; everything else survives the round trip byte-for-byte.
- **Agent-native, auditable.** Every AI mutation is visible and reversible — a unified _Proposed Change_ pipeline (diff preview → atomic apply) that the agent itself goes through, in every app.

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Stop promising pre-apply review in every app

Users relying on this trust guarantee can have documents mutated before approval: the checked ROADMAP.md explicitly says only Sheets has the proposal flow, while Docs and Slides use after-the-fact snapshots and PDF's trust UX is pending; it also marks the unified Proposed Change contract as design work. This line should describe the current per-app behavior rather than claiming that every mutation already passes through a diff-preview/atomic-apply gate.

Useful? React with 👍 / 👎.

- **Hermes is the backbone.** Identity, memory, sessions and skills come from the open-source [Hermes Agent](https://hermes-agent.nousresearch.com) — not from a proprietary cloud.

## Apps

| App | Product | What it is |
| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/docs` | **HermesOffice Docs** | `.docx` word processor. Byte-preserving round trip: only dirty paragraphs are regenerated (paragraph patch), everything else in the original file is kept byte-for-byte, so opening and saving never breaks layout in Word. Paginated view whose line metrics reproduce the original document's layout, tracked changes, comments, styles, equations, ink. |
| `apps/sheets` | **HermesOffice Sheets** | `.xlsx` spreadsheet. UI built on the open-source [Univer](https://github.com/dream-num/univer) core (Apache-2.0) with a large layer of in-house extensions; `.xlsx` import/export runs through an in-house Rust sidecar (calamine + IronCalc), charts are rendered in-house (Konva), plus pivot tables, slicers, conditional formatting, and formula tracing. |
| `apps/slides` | **HermesOffice Slides** | `.pptx` presentations. In-house `.pptx` parse/render/edit engine with masters, charts, cropping, ink, and text shaping (HarfBuzz metrics). |
| `apps/pdf` | **HermesOffice PDF** | `.pdf` viewer/editor on pdf.js + pdf-lib: annotations, forms, outlines, stamps, signatures, page operations, and printing support. |
| `apps/shell` | **HermesOffice** | The suite shell: home screen, tabbed hosting of the four editors, auto-update. |
| App | What it is |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Docs** | `.docx` word processor. Byte-preserving round trip via paragraph-level patching; paginated view reproducing the original layout; tracked changes, comments, styles, equations, ink. |
| **Sheets** | `.xlsx` spreadsheet on the open-source [Univer](https://github.com/dream-num/univer) core with in-house extensions; `.xlsx` import/export via an in-house Rust sidecar (calamine + IronCalc); charts (Konva), pivot tables, slicers, conditional formatting, formula tracing. |
| **Slides** | `.pptx` presentations. In-house parse/render/edit engine: masters, charts, cropping, ink, text shaping (HarfBuzz metrics). |
| **PDF** | `.pdf` viewer/editor on pdf.js + pdf-lib: annotations, forms, outlines, stamps, signatures, page operations, printing. |
| **Shell** | The suite shell: home screen, tabbed hosting of the four editors, auto-update. |

Every app embeds the same AI panel: block-granular AI editing with version
snapshots and diffs in docs, a tool-calling agent over workbook/slide/PDF
state in the others.
Every app embeds the same AI panel: block-granular AI editing with version snapshots and diffs in Docs; a tool-calling agent over workbook/slide/PDF state in the others.

**AI providers.** The apps sign in to a Genspark account and route model
calls through the Genspark service side; no model API key is stored locally.
## The agent, natively

## Engine packages
HermesOffice talks to the **Hermes Agent** through a local OpenAI-compatible gateway (`http://127.0.0.1:8642`):

All pure TypeScript, no Electron dependency, unit-tested (except the UI kit):
- **Hermes is the default provider** — no external account to create.
- **Per-document session continuity** — the agent remembers the conversation for each document (`X-Hermes-Session-Id`), across sessions and machines.
- **Trusted Agent Actions** — edits arrive as proposals with diff preview; accept, reject or roll back. The same pipeline gates external agents via the MCP server (roadmap P0).

- `packages/docx-engine` — docx parsing → block tree (with `docxIndex`
anchors and passthrough), OOXML fragment generation, byte-level paragraph
patching.
- `packages/pptx-engine` / `packages/pptx-render` — pptx model and rendering.
- `packages/file-parse` — text extraction for AI attachments (office formats,
text formats).
- `packages/agent-core` — the AI agent loop and skill composition shared by
every app.
- `packages/ai-provider` — provider abstraction and streaming for the model
backends.
- `packages/ai-search` — Genspark auth + web/image search tools.
- `packages/i18n`, `packages/ui`, `packages/project-store`,
`packages/electron-utils` — shared i18n core, React UI kit, recent-files
store, and Electron main-process helpers.

## Development
## Install & run

> The fork ships as a **release train** (`ho-v*` tags) with source-based auto-update. Installers are built from `main`; no prebuilt binaries are hosted on GitHub Releases yet.

**macOS (Apple Silicon / Intel):**

```bash
git clone https://github.com/criptogus/HermesOffice.git
cd HermesOffice
npm install
npm run dist:mac # → apps/shell/release/HermesOffice-*.dmg
Comment on lines +54 to +60

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Build an Intel artifact in the Intel instructions

On an Intel Mac, the shown npm run dist:mac command still packages only arm64: apps/shell/electron-builder.cjs includes x64 only when GENOFFICE_MAC_X64=1, which these instructions never set. Anyone following the advertised Intel path therefore receives an incompatible DMG; either include the opt-in environment variable or label this command Apple-Silicon-only.

Useful? React with 👍 / 👎.

```

**Windows:**

```bash
git clone https://github.com/criptogus/HermesOffice.git
cd HermesOffice
npm install
npm run fixtures # generate test .docx fixtures
npm test # engine + app unit tests (docs/sheets/slides need no display)
npm run typecheck # tsc --noEmit across every workspace
npm run dev # all four editors + shell against Vite dev servers
npm run dev:docs # a single app (same pattern works per workspace)
npm run dist:mac # package macOS dmg (regenerates third-party notices)
npm run dist:win # package Windows nsis installer
npm run dist:win # → apps/shell/release/HermesOfficeSetup-*.exe
Comment on lines 65 to +69

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Stage the Windows sidecar before running dist:win

On a fresh Windows checkout, this command does not produce a complete installer: build:all compiles the sidecar into Cargo's normal MSVC output, but apps/shell/electron-builder.cjs packages only target/x86_64-pc-windows-gnu/release/xlsx-sidecar.exe. The prerequisite already documented in CONTRIBUTING.md—building the GNU target or copying the binary into that path—must be included here; otherwise electron-builder can omit the resource and every workbook open in the resulting installer fails.

Useful? React with 👍 / 👎.

```

The sheets app additionally needs a Rust toolchain for its xlsx sidecar
(`cargo` on PATH); `npm run build -w @hermesoffice/sheets` compiles it
automatically.
**Development:**

Local UI/e2e driver scripts (Playwright + Electron, for local acceptance, not
committed by default) live in [`scripts/drivers/`](scripts/drivers/README.md).
```bash
npm install
npm run fixtures # generate test .docx fixtures
npm run dev # all four editors + shell against Vite dev servers
npm run dev:docs # a single app (same pattern per workspace)
```

The sheets app additionally needs a Rust toolchain for its xlsx sidecar (`cargo` on PATH).

## Engine packages

All pure TypeScript, no Electron dependency, unit-tested:

## Architecture notes (docx round trip)
- `packages/docx-engine` — docx parsing → block tree (with `docxIndex` anchors and passthrough), OOXML fragment generation, byte-level paragraph patching.
- `packages/pptx-engine` / `packages/pptx-render` — pptx model and rendering.
- `packages/file-parse` — text extraction for AI attachments.
- `packages/agent-core` — the AI agent loop and skill composition shared by every app.
- `packages/ai-provider` — provider abstraction and streaming for model backends.
- `packages/i18n`, `packages/ui`, `packages/project-store`, `packages/electron-utils` — shared i18n core, React UI kit, recent-files store, Electron main-process helpers.

## Architecture note (the docx round trip)

```
open docx ─► archive original by hash (never touched)
Expand All @@ -106,29 +103,27 @@ save ─► dirty blocks → OOXML fragments (referencing existing styles o
─► repack zip; all other entries copied byte-for-byte
```

The same philosophy holds in sheets and slides: the original file is the
source of truth, edits are applied as narrow patches, and everything the
editor didn't touch survives the round trip untouched.
The same philosophy holds in sheets and slides: the original file is the source of truth, edits are applied as narrow patches, and everything the editor didn't touch survives the round trip untouched.

## Security
## Roadmap

Public and outcome-driven: [ROADMAP.md](ROADMAP.md). Current focus — **Phase 2 · Value Loops**: complete vertical workflows (meeting → minutes, report → deck, template → deliverable), live meeting minutes (100% local), the unified Proposed Change pipeline, and the embedded MCP server that lets _any_ agent — Hermes, Claude Code, yours — work on documents through the same trust layer.

See [SECURITY.md](SECURITY.md) for the process security posture (renderer
sandboxing, IPC validation, external-link gating) and the threat models for
AI-generated content.
## Contributing

## Third-party notices
See [CONTRIBUTING.md](CONTRIBUTING.md). Good starting points:

- `docs/hermes-integration.md` — how the Hermes brain plugs into the apps.
- `packages/agent-core` — the agent loop shared by all apps.
- `packages/docx-engine` — byte-preserving paragraph patch.
- Issues labeled [`good-first-issue`](https://github.com/criptogus/HermesOffice/labels/good%20first%20issue).

## Security

`npm run notices` regenerates the bundled third-party license summary
(`tools/gen-third-party-notices.mjs`); all runtime dependencies are
MIT/Apache-2.0/OFL, and the bundled fonts (Liberation, Carlito, Caladea, Noto
CJK subsets) are OFL/Apache.
See [SECURITY.md](SECURITY.md) for the process security posture (renderer sandboxing, IPC validation, external-link gating) and the threat models for AI-generated content.

## License

HermesOffice is licensed under the [Apache License 2.0](LICENSE), with one
exception: the `ee/` directory is reserved for future enterprise modules and
is covered by the [HermesOffice Enterprise License](ee/LICENSE).
[Apache License 2.0](LICENSE), with one exception: the `ee/` directory is reserved for future enterprise modules and is covered by the [HermesOffice Enterprise License](ee/LICENSE).

The HermesOffice and Genspark names and logos are trademarks of Mainfunc, Inc.
The Apache-2.0 license does not grant permission to use them (see section 6);
forks should use their own branding.
Built on the open-source [GenOffice](https://github.com/genspark-ai/genoffice) (Apache-2.0) — a thin fork that keeps engines and app shells aligned with upstream while adding the Hermes integration, product identity and collaboration features.
Loading