Shiin documentation
Note
Project status: pre-alpha. The first experimental release provides CLI and Unix-daemon archives for Linux and macOS. Rust client and MCP integrations remain available from source; see installation and the roadmap for limits and remaining work.
Shiin is an agent-agnostic authorization layer for AI agent actions. It sits between AI agents (Claude Code, Codex CLI, Cursor, MCP clients, and custom agents) and the things they act on: files, commands, networks, and services. For every action an agent proposes, Shiin decides whether to allow it, deny it, or hold it for a human to approve, and it records evidence of that decision.
Shiin’s decisions are made by explicit, deterministic policy, never by a language model. Policies are written once and apply to every agent. Policies can also be bound to the specific task a developer gave the agent, so an action can be refused because it does not belong to that task, even if it would otherwise be allowed.
What exists, what is specified, and what is planned
| State | What it covers |
|---|---|
| Exists today | The local engine, policy, hooks, CLI, audit log, experimental tasks, Unix approvals/grants, signed evidence/replay, Rust client, MCP proxy, Unix command wrapper, schemas, conformance vectors, and documentation tooling |
| Specified | The action request, decision, evaluation, policy model, intent binding, approval protocol, audit events, receipts, adapter contract, and local API |
| Open | Independent review, live-host and external MCP validation, attested agent identity, remote approvals, Windows daemon transport, and release qualification; see the roadmap |
Start here
| If you are | Read, in order |
|---|---|
| New to Shiin | Vision, How Shiin works, Use cases, Limitations |
| Evaluating Shiin’s security | Threat model, Security model, Enforcement levels, Limitations |
| Comparing Shiin with other tools | Landscape, FAQ |
| Building an adapter or integration | Adapter contract, Action request, Decision, Local API |
| Planning to write policy | Policies, Policy model, Writing policies |
| Contributing code | Workspace and crates, Coding standards, Testing strategy, CONTRIBUTING.md |
| Proposing a change | ADR index, RFC process |
Reading the status banners
Every page starts with a banner that says what kind of page it is and how settled its content is.
- Specification pages are normative contracts. Implementations will be tested against them.
- Design document pages explain the intended design and the reasons behind it.
- Design intent: not implemented pages describe what using Shiin will look like. They are written ahead of the code so the experience can be reviewed before it is built. Nothing on those pages works yet.
- Architecture decision pages record one decision and its status.
- Project policy pages set rules for the project and its contributors.
The documentation style guide defines every label and the checks that keep banners accurate.
Giving feedback
The specification phase is the cheapest time to change the design.
- For a problem in a specification, open an issue using the spec feedback form.
- For anything that might be a way to bypass Shiin, do not open a public issue. Follow SECURITY.md instead.
- For larger changes, read the RFC process.