atomic-cursor

Atomic VCS integration for Cursor.

Automatic turn recording with AI provenance, intent tracking, and knowledge graph skills.

What it does

• 1 session = 1 view — a draft view is created automatically when you start a Cursor session
• Every turn records with provenance — model, vendor, session, turn number, timing
• Tool executions tracked — reads, edits, shell calls captured in a causal decision graph
• Thinking blocks captured — agent reasoning stored as provenance nodes
• Intent workflow — rules prompt guides problem-first development with vault intents

Install

Quick start

git clone https://github.com/atomicdotdev/atomic-cursor
cd atomic-cursor
./install.sh

From npm (once published)

npx atomic-cursor

What install does

1. Hooks — installs hook entries into ~/.cursor/hooks.json (fires atomic agent hooks cursor <verb> on lifecycle events)
2. Rules — must be copied to each project's .cursor/rules/ directory manually

Add rules to a project

mkdir -p .cursor/rules
cp /path/to/atomic-cursor/rules/atomic.md .cursor/rules/atomic.md

Prerequisites

• Atomic VCS installed and on your PATH (atomic --version)
• A project with an .atomic/ repository (atomic init)
• Cursor installed

Usage

cd my-project
atomic init                                    # if not already an atomic repo
cp /path/to/atomic-cursor/rules/atomic.md .cursor/rules/  # add rules
# Open project in Cursor — hooks activate automatically

The hooks automatically:

1. Create a draft view when the session starts
2. Track your prompt and model info
3. Record tool executions in a provenance graph
4. Capture thinking blocks as reasoning nodes
5. Record changes with full AI attestation when a turn ends

You never need to run atomic add or atomic record — the hooks handle it.

Viewing provenance

# Show the causal decision graph (goals → tool calls → patch)
atomic change -p <hash>

# Show inline AI attestation (model, tokens, cost)
atomic change -a <hash>

# Show session-level attestations
atomic agent attest

What's in the package

File	Purpose
hooks.json	Hooks config — merged into ~/.cursor/hooks.json
rules/atomic.md	Agent rules — copy to .cursor/rules/ in each project
skills/atomic-vault/SKILL.md	Vault reference (goals, intents, memory)
skills/code-intelligence/SKILL.md	Knowledge graph query patterns
install.js	Installs hooks into ~/.cursor/hooks.json
install.sh	Development install

How hooks work

Cursor reads hooks from .cursor/hooks.json. The Atomic hooks call back to atomic agent hooks cursor <verb>:

Cursor session start
  │
  ├── sessionStart → Rust creates haikunator-named draft view
  │
  ├── User sends prompt
  │   ├── beforeSubmitPrompt → Rust saves prompt + model on session
  │   ├── Agent works (edits, shell, reads)
  │   │   ├── postToolUse → Rust appends to provenance graph
  │   │   └── afterAgentThought → Rust captures reasoning blocks
  │   └── Turn ends
  │       └── stop → Rust adds files, records change with provenance
  │
  ├── User sends another prompt → repeat
  │
  └── Session ends
      └── sessionEnd → Rust creates attestation

Uninstall

npx atomic-cursor --uninstall

Or manually:

atomic agent disable --agent cursor --global

Rules files in project .cursor/rules/ must be removed manually.

License

Apache-2.0 — same as Atomic VCS.