Integrations

Intent captures decisions from AI coding tools through a unified agent observer architecture. All integrations use native session watching—no extensions or wrappers required.

Architecture

Intent uses SpecStory CLI as a vendored client library to provide a unified provider interface for all AI tools. Each tool has a dedicated provider that:

1. Watches for session activity in the tool's native storage format
2. Normalizes sessions to a common schema
3. Extracts file operations from tool calls
4. Routes sessions to Intent's journal for correlation and enrichment

┌─────────────────────────────────────────────────────────────────┐
│                    AI Coding Tools                              │
│  Claude Code    Cursor CLI    Codex CLI    Gemini CLI          │
└───────┬─────────────┬─────────────┬─────────────┬──────────────┘
        │             │             │             │
        ▼             ▼             ▼             ▼
┌─────────────────────────────────────────────────────────────────┐
│              SpecStory CLI Provider Interface                   │
│     (unified schema, native watching, file op extraction)       │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Intent Agent Observer                        │
│  (provenance hints → journal → correlation → enrichment)        │
└─────────────────────────────────────────────────────────────────┘

Supported Tools

Claude Code

Provider ID: claude

Intent monitors ~/.claude/projects/<hash>/ for JSONL session files. This is the deepest integration—Claude Code's structured tool output provides explicit file paths and operation types.

What's captured:

• Complete conversation context (user prompts, agent replies)
• All tool calls (Write, Edit, MultiEdit, Read, Glob, Grep, Bash, etc.)
• Explicit file paths from tool inputs
• Content for correlation matching

Detection: File system watching via fsnotify for real-time capture.

Cursor

Provider ID: cursor

Intent monitors ~/.cursor/chats/ SQLite database for session data. Cursor stores chat history in a structured database that Intent queries directly.

What's captured:

• Chat and Composer conversations
• File references and context
• Tool call data where available

Detection: SQLite change detection for database updates.

Codex CLI

Provider ID: codex

Intent monitors OpenAI Codex CLI session files in JSONL format, similar to Claude Code.

What's captured:

• Full conversation transcripts
• Tool use and file operations
• Session metadata and timing

Detection: File watching for session file creation/modification.

Gemini CLI

Provider ID: gemini

Intent monitors Google's Gemini CLI project directory structure for JSON-based session storage.

What's captured:

• Conversation history
• Tool calls and outputs
• Project context

Detection: Directory watching for session updates.

How File Operations Are Extracted

Intent extracts file operations from AI sessions using a multi-layered approach:

1. Declared Paths (High Confidence)

Explicit file paths provided by the tool:

• pathHints field in tool output
• file_path or path parameters in tool inputs

2. Inferred Paths (Lower Confidence)

Regex-based extraction from shell commands:

• Redirections: > file.txt, >> log.txt
• File commands: touch, cp, mv, rm, mkdir
• Heredocs: cat << EOF > file.txt

Each provenance hint includes a confidence level so the correlation engine can weight matches appropriately.

Integration Comparison

All tools normalize to the same unified schema, enabling consistent:

• Provenance hints — File operations linked to exchanges
• Session transcripts — Markdown stored in CRDT for search
• Correlation — 5-dimensional matching to filesystem events
• Enrichment — AI-generated decision summaries

Data Flow

When you use any supported AI tool:

1. Tool writes session data to its native storage location
2. SpecStory provider detects the change via watching
3. Session is normalized to unified SessionData schema
4. Agent observer extracts file operations with confidence levels
5. Provenance hints written to Intent journal
6. Session markdown appended to CRDT for searchability
7. Correlation engine matches hints to filesystem events
8. Enrichment generates decision summaries

This happens automatically in the background. Your workflow stays the same.

Slack Integration

Intent can post session enrichments to Slack for team visibility.

What gets posted:

• Session scope and summary
• Key decisions made
• Technologies used
• Files changed

Setup:

intent configure slack

Follow the prompts to connect your Slack workspace and select a channel.

Sessions post when they go idle for 5+ minutes, providing automatic team updates as work completes.

Adding Support for New Tools

The SpecStory CLI provider interface (pkg/spi/provider.go) defines a standard contract:

type Provider interface {
    Check() (*CheckResult, error)           // Verify tool installation
    DetectAgent() (*DetectResult, error)    // Check if tool used in project
    GetAgentChatSession(id string) (*SessionData, error)
    GetAgentChatSessions() ([]*SessionData, error)
    WatchAgent(ctx context.Context, callback SessionCallback) error
}

New tools can be integrated by implementing this interface and registering with the provider factory.

Troubleshooting

Sessions not appearing:

• Verify the tool is installed: intent status shows detected tools
• Check the tool's session storage location exists
• Ensure Intent daemon is running: intent service start

File operations not linked:

• Correlation requires filesystem events within ±30 seconds of AI session
• Check that files are within the project directory (not ignored by .intentignore)

Partial data captured:

• Some tools provide less structured output than others
• Shell command inference has lower confidence than declared paths