Why it matters
For AI builders, Seiso offers a way to manage the increasing volume of AI-generated documentation. By establishing a clear convention and providing automated checks, it helps ensure that documentation remains reliable and useful as a context source for coding agents and human collaborators.

What changed

Seiso, a fresh release from scarletkc, introduces a structured Markdown convention and a linter to address challenges in managing project documentation, particularly when generated by AI. The tool is built in Rust and is available via Cargo, PyPI, and npm packages, with prebuilt binaries for common platforms like macOS, Linux (x64 and arm64), and Windows x64. For other platforms, including musl-based Linux, installation via Cargo is recommended, or the PyPI package can build from source with a Rust toolchain.

The core of Seiso is its convention, which dictates how Markdown files should be organized. Key principles include:

  • Single Kind Declaration: Each document should declare a single kind (e.g., howto, reference, adr) and contain only content relevant to that kind.
  • Single Source of Truth: Facts should reside in one primary location, with other pages linking to it rather than duplicating information.
  • Separation of Volatile Data: Information that changes frequently, such as version numbers or deployment status, should not be hardcoded into long-lived pages.
  • Clear Pointers: Sentences should use pointers to refer to files or symbols, guiding readers directly to the promised information.
  • Objective Prose: Documentation should avoid addressing the reader directly or narrating its creation process.
  • Documented Judgment Calls: Decisions that tools cannot automate should be written down with a clear reason.

The seiso command-line tool facilitates this convention. seiso init generates a seiso.toml configuration file, suggesting exclusions, kind mappings, and documentation site entries for review. seiso check runs stable rules by default, ensuring adherence to established conventions. Experimental rules are available in preview mode using the --preview flag, which should be tested locally before integration into CI pipelines.

Why it matters for builders

As AI increasingly assists in generating project documentation, maintaining its accuracy and consistency becomes critical. Seiso provides a framework to standardize this documentation, making it more reliable for both human developers and AI coding agents. By enforcing a clear structure and identifying inconsistencies, Seiso helps prevent the spread of misinformation that can arise from unmanaged, AI-generated content, thereby improving the overall quality of project knowledge bases.

Practical impact

AI builders can integrate Seiso into their development workflows to automate documentation checks. The tool's diagnostics provide specific locations and suggested fixes, enabling AI agents to potentially repair documentation issues autonomously. Developers can start by running seiso init in their repositories to set up a basic configuration and then use seiso check to identify any convention violations. Exploring the preview rules with seiso rule --all and seiso rule <rule_name> can help identify areas for further improvement and potential automation.

Caveats and source limits

The source indicates that Seiso is a fresh release with version v0.2.0. While it offers stable and preview rules, the preview rules are experimental and may produce false positives. The effectiveness of AI agents in repairing findings from seiso's output is described as potential, rather than a guaranteed outcome. The documentation does not provide independent benchmark results for the linter's performance or specific metrics on how it improves documentation quality or agent performance. Pricing information is not available as it is an open-source project. The source also mentions integrations with Claude Code hooks and pre-commit, but detailed implementation guides for these are not elaborated upon in the provided excerpt.

Sources

Written with AI assistance from the linked sources; every claim below was checked against them automatically. How we produce articles.

Claim check: 8/8 supported claims - 8 evidence links - 99% avg confidence
  • Seiso is a Markdown convention and linter for project documentation written by AI and read by humans and agents.supported - github.com
  • Seiso is built using Rust.supported - github.com
  • Seiso is available via Cargo, PyPI, and npm packages.supported - github.com
  • Seiso has a fresh release, version v0.2.0.supported - github.com
  • Seiso defines a convention for organizing Markdown in a repository, similar to how rustfmt formats Rust code.supported - github.com
  • Seiso's rules check documents against its convention, with stable rules running by default and others in opt-in preview.supported - github.com
  • Each diagnostic from Seiso indicates the problem location and suggests a fix, allowing agents to repair most findings.supported - github.com
  • Seiso is licensed under the MIT license.supported - github.com

Caveats

  • The source states agents 'can repair most findings', implying potential rather than guaranteed success.
  • Single-source caution: verify critical details at the linked source.
Radar score 86/100 - how it was calculated
Reliability82
Freshness95
Novelty77
Technical81
Developer96
Ecosystem72
Confidence98
  • Reliability 82: GitHub metadata supports source trust
  • Freshness 95: Fresh GitHub release date
  • Novelty 77: Fresh GitHub release
  • Technical 81: Repository technical metadata
  • Developer 96: Developer tooling signals
  • Ecosystem 72: Fresh GitHub release
  • Confidence 98: Claims have reliable evidence
Share
XLinkedInHacker News

Discussion

Loading comments...

Related articles

Developer Tools - Oct 14, 2026Muxa: tmux Agent Monitoring ToolMuxa is a Rust-based tool designed to monitor tmux sessions running AI coding agents like Claude Code, Codex, and Gemini CLI. It allows developers to quickly see which agent session is active and jump directly to it without needing a wrapper or new terminal.Developer Tools - Nov 8, 2026proc-cli v2.3.0: Semantic Process Management CLIThe proc-cli tool, recently updated to v2.3.0, offers a semantic command-line interface for process management. It allows users to target processes by port, PID, name, or path, and is built using Rust.Developer Tools - Nov 2, 2026Herdr-GPUI Native Client v20261028.1 ReleasedThe Herdr-GPUI project has released version v20261028.1, a native client for Herdr. This client is built with Rust and GPUI, offering a desktop interface for managing terminal sessions, workspaces, Git worktrees, and agent activity via a local Herdr daemon.Developer Tools - Oct 11, 2026Harness Terminal v2.1.0: GPU-Accelerated macOS TerminalHarness Terminal has released version 2.1.0, a native macOS terminal application featuring GPU rendering for enhanced performance. It supports durable sessions, coding-agent workflows, and SSH connectivity, with session host, daemon, and CLI components available for Linux.Developer Tools - Oct 4, 2026AgentHydra v1.7.0: Unified Local AI CodingAgentHydra version 1.7.0 consolidates local AI coding tools, including Claude Code, Codex, and OpenCode, into a single interface. It features a schedulable queue and isolated Claude Desktop instances, operating locally and privately.Developer Tools - Nov 1, 2026Flisk v1.4.23: Run Your Whole App LocallyFlisk, a TypeScript project, has released version 1.4.23, enabling users to run their entire application on their local machine with a single command. This tool aims to simplify local development workflows for microservices and full applications.