Intent

Git-native reasoning layer for software projects.

Intent lives inside your repo as .intent/ and tracks the why behind code: plans, architectural decisions, constraints, and system context. It's designed to be read by both humans and AI agents.

Git already tracks what changed. Intent tracks why it changed.

Why Intent

Modern codebases have a knowledge problem. Commit messages record what changed. PRs explain why at that moment. But over time, the reasoning behind architectural choices, constraints, and active plans disappears into history.

AI agents have the same problem — they can read your code but they can't read your mind. They don't know that the auth middleware is being rewritten for compliance reasons, or that the listing limit exists because of a vendor contract, or that you're mid-way through a multi-sprint migration.

Intent solves this by making reasoning a first-class artifact, committed alongside code:

git add src/auth/middleware.ts .intent/plans/auth-rewrite.md
git commit -m "Refactor auth middleware for session token compliance"

Installation

npm install -g @dev-sixbyfive/intent

This installs both the intent CLI and the intent-mcp MCP server in one go.

Or with pnpm:

pnpm add -g @dev-sixbyfive/intent

Requirements: Node 18+, must be run inside a git repository.

Install individual packages

If you only need one piece:

npm install -g @dev-sixbyfive/intent-cli   # CLI only
npm install -g @dev-sixbyfive/intent-mcp   # MCP server only

Use @dev-sixbyfive/intent-core or @dev-sixbyfive/intent-schemas if you're building tooling on top of the .intent/ format.

Quick start

# 1. Initialize Intent in your repo
cd your-project
intent init

# 2. Document a plan
intent plan create auth-rewrite --title "Auth middleware rewrite" --system auth

# 3. Record an architectural decision
intent decision add --title "Use short-lived JWTs over session tokens" --system auth

# 4. Before you commit, see what intent context applies to your diff
git add src/auth/
intent review-diff

The .intent/ format

Every .intent/ file uses hybrid frontmatter markdown: structured YAML frontmatter + free-form markdown body. The YAML is machine-readable; the body is human reasoning.

.intent/
  intent.json          ← project config (the only pure JSON file)
  plans/               ← active and historical plans
  decisions/           ← architectural decision records (ADRs)
  systems/             ← system/domain definitions
  constraints/         ← hard and soft constraints
  links/               ← auto-generated index (never edit manually)
    index.json

Plan file

---
id: plan-auth-rewrite
title: Auth middleware rewrite
type: plan
status: active
created: 2024-01-15T09:00:00Z
updated: 2024-01-15T09:00:00Z
system: auth
decisions: [DEC-0001]
constraints: []
tags: [security, compliance]
---

## Goal

Replace the legacy session token middleware with short-lived JWTs.

## Reason

Legal flagged the current session token storage as non-compliant with
the new data residency requirements. Must be resolved before Q2 audit.

## Rules

- Tokens must expire in 15 minutes
- Refresh tokens stored in httpOnly cookies only
- No token data written to application logs

Decision file

---
id: DEC-0001
title: Use short-lived JWTs over session tokens
type: decision
status: active
created: 2024-01-15T09:00:00Z
updated: 2024-01-15T09:00:00Z
system: auth
plans: [plan-auth-rewrite]
tags: [security]
---

## Context

We need to replace the current session token approach. Options were:
opaque session tokens (existing), short-lived JWTs, or a third-party
auth provider.

## Decision

Short-lived JWTs (15 min) with httpOnly refresh tokens.

## Consequences

- Stateless auth — no session store required
- Must implement token refresh flow on the client
- All services need to validate JWTs independently

Constraint file

---
id: CON-0001
title: All tokens must expire within 15 minutes
type: constraint
severity: hard
created: 2024-01-15T09:00:00Z
updated: 2024-01-15T09:00:00Z
system: auth
tags: [security, compliance]
---

## Description

No token issued by the auth service may have a lifetime longer than 15 minutes.
Refresh tokens are exempt but must be stored in httpOnly cookies only.

## Rationale

Required by the Q2 compliance audit. Non-negotiable until legal sign-off.

Statuses

Type	Statuses
Plan	`draft`, `active`, `archived`, `superseded`
Decision	`draft`, `active`, `archived`, `superseded`
System	(no status — systems are always active)
Constraint	`severity: hard` or `soft` — hard constraints are non-negotiable, soft are strong preferences

CLI reference

`intent init`

Initialize Intent in the current git repository.

intent init
intent init --project "my-app"   # explicit project name
intent init --force               # reinitialize existing .intent/

Creates .intent/ with the directory structure and a intent.json config file.

`intent plan create <name>`

Create a new plan file.

intent plan create subscriptions
intent plan create subscriptions --title "Marketplace subscription tiers"
intent plan create subscriptions --system marketplace --status active

Opens a Markdown file at .intent/plans/<name>.md with a structured template.

`intent plan update <name>`

Update a plan's status, title, or system without editing the file manually.

intent plan update auth-rewrite --status archived
intent plan update auth-rewrite --title "Auth middleware rewrite (phase 2)"
intent plan update auth-rewrite --status active --title "New title" --system auth

`intent plan show <name>`

Show full details of a plan, including all metadata and the markdown body.

intent plan show auth-rewrite

`intent plan list`

List all plans, optionally filtered.

intent plan list
intent plan list --status active
intent plan list --system marketplace
intent plan list --tag security

`intent decision add`

Record a new architectural decision. IDs are auto-incremented (DEC-0001, DEC-0002, …).

intent decision add
intent decision add --title "Use Postgres for the event store"
intent decision add --title "Use Postgres for the event store" --system events

`intent decision update <id>`

Update a decision's status, title, or system.

intent decision update DEC-0001 --status superseded
intent decision update DEC-0001 --title "Use short-lived JWTs (revised)"
intent decision update DEC-0001 --system auth

`intent decision show <id>`

Show full details of a decision, including all metadata and the markdown body.

intent decision show DEC-0001

`intent decision list`

List all decisions, optionally filtered.

intent decision list
intent decision list --status active
intent decision list --system auth
intent decision list --tag security

`intent constraint add`

Record a hard or soft constraint. IDs are auto-incremented (CON-0001, CON-0002, …).

intent constraint add --title "No external databases in the core package" --severity hard
intent constraint add --title "Prefer open source dependencies" --severity soft --system core

`intent constraint update <id>`

Update a constraint's title, severity, or system.

intent constraint update CON-0001 --severity soft
intent constraint update CON-0001 --title "No external databases in core or schemas packages"
intent constraint update CON-0001 --system core

`intent constraint show <id>`

Show full details of a constraint, including all metadata and the markdown body.

intent constraint show CON-0001

`intent constraint list`

List all constraints, optionally filtered.

intent constraint list
intent constraint list --severity hard
intent constraint list --system core
intent constraint list --tag compliance

`intent system create <name>`

Create a system/domain definition.

intent system create marketplace
intent system create marketplace --title "Marketplace Domain"

`intent system list`

List all systems.

intent system list

`intent context [system]`

Show all intent context for the project, optionally filtered to a system.

intent context               # all plans, decisions, systems
intent context marketplace   # filtered to the marketplace system

`intent review-diff`

Show intent context relevant to the current git diff. Run this before committing to see which plans and decisions apply to your changes.

intent review-diff             # staged changes only (default)
intent review-diff --all       # staged + unstaged
intent review-diff --base origin/main   # diff against a branch (CI mode)

This is the highest-value command. It cross-references changed files against the links index and surfaces only the context that's relevant to what you're about to commit.

`intent link`

Rebuild the .intent/links/index.json index. Run after adding or editing .intent/ files to keep review-diff results accurate.

intent link

The links index is auto-generated and excluded from git (via .intent/.gitignore). It's rebuilt on demand.

`intent validate`

Validate all .intent/ files and check referential integrity across plans, decisions, and systems.

intent validate               # check everything
intent validate --errors-only # suppress warnings, show errors only

Reports broken cross-references (plan references a decision that doesn't exist, etc.) as errors, and draft plans as warnings. Exits 0 if valid, 1 if there are errors.

`intent status`

Show a health overview of the .intent/ directory.

intent status

Displays:

Plan/decision/system counts
Active and draft plans with their system assignments
Links index freshness
Validation summary (errors and warnings, with a pointer to intent validate for details)

`intent export <target>`

Export intent context to the config file that your editor or AI tool reads automatically.

intent export claude    # → CLAUDE.md
intent export cursor    # → .cursor/rules
intent export copilot   # → .github/copilot-instructions.md
intent export windsurf  # → .windsurfrules
intent export html      # → intent-context.html  (semantic HTML, best for agent parsing)
intent export json      # → intent-context.json  (structured JSON)

All targets support an optional --system filter:

intent export claude --system marketplace

All markdown targets (claude, cursor, copilot, windsurf) export the same content: agent instructions, constraints (hard ones first), active plans, architectural decisions, and systems. The block is wrapped in  /  markers so re-running updates it in place without touching the rest of the file.

The html and json targets always overwrite the output file.

HTML format

intent export html produces a self-contained intent-context.html with three layers:

Embedded JSON blob (<script type="application/json" id="intent-data">) — full structured context for programmatic access, no parsing required
Semantic HTML sections — <section id="plans">, <section id="constraints"> etc., with <article data-id="..." data-status="..." data-system="..."> per record
Rendered body — each record's markdown body converted to HTML for human readability

Agents can query the JSON blob directly or use data-* attributes as CSS selectors (e.g. [data-status="active"]). The file can also be opened in a browser.

`--watch` flag

All targets support --watch, which re-exports automatically whenever any .intent/ file changes:

intent export claude --watch
intent export html --watch

The terminal shows a timestamped line on each successful re-export. Use Ctrl+C to stop.

When to run it: after intent init, and again whenever you add or update .intent/ files. Or use --watch to keep it current continuously during development.

`intent search <query>`

Full-text search across all intent files — plans, decisions, systems, and constraints — ranked by relevance with context excerpts.

intent search "jwt authentication"
intent search "vendor listing limit"
intent search "compliance"

GitHub Action

Add automatic intent context comments to pull requests.

Setup

Copy this workflow into your repo at .github/workflows/intent-pr.yml:

name: Intent PR Context

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  intent:
    name: Post intent context
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: SixByFive/intent/.github/actions/intent-pr@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          base-ref: origin/${{ github.base_ref }}

What it does

When a PR is opened or updated, the action:

Runs intent review-diff --base origin/<base-branch> against the PR diff
Posts a comment listing all relevant plans, decisions, and systems
Updates the existing comment on subsequent pushes (no duplicate comments)

If no related intent context is found, no comment is posted.

Action inputs

Input	Required	Default	Description
`github-token`	Yes	—	GitHub token for posting comments (`secrets.GITHUB_TOKEN` works)
`base-ref`	No	`origin/main`	Git ref to diff against

Testing locally

Test the CLI part directly:

git fetch origin
intent review-diff --base origin/main

To run the full action locally with Docker:

# Install act: https://github.com/nektos/act
act pull_request --secret GITHUB_TOKEN=your_pat

MCP server

Intent ships an MCP server so AI agents can query your intent context directly during a task. The server speaks standard MCP over stdio and works with any MCP-compatible client.

Claude Code

Add to .claude/settings.json in your project, or to ~/.claude/settings.json globally:

{
  "mcpServers": {
    "intent": {
      "command": "npx",
      "args": ["@dev-sixbyfive/intent-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "intent": {
      "command": "npx",
      "args": ["@dev-sixbyfive/intent-mcp"]
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.yaml:

mcpServers:
  intent:
    command: npx
    args:
      - "@dev-sixbyfive/intent-mcp"

ChatGPT desktop

Add to your ChatGPT desktop MCP config (~/Library/Application Support/ChatGPT/mcp.json on Mac, %APPDATA%\ChatGPT\mcp.json on Windows):

{
  "mcpServers": {
    "intent": {
      "command": "npx",
      "args": ["@dev-sixbyfive/intent-mcp"]
    }
  }
}

Note: ChatGPT desktop MCP support requires the ChatGPT desktop app with MCP enabled. See OpenAI's MCP guide for setup steps.

Available tools

Tool	Description
`intent_context`	Get all plans, decisions, systems, and constraints. Optionally filter by system.
`intent_review_diff`	Get intent context relevant to the current git diff. Supports `base` for CI.
`intent_list_plans`	List all plans. Supports `status`, `system`, `tag` filters.
`intent_list_decisions`	List all architectural decisions. Supports `status`, `system`, `tag` filters.
`intent_list_systems`	List all system definitions. Supports `tag` filter.
`intent_list_constraints`	List all constraints. Supports `severity`, `system`, `tag` filters.
`intent_search`	Full-text search across all intent files; returns matches ranked by relevance with excerpts.
`intent_rebuild_links`	Rebuild the links index.
`intent_validate`	Validate all `.intent/` files and check referential integrity.
`intent_status`	Health overview: counts, active/draft plans, links index state, validation summary.
`intent_agent_prepare`	Keyword-score plans/decisions/systems/constraints against a task; return focused context bundle. Persists task to session for use by `intent_agent_review`.
`intent_agent_review`	Review diff coverage and validation; returns checklist, `suggestDecision` signal, and the task from the last prepare session.
`intent_export`	Export context as markdown, HTML, JSON, or write to `claude`/`cursor`/`copilot`/`windsurf` target files.

Example agent workflow

User: Implement the vendor listing limit

Agent calls: intent_agent_prepare "implement vendor listing limit"
  → scores plans/decisions by relevance
  → returns plan-subscriptions, DEC-0007 (listing constraints), sys-marketplace

Agent implements accordingly, without asking the user to re-explain the plan

Agent calls: intent_agent_review (after making changes)
  → checklist: changes covered by plan-subscriptions ✓
  → validation: all files valid ✓
  → suggestDecision: false (changes were linked)

Tools without MCP support

For tools that don't support MCP (web interfaces, older IDE extensions), use intent export to generate a static context file instead. See the CLI reference above.

Agent workflow

Intent has two commands built specifically for AI agent workflows — loading focused context before a task, and reviewing alignment after.

`intent agent prepare [task]`

Get intent context relevant to a task. Keyword-scores all plans, decisions, systems, and constraints against the task description, pulls in cross-referenced items transitively, and falls back to full context when nothing matches or no task is given. The task is persisted to .intent/.agent-session.json so intent agent review can reference it.

intent agent prepare "add OAuth login with GitHub"
intent agent prepare "refactor the payment module"
intent agent prepare          # no task → full context
intent agent prepare "..." --hook   # JSON output for hook injection

The --hook flag emits JSON on stdout — useful for Claude Code hooks that need to inject context into a system prompt before the agent starts working.

`intent agent review`

Review the current diff against intent and validate all files. Produces a structured checklist and flags whether unlinked changes suggest a new decision record is needed. Automatically loads the task from the last agent prepare session.

intent agent review                       # staged changes
intent agent review --base origin/main    # diff against a branch
intent agent review --unstaged            # unstaged changes
intent agent review --hook                # JSON output + exit code for CI/hooks

In interactive (non-hook) mode, if changed files have no linked intent entries, you're prompted:

Did you make architectural decisions not captured above? [y/N]

Answering y walks through a short Q&A (title, context, decision, consequences) and writes a draft DEC-XXXX.md file ready for you to refine.

Wiring into Claude Code hooks

Add to .claude/settings.json to automatically inject relevant context before every tool call:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "intent agent prepare --hook"
          }
        ]
      }
    ]
  }
}

Monorepo structure

packages/
  intent/    — Meta-package: installs CLI + MCP server in one go (@dev-sixbyfive/intent)
  schemas/   — Zod schemas and TypeScript types for the .intent/ format
  core/      — All .intent/ file I/O, parsing, and git integration
  cli/       — Commander-based CLI (thin layer — no business logic)
  mcp/       — MCP server exposing Intent tools to AI agents

Dependency rule: schemas → core → cli/mcp. Core never imports CLI; schemas never import core.

Building from source

git clone https://github.com/SixByFive/intent
cd intent
pnpm install
pnpm build

# Link the CLI globally
cd packages/cli && pnpm link --global
cd ../mcp && pnpm link --global

Development

pnpm dev   # watch mode across all packages

What Intent is not

Not a documentation app — .intent/ is not a wiki
Not a project management tool — it doesn't replace Linear, Jira, or GitHub Issues
Not a SaaS dashboard — no account, no sync, no external dependency
Not a replacement for commit messages or PRs — it complements them

Contributing

Issues and PRs welcome at github.com/SixByFive/intent.

When contributing, keep the dependency rule in mind: schemas → core → cli/mcp. All business logic belongs in core, not in cli command handlers.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github		.github
.intent		.intent
packages		packages
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Intent

Contents

Why Intent

Installation

Install individual packages

Quick start

The .intent/ format

Plan file

Decision file

Constraint file

Statuses

CLI reference

intent init

intent plan create <name>

intent plan update <name>

intent plan show <name>

intent plan list

intent decision add

intent decision update <id>

intent decision show <id>

intent decision list

intent constraint add

intent constraint update <id>

intent constraint show <id>

intent constraint list

intent system create <name>

intent system list

intent context [system]

intent review-diff

intent link

intent validate

intent status

intent export <target>

HTML format

--watch flag

intent search <query>

GitHub Action

Setup

What it does

Action inputs

Testing locally

MCP server

Claude Code

Cursor

OpenAI Codex CLI

ChatGPT desktop

Available tools

Example agent workflow

Tools without MCP support

Agent workflow

intent agent prepare [task]

intent agent review

Wiring into Claude Code hooks

Monorepo structure

Building from source

Development

What Intent is not

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`intent init`

`intent plan create <name>`

`intent plan update <name>`

`intent plan show <name>`

`intent plan list`

`intent decision add`

`intent decision update <id>`

`intent decision show <id>`

`intent decision list`

`intent constraint add`

`intent constraint update <id>`

`intent constraint show <id>`

`intent constraint list`

`intent system create <name>`

`intent system list`

`intent context [system]`

`intent review-diff`

`intent link`

`intent validate`

`intent status`

`intent export <target>`

`--watch` flag

`intent search <query>`

`intent agent prepare [task]`

`intent agent review`

Packages