Word Agent

An AI-powered, web-based workstation for editing, analyzing, and converting .docx documents — every change is previewable, reviewable, and version-controlled.

简体中文 · English

Word Agent is a single-tenant, self-hosted document workstation. You import a .docx, chat with an agent that can read structure, propose edits, run scripts in a per-session sandbox, and convert formats — and you stay in control: nothing is written to the document until you click Apply.

---

Highlights

• Two-tier agent architecture — A single tool-calling loop combines deterministic, patch-style edits with an open-ended Linux sandbox. The model picks the right tier per task; you only review the result.
  • Tier 1 — Typed document operations: edit_text, set_style, set_format, find_and_replace, unify_heading_format, unify_body_format, analyze_document, rewrite_block — surgical edits that surface as preview cards before they touch the file.
  • Tier 2 — Per-session sandbox: A scratch workdir with python-docx, lxml, openpyxl, LibreOffice, Pandoc, Poppler, ImageMagick, zip/unzip — for format conversions, image extraction, custom OOXML scripts, or anything that doesn't fit the patch model.
• Preview-first edit pipeline — All Tier-1 edits go through generate → preview → confirm → execute → new version. Patch cards show before/after diffs, anchor IDs, and the operation type. Discard is one click.
• Version history with cross-version & cross-document compare — Every apply creates a new version. The Compare workspace renders two documents side-by-side with word-level inline diffs, block-level change cards, and style-level diffs (catalog + per-paragraph inline formatting).
• Workspace file references with @filename — Mention any workspace file in chat and the backend mounts it under stable workspace/... sandbox paths so the agent can read context (PDFs, Markdown, images, spreadsheets) alongside the active .docx.
• Markdown skill packs — Reusable knowledge under skills/<pack>/SKILL.md is auto-discovered, indexed in the system prompt, and mounted into the sandbox so the model can read full references with sandbox_read_file before writing scripts. skills/word-doc-tools/ ships with the project.
• Inline previews for generated artifacts — PDFs, images, Markdown, HTML, and text artifacts produced by the sandbox preview directly in the right panel and can be saved into the workspace with one click.
• Per-dialog diagnostics — JSONL session logs (LLM request/response summaries, tool inputs/results, sandbox setup, final plan) are written under data/agent-sessions/YYYY-MM-DD/ for offline inspection.
• Bilingual UI — Toggle between English and 中文 from the header at any time.
• Sandbox security model — Per-session workdirs, locked CWD, host-env stripping, output and CPU caps, session TTL, and process-group kill on timeout. Designed for trusted single-user docker deployment.

---

Screenshots

Document workspace

The three-panel layout: workspace and version history on the left, live .docx preview in the center, and the agent / style inspector on the right.

Side-by-side compare

Compare any two versions of one document, or two completely separate documents — the diff panel on the right summarizes block-level and style-level changes with word-level highlights.

---

Architecture in one breath

pnpm workspaces + Turborepo monorepo:

• apps/web — React + Vite + Tailwind v4 + Zustand + TanStack Query frontend (port 5173)
• apps/api — NestJS + Fastify backend, Drizzle ORM + better-sqlite3, Vercel AI SDK (Anthropic / OpenAI), OOXML read via fast-xml-parser, write via @xmldom/xmldom (port 3001)
• packages/shared-types — TypeScript types shared across packages
• skills/word-doc-tools/ — first Markdown skill pack mounted into the agent sandbox

For a deeper map of agent tooling, document operations, and conventions, see CLAUDE.md.

---

Project structure

apps/web              React + Vite frontend
apps/api              NestJS + Fastify API, document operations, agent loop
packages/shared-types Shared TypeScript types
skills/word-doc-tools Default Markdown skill pack mounted into the sandbox
docker-compose.yml    Single-host deployment
data/                 Runtime: SQLite db, uploads, sandbox workdirs, session logs

---

Requirements

• Node.js 20+
• pnpm 10.33.0+
• Docker and Docker Compose (for container deployment)

Local development

pnpm install
pnpm dev

The frontend serves at http://localhost:5173 and proxies /api to the backend on http://localhost:3001.

Useful commands:

pnpm build
pnpm lint
pnpm --filter @word-agent/api test
pnpm check

Docker Compose deployment

Create an environment file from the template and fill in only the provider settings you need:

cp .env.example .env
pnpm docker:up

The web app is served at http://localhost:8080 by default. Change WEB_PORT in .env if another host port is needed. The web container also reverse-proxies /api to the API service, so the browser uses a single origin and no CORS setting is needed for the default Compose deployment.

Persistent application data lives in the word_agent_data Docker volume, mounted at /app/data in the API container — SQLite database, uploaded files, sandbox outputs, telemetry, and optional session diagnostics.

Stop the stack:

pnpm docker:down

Environment variables

Common deployment variables:

Variable	Purpose
WEB_PORT	Host port for the web container, default 8080
CORS_ORIGIN	Optional; only for non-proxied deployments where the frontend and API are served from different browser origins
LLM_PROVIDER	openai or anthropic
OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL	OpenAI / OpenAI-compatible provider settings
ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL	Anthropic provider settings
AGENT_SESSION_LOG_ENABLED	Set to false for release deployments unless diagnostics are needed

Without an LLM key, Word Agent still imports, previews, compares, and runs deterministic document operations; the agent falls back to keyword-based skill routing.

Do not commit .env, runtime data, logs, generated builds, or uploaded documents.

Release check

Before publishing or packaging changes:

pnpm check
docker compose --env-file .env.example config --quiet

For container changes, also run:

docker compose --env-file .env.example build