KatanA Desktop is a fast, lightweight Markdown workspace designed for developers working with specification documents and technical writing across macOS, Windows, and Linux. It is built with Rust and egui, ensuring native performance without relying on Electron or Node.js.
Key Features:
Live split-view preview: Edit Markdown on one side while seeing the rendered HTML output on the other, with synchronized scrolling.
Diagram rendering support for Mermaid, PlantUML, and Draw.io diagrams directly in Markdown files.
GitHub Flavored Markdown (GFM) capabilities, including tables, task lists, footnotes, and autolinks.
Workspace-aware file navigation: Open a folder to easily browse and manage documentation within the integrated file tree.
Tab bar functionality for opening multiple documents simultaneously, similar to VSCode-style tabs.
Internationalization (i18n): The UI is fully localized with English and Japanese language support.
Audience & Benefit:
Ideal for developers involved in specification-driven development workflows, KatanA Desktop provides a streamlined environment for creating, editing, and visualizing technical documentation. It helps users maintain clarity and efficiency in their workflow while supporting integration with AI agents, making it a valuable tool for modern, AI-assisted development practices.
The software can be installed via winget on supported platforms, offering developers a seamless setup experience across different operating systems.
README
KatanA Desktop
A fast, lightweight Markdown workspace for macOS, Windows, and Linux — built with Rust and egui.
The name KatanA comes from the Japanese word "刀" (katana) — a razor-sharp blade forged with precision and purpose.
Just as a katana cuts cleanly through its target, this tool is designed to slice through the complexity of documentation workflows with speed and clarity. The name reflects the creator's desire to build something that helps developers cut through challenges decisively, one problem at a time.
KatanA Desktop is a fast, lightweight Markdown workspace for macOS, Windows, and Linux, purpose-built for developers who work with specification documents and technical writing.
The trailing uppercase A stands for "AI"and"Agent"— KatanA is designed for the era of AI agent-assisted development, where Markdown specifications serve as the bridge between humans and AI.Katana × AI Agent = KatanA.
Background
As of 2026, software development is rapidly evolving with the rise of AI agents assisting engineers in writing, reviewing, and maintaining code.
Alongside this shift, Spec-Driven Development (SDD) is gaining attention as a development methodology where specifications, architecture descriptions, and tasks are defined before implementation. These specifications are typically written in and serve as the central source of truth for both developers and AI agents.
This repository is operated with an AI-agent-first workflow in mind.
Repository-local skills are maintained canonically under .agents/skills/.
If another AI agent expects a different skill directory layout, copy the same skill content from .agents/skills/ into that agent's expected path instead of maintaining a separate variant.
KatanA itself is also developed through a Codex-centered AI-agent workflow.
We primarily use Codex and combine it with other AI agents where they fit best, such as implementation, review, investigation, documentation, and release preparation.
This keeps the project aligned with the same human-and-agent collaboration model that KatanA is built to support.
Mandatory Tools for AI-Agent Workflow
To minimize token consumption and manage context window bloat, the use of rtk is mandatory for all AI agents working in this repository.
AI agents MUST wrap noisy commands (tests, linters, builds) with rtk to ensure outputs are filtered and summarized before being ingested into the context.
However, existing Markdown tools are often either:
general-purpose editors not optimized for technical documentation workflows, or
heavy knowledge-management tools with unnecessary complexity.
KatanA Desktop was created to solve this problem
The goal of KatanA is to provide a simple, fast, and workspace-oriented Markdown environment where developers can easily browse and edit documentation used in SDD workflows.
Features
Live split-view preview — Edit on the left, rendered HTML on the right, scroll-synced
Diagram rendering — First-class support for Mermaid, PlantUML, and Draw.io fenced code blocks
Open the DMG and drag KatanA Desktop.app into your Applications folder
Run the following command once to allow the app to launch:
xattr -cr /Applications/KatanA\ Desktop.app
> Note: On macOS Sequoia (15.x), Gatekeeper requires this command for apps not notarized with Apple.
> Alternatively, go to System Settings → Privacy & Security → "Open Anyway" after the first launch attempt.
Windows
Winget (Recommended)
On Windows 10 / 11, you can easily install KatanA Desktop using the official winget package manager:
winget install HiroyukiFuruno.katana-desktop
Manual Download (Windows)
You can also download the files manually from the Releases page.
Portable ZIP: Extract the archive to your preferred location and run KatanA.exe.
MSI Installer: Automatically creates Start Menu and Desktop shortcuts. (Note: Since the MSI is not code-signed, Windows SmartScreen may display a warning. Select "More info" -> "Run anyway" to proceed).
Linux
Homebrew (Recommended)
brew tap HiroyukiFuruno/KatanA && brew install katana-desktop
KatanA features a built-in auto-updater. Once installed (whether via Homebrew or manually), KatanA will notify you when a new release is available.
macOS / Windows / Linux: You can update the app directly from within the UI by clicking the "Install and Restart" button.
macOS Homebrew installs: The first in-app update automatically untaps KatanA from Homebrew to prevent double-management issues.
Current Status
KatanA Desktop is under active development. See the Releases page for the latest version and changelog.
Core features available today:
Workspace-based Markdown browsing
Diagram support (Mermaid / PlantUML / draw.io)
Split preview with synchronized scrolling
Fast native desktop performance (Rust-based)
The project is evolving rapidly — new features and improvements are released frequently.
Diagram Rendering Setup
KatanA supports Mermaid, PlantUML, and Draw.io diagrams in Markdown fenced code blocks. Mermaid and Draw.io renderer assets are bootstrapped by KatanA. PlantUML rendering requires a Java runtime.
PlantUML
Install a Java runtime:
brew install openjdk@25
Open a Markdown file containing a PlantUML block in KatanA and click the ⬇ Download button that appears in the preview pane. The plantuml.jar will be downloaded automatically.
Draw.io
Draw.io diagrams are rendered natively — no external tools required.
Project Goals
KatanA aims to become a tool that helps developers:
Read and navigate Markdown documentation efficiently
Work with specification-driven workflows
Integrate documentation with modern AI-assisted development
The long-term vision is to build a lightweight documentation workspace that complements modern development tools.
We Want Your Ideas
This project is still in its early stages. We welcome features ideas, usability suggestions, and bug reports.
If you have thoughts on how KatanA can improve the documentation workflow for developers, please open an issue or discussion.
For Contributors
If you would like to help shape the future of KatanA, please read our:
🤝 Contributing Guide — How to join discussions, provide design feedback, and collaborate via AI-agent-assisted workflows.
Open Source Commitment
KatanA Desktop is an open source project.
We are committed to keeping the core functionality available for free, especially features that do not incur ongoing operational costs.
These include:
Markdown viewing
Workspace navigation
Documentation browsing
Diagram rendering
Future Plans
Some advanced features may require external services or operational costs.
For sustainability, the project may introduce:
optional paid features (e.g., AI-assisted tools)
small advertisements within the application
However, the core documentation functionality will remain free.
For Developers
If you want to build from source, contribute, or understand the architecture:
⭐ Star this repository — it helps others discover KatanA
Share KatanA with people who might find it useful
Appendix: Windows Environment Setup
Installation instructions for the Java runtime required for PlantUML rendering on Windows.
Installing JDK (Required for PlantUML)
A Java runtime is required to render PlantUML diagrams.
winget install -e --id Oracle.JDK.25
> If you encounter errors: Errors may occur if your winget sources are outdated. Keep your sources updated and retry:
>
> powershell > winget source update > winget install -e --id Oracle.JDK.25 >
