Intent

Intent captures why your code exists, in the repository, in a form your team and your coding agents can both read.

Your code says what it does and version control says when it changed. Neither says what you were trying to achieve, what you ruled out, or what breaks if someone changes it. Intent gives that reasoning a place to live that ages with the code instead of away from it.

  $ brew install matthewsinclair/intent/intent

Full documentation is in docs/. If you are new, start at the documentation index; if you are moving a v2 project across, start at Migrating from v2.

What it is

A single CLI, written in Rust, that manages a small set of durable objects inside your repository.

A steel thread is one intention followed end to end. It breaks into work packages, and it states acceptance criteria — the conditions that decide whether the intention was met. Each criterion is backed by an acceptance test, so whether a thread is satisfied is computed rather than asserted.

Around that sits the machinery that makes it survive contact with a real project: a store that is the single source of truth, generated views so nothing is maintained twice, a rule library your coding agents can be held to, per-language critics that check work against those rules, and commit-time gates that refuse changes contradicting what the project said it was doing.

Why it exists

Comments rot because nothing checks them. They sit beside the code, they are not tested, and the first person to change the code under a stale comment usually leaves it there.

Design documents rot because nothing links them. They are correct on the day they are written, and nothing notices when they stop being true.

And a coding agent cannot reconstruct any of it. It reads what the code does and builds confidently on assumptions you would have rejected in one sentence — because the sentence was never written anywhere it could read. Handing an agent more context each session does not fix that; the context has to come from something that cannot silently drift.

A first steel thread

  $ intent init
  $ intent st new "Add user authentication"
  created: ST0001

Then record why it exists and what would make it done:

  $ intent st edit ST0001
  $ intent ac new ST0001 AC-01.1 --text "Sessions survive a server restart"
  $ intent st show ST0001

The reasoning is now a tracked object rather than a paragraph in a chat log, and intent ac gate ST0001 will tell you whether the thread is satisfied instead of asking you to remember.

Getting started follows this through to a satisfied thread on a real project.

Commands

The command reference is generated from the dispatch register at a named revision — see docs/reference/. It is generated rather than hand-written because a command list typed into prose beside the register is a copy of a measured mapping, and it drifts from it silently.

For the surface of a build you actually have in front of you, ask that build: intent --help, and intent <command> --help.

intent help was retired in v3. It refuses with a message saying so. Use intent --help.

Repository layout

.
├── AGENTS.md          # Tool-agnostic LLM config (generated by `intent agents sync`)
├── CLAUDE.md          # Claude Code-specific overlay
├── usage-rules.md     # Prescriptive DO / NEVER contract
├── native/rust/       # The v3 CLI, daemon and services -- the tool itself
├── bin/               # The v2 Bash line, retained while v3 finishes its port
├── docs/              # Public documentation (docs/v2/ is the frozen v2 archive)
├── surface/           # The dispatch register the command reference is generated from
├── lib/templates/     # Single source for all generated content
└── intent/            # This project's own Intent artefacts
    ├── .canon/        # The store: threads and issues as canon
    ├── .config/       # Per-project config and metadata
    ├── st/            # Steel threads (info.md and acceptance.md are generated views)
    ├── docs/          # Internal authoring canon
    ├── llm/           # Module registry and code-placement flowchart
    └── plugins/       # Rules, skills and subagents

Intent is built with Intent, so intent/ here is both the tool's own working record and a worked example of what the tool produces.

Note on intent/st/: info.md and acceptance.md are rendered from the store and say so in their own first lines. Edit them through the CLI; a hand-edit is discarded by the next sync and nothing fails at the moment you make it. design.md, impl.md and tasks.md are yours to write.

Working with coding agents

Intent's LLM-facing surface — the three root config files, the session hooks, the skills, the subagents, the rule library and the per-language critics — is explained end to end in intent/docs/working-with-llms.md. That is the canonical narrative, and it is where the reasoning behind the layout lives.

Contributing

Create a steel thread for the change, record what you are trying to achieve and what would make it done, and reference it in the pull request. The acceptance gate applies to contributions the same way it applies to everything else.

Getting help

• Documentation — install, getting started, concepts, command reference, migration
• intent doctor — findings about the project you are standing in. It does not inspect the installation; intent claude rules list is the check that the support tree arrived
• GitHub Issues — bug reports

License

MIT. See LICENSE.md.