Intent Capture

What is intent capture?

Every supervision session starts with your prompt. Caret captures that prompt and parses it into a structured intent record — a machine-readable representation of what you asked the agent to do. This intent record is the contract that every subsequent tool call is evaluated against.

Intent record structure

An intent record contains three primary fields:

{
  "action": "fix",
  "scope": ["src/auth/**"],
  "keywords": ["token", "refresh", "session"]
}

Action field

The primary verb extracted from your prompt. Caret recognizes these action categories:

Action	Description	Example prompts
fix	Bug fix, error correction	"Fix the login bug", "Fix the broken test"
add	New feature or functionality	"Add rate limiting", "Add a search bar"
update	Modify existing behavior	"Update the API response format"
refactor	Restructure without behavior change	"Refactor UserService to use repository pattern"
delete	Remove code or features	"Delete unused feature flags"
test	Write or fix tests	"Write unit tests for auth module"

Scope field

The files and directories your prompt references. Caret extracts file paths, directory paths, and module names from your prompt text. If no explicit files are mentioned, Caret infers scope from keywords.

• Explicit: "Fix the bug in src/auth/login.ts" → ["src/auth/login.ts"]
• Directory: "Refactor the auth module" → ["src/auth/**"]
• Inferred: "Fix the header component" → ["src/components/Header*"]

Keywords field

Significant nouns and technical terms extracted from your prompt. Used for semantic matching when evaluating whether tool calls are related to your intent.

How parsing works

🖼 Intent extraction flow — prompt text parsed into action, scope, and keywords fields

Intent parsing runs in two tiers:

1. Rule-based extraction (<5ms): Regex patterns extract file paths, action verbs, and known keywords. This covers 80% of prompts accurately.
2. LLM-assisted parsing (optional): For complex or ambiguous prompts, Caret can use a lightweight LLM call to extract intent. This is configurable and off by default.

Examples

Prompt: "Fix the auth token refresh in src/auth/session.ts"
Intent: {
  action: "fix",
  scope: ["src/auth/session.ts"],
  keywords: ["auth", "token", "refresh"]
}

Prompt: "Add rate limiting to the /api/chat endpoint"
Intent: {
  action: "add",
  scope: ["src/api/chat/**"],
  keywords: ["rate limiting", "rate limit", "chat", "endpoint"]
}

Prompt: "Refactor the user service to use dependency injection"
Intent: {
  action: "refactor",
  scope: ["src/services/user/**"],
  keywords: ["user service", "dependency injection"]
}

Manual intent override

When using caret run, you can manually specify the intent for a session:

caret run claude --intent "Fix the login bug in src/auth/"

This is useful for CI environments or when the automatic prompt capture doesn't have access to the full prompt text.