KatanA Desktop HiroyukiFuruno

KatanA Desktop

A fast, lightweight Markdown workspace for macOS, Windows, and Linux — built with Rust and egui.

🌐 Official Website | 📚 Documentation

English | 日本語

---

What is KatanA

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 Markdown documents 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. The owner primarily uses Antigravity as the main development agent. 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. Operational familiarity and maintenance priority are Antigravity-first.

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
• GitHub Flavored Markdown — Tables, strikethrough, task lists, footnotes, autolinks
• Workspace-aware — Open a folder and navigate files from the integrated file tree
• Tab bar — Multiple documents open simultaneously with VSCode-style tabs
• i18n — UI strings fully localised (English / Japanese bundled)
• Fast native performance — Built with Rust and egui, no Electron, no Node.js — just a single native binary

---

Installation

> Available on macOS (Apple Silicon & Intel), Windows, and Linux.

macOS

Homebrew (Recommended for macOS)

brew tap HiroyukiFuruno/KatanA && brew install --cask katana-desktop

No additional steps required — the app is ready to use immediately.

Manual Download (macOS)

1. Go to the Releases page
2. Download the latest KatanA-Desktop-x.y.z.dmg
3. Open the DMG and drag KatanA Desktop.app into your Applications folder
4. 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

Portable ZIP (Recommended)

1. Go to the Releases page
2. Download KatanA-windows-x86_64.zip
3. Extract the archive to your preferred location (e.g. C:\Program Files\KatanA\)
4. Run katana-desktop.exe

> Tip: Pin it to the taskbar or create a shortcut for quick access.

MSI Installer (Windows)

An MSI installer (KatanA-windows-x86_64.msi) is also available on the Releases page. It automatically creates Start Menu and Desktop shortcuts.

> Note: Since the MSI is not code-signed, Windows SmartScreen may display a warning when downloading. > In Edge, click "…" → "Keep" in the download bar. If a further dialog appears, click "Show more" → "Keep anyway" to proceed.

Linux

Homebrew (Recommended)

brew tap HiroyukiFuruno/KatanA && brew install katana-desktop

Manual Download (Linux)

1. Go to the Releases page
2. Download the KatanA-linux-x86_64.tar.gz
3. Extract the archive and run the executable directly

Updating KatanA

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: You can update the app directly from within the UI by clicking the "Update & Restart" button. If you initially installed KatanA via Homebrew, the first time you update from within the app, KatanA will automatically untap itself from Homebrew to prevent double-management issues.
• Windows / Linux: The update dialog will provide a direct link to download the latest asset from the release page.

---

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. External tools are required only for Mermaid and PlantUML rendering.

Mermaid

Install the Mermaid CLI globally:

npm i -g @mermaid-js/mermaid-cli

Once installed, mmdc will be detected automatically. No additional configuration is needed.

PlantUML

1. Install a Java runtime:

brew install openjdk@25

1. 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:

• 📖 Development Guide — Setup, build, test, and project structure
• 📐 Coding Rules — Code style, conventions, and quality gates
• 🏗️ Architecture Decisions — Design rationale and ADRs

---

Support the Project

If you find KatanA useful and would like to support its development, you can do so through sponsorship.

Support helps cover:

• development time
• infrastructure
• tooling costs

👉 Become a Sponsor

• ⭐ Star this repository — it helps others discover KatanA
• Share KatanA with people who might find it useful

---

Appendix: Windows Environment Setup

Installation instructions for external tools required for diagram rendering (Mermaid / PlantUML) on Windows.

Installing Node.js (Required for Mermaid CLI)

Node.js is required to run the Mermaid CLI (mmdc).

winget install -e --id OpenJS.NodeJS.LTS

After installation, open a new terminal and run:

npm i -g @mermaid-js/mermaid-cli

> If you encounter errors: If winget fails, please download and install Node.js directly from the Official Node.js Website.

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 >

---

License

KatanA Desktop is released under the MIT License.