Importing Existing Specs

If you've been using Claude Code, you already have a rich history of conversations that describe features, bug fixes, and implementation decisions. The Historical Import feature lets you import this history into SF Veritas as specs, giving you instant traceability for past work.

What Gets Imported

When you import Claude Code history, SF Veritas extracts:

Data	Description
Conversations	Each Claude Code session becomes a spec with the full conversation history
Git Commits	Commits made during the time period are linked to relevant specs
File References	Files mentioned in conversations are linked to their specs

How It Works

Claude Code Project Discovery

Claude Code stores conversation logs in ~/.claude/projects/. Each project folder corresponds to a repository you've worked on:

~/.claude/projects/
├── -Users-yourname-code-my-app/           # /Users/yourname/code/my-app
├── -Users-yourname-work-api-server/       # /Users/yourname/work/api-server
└── -Users-yourname-projects-web-frontend/ # /Users/yourname/projects/web-frontend

The import wizard automatically discovers these projects and shows you:

• Project name and path
• Number of conversations
• Last activity date
• Whether the git repository still exists

Conversation Parsing

Each conversation (.jsonl file) is parsed to extract:

• Title - First user message (truncated for readability)
• Timestamp - When the conversation started
• Message count - Number of exchanges
• File references - Files that were read, edited, or discussed

Path Resolution

Claude Code encodes repository paths by replacing / with - in folder names. However, folder names containing hyphens create ambiguity:

-Users-dev-my-cool-project

Could be:
├── /Users/dev/my-cool-project    (folder: my-cool-project)
├── /Users/dev/my/cool/project    (folders: my, cool, project)
├── /Users/dev/my/cool-project    (folders: my, cool-project)
└── /Users/dev/my-cool/project    (folders: my-cool, project)

SF Veritas resolves this ambiguity using a two-step process:

1. Filesystem validation - Check which path interpretations actually exist
2. Conversation analysis - Examine file paths referenced in conversations to determine the correct repository

This ensures accurate matching even when you have similarly-named projects.

Import Wizard

Accessing the Import Wizard

1. Open the SF Veritas Desktop Application
2. Go to Settings
3. Under Historical Import, click Import Claude Code History

Step 1: Project Discovery

The wizard automatically scans ~/.claude/projects/ and displays discovered projects:

Column	Description
Project	Repository name and full path
Conversations	Number of Claude Code sessions found
Last Activity	When you last used Claude Code in this project
Git	Badge shown if the repository still exists

By default, all projects are selected. Uncheck any you don't want to import.

Step 2: Import

Click Import to begin. For each selected project:

1. Source created - A data source is registered for the repository
2. Conversations scanned - JSONL files are parsed and indexed
3. Git history scanned - Commits from the repository are imported (if it exists)
4. Notes created - Each conversation becomes a spec/note
5. Links established - Git commits are linked to relevant specs

The progress bar shows:

• Current project being imported
• Number of projects completed vs. total

Step 3: Verification

Once complete, you'll see a summary of what was imported. You can then:

• View imported specs in the Notes panel
• Browse git commit history linked to specs
• Use the Spec Graph to visualize relationships

What to Expect After Import

Notes Panel

Each imported conversation appears as a note with:

• Status: note (can be changed to todo, in_progress, complete)
• Content: Summary of the conversation
• Tags: Auto-generated based on content
• Links: Connected git commits and code references

Spec Graph

The Spec Graph visualizes relationships between:

• Specs (notes/requirements)
• Code (functions, classes, files)
• Commits (git history)

Imported conversations will show connections to:

• Files that were modified during the conversation
• Git commits made around the same time
• Functions and classes that were discussed

Best Practices

Import Early

Import your Claude Code history early in your SF Veritas adoption. This gives you:

• Immediate value from past work
• Context for ongoing development
• A foundation for future spec-driven development

Review and Organize

After import, spend time reviewing:

• Mark important specs with appropriate status (todo for unfinished work)
• Add tags to group related specs
• Link specs to code that wasn't automatically detected

Continuous Sync

Enable Continuous Sync in Settings to automatically import new conversations as they're created. This keeps your spec history up-to-date without manual intervention.

Troubleshooting

No Projects Found

If the wizard shows "No Claude Code projects found":

1. Verify Claude Code has been used: ls ~/.claude/projects/
2. Check that projects contain .jsonl files
3. Ensure you have read permissions on the directory

Wrong Repository Matched

If a project is matched to the wrong repository:

1. The path resolution uses file references from conversations
2. If conversations don't reference any files, it falls back to:
   • Git repository detection (prefers paths with .git)
   • Longest valid path
3. You can manually correct links after import in the Spec Graph

Import Failed for a Project

Check the console for errors. Common issues:

• Permission denied - Ensure read access to the project folder
• Invalid JSON - Some .jsonl files may be corrupted; they'll be skipped
• Git errors - Repository may have been moved or deleted

Technical Details

Storage Location

Imported data is stored in the SF Veritas database:

• macOS: ~/Library/Application Support/SF Veritas/
• Windows: %APPDATA%\SF Veritas\
• Linux: ~/.config/SF Veritas/

Data Model

Entity	Description
ImportSource	Registered data source (repository + Claude project folder)
ClaudeConversation	Parsed conversation with metadata
ImportedGitCommit	Git commit imported from repository
SpecGitCommit	Link between a spec and a git commit
Note	The spec itself (created from conversation)

Privacy

All data remains local. The import process:

• Reads from your local ~/.claude/ directory
• Stores data in your local SF Veritas database
• Never sends conversation content to external services