A clean-room Rust toolkit to read, convert, render, write and AI-edit HWP 5.0 / HWPX documents with no Hancom Office or COM dependency. Runs on Linux / macOS / CI.
A Rust workspace for Korean HWP documents (.hwp HWP 5.0 binary, .hwpx OWPML/KS X 6101) with no
external HWP library. The CFB container, HWP record streams, OWPML XML, page layout and glyph
shaping are all implemented directly from the specification and from measurements of genuine files.
Nothing depends on Hancom Office or Windows COM automation, so it runs as-is on Linux/macOS servers
and in CI.
ahwp reads, converts, renders and writes .hwp and .hwpx, edits them in place while preserving
images, formatting and unparsed records, composes new documents from typed specs and Korean
official-document templates, and serves the same operations to AI agents over MCP. Charts and OLE
objects are not supported, equations render as an approximation, and only unmodified hwp-origin
documents round-trip byte-identically.
- No Hancom parity claim. The final verdict is always whether the file opens correctly in Hancom Office.
The full feature list, status table, limitations and roadmap are in What ahwp does and its limits. Unimplemented features are catalogued in 12-feature-gaps.
The command is ahwp. 2.0 removed the 1.x hwp compatibility name: replace hwp with ahwp in scripts and MCP client configurations.
# One-line script (macOS / Linux), installs to ~/.local/bin and verifies the .sha256
curl -fsSL https://raw.githubusercontent.com/STAIxBWLB/agent-hwp/main/scripts/install.sh | sh
# Homebrew (macOS / Linux); the repository is its own tap
brew tap staixbwlb/hwp https://github.com/STAIxBWLB/agent-hwp
brew install ahwp
# From source (Rust edition 2024, rust-version 1.93 or newer)
git clone https://github.com/STAIxBWLB/agent-hwp.git && cd agent-hwp
cargo install --path crates/hwp-cli
ahwp update # self-update to the latest release (a brew install delegates to brew)Pin a version or install directory for a build step:
curl -fsSL https://raw.githubusercontent.com/STAIxBWLB/agent-hwp/main/scripts/install.sh \
| sh -s -- --dir /usr/local/bin --tag v2.1.0No fonts are bundled. Text extraction and conversion need none; rendering and PDF output need CJK
fonts passed with --font-dir <dir> or HWP_FONT_DIR. Pre-built binaries for every platform,
serverless and container builds (glibc 2.17 baseline), font details and rollback are in
Install and update.
ahwp info report.hwp # format, version, properties
ahwp cat report.hwp --format markdown # extract text as markdown
ahwp grep "예산" report.hwp # search (exit 1 when nothing matches)
ahwp convert report.hwp -o report.hwpx # hwp → hwpx
ahwp render report.hwp -o report.pdf --font-dir ./fonts # searchable multi-page PDF
ahwp new -o out.hwpx --from notes.md # new document from markdown
ahwp new -o gian.hwpx --template gian-internal # 기안문 with 두문/결문 frames
ahwp fill gian.hwpx -o final.hwpx --set "제목=예산 집행 계획"
ahwp edit form.hwp -o filled.hwp --replace "초안=>최종" --verify
ahwp mcp --root . --font-dir ./fonts # MCP stdio server for AI clientsMore examples, and every command at a glance, are in Commands at a glance.
| I want to | Read |
|---|---|
| See every feature, the status table, limits and roadmap | What ahwp does and its limits |
| Install on another platform, in a container or serverless build, or set up fonts | Install and update |
| Look up a command or a flag | Commands at a glance |
| Convert a document or extract text, markdown or provenance segments | Markdown export |
| Edit or fill a document, or bind form fields (workflows and conventions) | Agent conventions |
| Author new documents from specs, write 공문 or regenerate from JSON | Authoring documents |
| Certify a written file or run the structured corpus | Certification and the structured corpus |
Use ahwp from an AI agent over MCP |
MCP server |
| Set up a specific AI client (including Amazon Quick) or install the agent skill | AI client integrations |
| Deploy the MCP server remotely | Remote MCP deployment |
| Find any other page | The docs map |
| Contribute or build from source | Development |
agent-hwp follows Semantic Versioning from 1.0.0. A breaking change to any of the following needs a new major version:
- the
ahwpCLI's commands, flags and exit codes; - the MCP tools' names and arguments, over stdio and
ahwp serve; - the published JSON Schemas in
schemas/. Each schema also carries its own version in its file name (edit-ops-v1,segment-envelope-v2): an incompatible change ships as a new file.
Not covered: the wording of human-facing messages and --help text, rendered pixels, and the exact
bytes of written files.
Bug reports and pull requests are welcome.
- Work on a
feat/,fix/ordocs/branch and submit a PR. Do not push to main directly. - Pass
scripts/check.shbefore opening a PR (the same gates as CI). - Add round-trip or golden tests with new format features where possible.
- User-facing documentation is bilingual with English as the canonical side (
NAME.md) and Korean as its pair (NAME.ko.md); update both in the same commit. - Commit messages, PR text and release notes are written in English only.
- For specification questions, consult Hancom's official HWP Document File Formats 5.0 (not bundled here).
This product was developed with reference to Hancom's HWP document file format open specification, 한글 문서 파일 형식 5.0 / HWP Document File Formats 5.0 (© Hancom Inc.).
The specification is copyrighted by Hancom Inc. Its open-document license permits free viewing, copying and distribution but restricts distribution to the unmodified original or copies thereof, so this repository does not bundle the specification or derivatives of it (extracted text, page captures) and links only to the official distribution point. See docs/README.md.
Some test fixtures come from hahnlee/hwp-rs (Apache-2.0); see
fixtures/README.md and the root NOTICE. The form-field rules of ahwp slots --forms and
ahwp fill --forms are ported from chrisryugj/kordoc (MIT);
see the root NOTICE.
Dual-licensed under MIT or Apache-2.0. Unless stated otherwise, code contributed to this repository is understood to be released under the same two licenses.