seiso CLI
A convention and linter for project Markdown written by AI: each fact has one home and each page one kind.
- 195 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The utility reads the repository Markdown and writes only the `seiso.toml` file.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/seisoDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The utility reads the repository Markdown and writes only the `seiso.toml` file.
This is third-party code. Review the repository files before installing.
What it does
seiso defines one convention for organizing Markdown in a repository, the way rustfmt settled formatting for Rust code. Every document declares one kind, such as `howto`, `reference` or `adr`, and holds only what that kind is for. A fact lives in one place and other pages link to it. Rules check documents against the specification: fast-changing values such as versions and counts on long-lived pages, pointers with no file or symbol, addresses to the requester and narration of how a page was made. Each diagnostic names the place and the fix, so an agent repairs most findings from the output. `seiso init` writes a starter `seiso.toml`, `seiso check` runs the stable rules and `--preview` enables experimental ones.
Who it is for. Teams where agents write documentation faster than people can review it and pages go stale and contradict one another.
Good fit when
- A version appears in three places across README and `docs/` and two of them are stale.
- An agent rewrote the docs and pages with no clear kind, mixing how-to and rationale, must be caught.
- Document checks are wired into CI and a Claude Code hook after edits.
- A new repository needs a starter layout of document kinds from `seiso init`.
Not a fit when
- You need spelling and Markdown formatting checks, which other tools handle.
- You need to detect whether text sounds machine-written.
- The documents do not belong to a project and need no kind or source.
Example request
Run seiso check over the repository and fix the violations from the hints, and bring any ownership decisions about a fact to me.Limitations
The convention is provisional: the specification is versioned separately and may change before 1.0.0. Stable rules run by default, while the rest run only under `--preview`, can report false positives and do not belong in CI gates. Review the `seiso init` suggestions before relying on them. The tool does not guess whether text sounds machine-written and does not check spelling. Judgment calls such as picking the page that owns a fact are recorded in the diagnostic as a human decision.
How to disable. Remove the binary with `cargo uninstall seiso`, `uv tool uninstall seiso` or `npm uninstall -g @scarletkc/seiso`. Delete `seiso.toml` and the hook and CI entries by hand.
FAQ
How do I install seiso?
`cargo install seiso`. Alternatives are `uv tool install seiso` or `pipx install seiso` and `npm install -g @scarletkc/seiso`. The PyPI and npm packages include prebuilt binaries for macOS, Linux and Windows.
Which document kinds exist?
For example `howto`, `reference` and `adr`. The rule of thumb: a how-to gives steps, and why the design looks that way goes to an ADR.
How do I learn what a rule means?
With `seiso rule <CODE>`, which explains the rule with examples. `seiso rule --all` lists every rule with its status.
How do I wire it into Claude Code?
The integrations guide describes Claude Code hooks, pre-commit and CI. A `.pre-commit-hooks.yaml` file sits in the repository.
What does `seiso parse` do?
It shows the document model without running rules so you can see how seiso read the Markdown.
Discussion
No questions or reviews yet.
Related
CLI toolsA Rust port of docling that turns PDF, Office, HTML and scans into Markdown and JSON in one binary, with an MCP mode
The CLI checks and formats Markdown so an agent can report violations before applying agreed changes.
Seven plain-language skills inspired by ISO 24495: legal drafting, technical writing, document audits and an agent output style
A document pipeline skill: anything to markdown, markdown to clean html and publisher-grade docx, and html back to markdown
A CLI and skill that export Feishu and Lark docs, sheets and wikis to Markdown and let an agent read or append to them.
A CLI and skill for an agent to publish reports and specs as HTML documents that a team comments on, with every version kept
README in short
The implementation is separate from the convention specification, which has examples and an adoption guide on the project site. Rules meet promotion criteria before they become stable.