NextStepAI

A security-first AI agent for macOS that enables workflow automation through natural language commands while maintaining strict security boundaries.

Requirements

• macOS 14.0 (Sonoma) or later
• Xcode 15.0+ or Swift 5.9+
• Apple Silicon or Intel Mac (Universal Binary)

Quick Start

# Clone the repository
git clone <repo-url>
cd NextStepAI

# Resolve dependencies
swift package resolve

# Build
swift build

# Run
.build/debug/NextStepAI

Project Structure

NextStepAI/
├── Package.swift           # Swift Package manifest
├── Sources/
│   ├── NextStepAIApp/      # SwiftUI macOS application
│   ├── NextStepAICore/     # Data models and database
│   ├── NextStepAIPolicy/   # Capabilities and permissions
│   ├── NextStepAITools/    # Tool system
│   ├── NextStepAISecrets/  # Keychain integration
│   ├── NextStepAIBrowser/  # Browser automation
│   ├── NextStepAIAudit/    # Audit logging
│   └── NextStepAIProviders/# Model provider abstraction
├── Tests/                  # Unit and integration tests
├── SPEC.md                 # Product specification
├── TECHNICAL-IMPLEMENTATION-PLAN.md
└── CLAUDE.md               # Development context for AI assistants

External Dependencies

GRDB.swift

Attribute	Value
Name	GRDB.swift
Version	6.29.3
Repository	https://github.com/groue/GRDB.swift
License	MIT
Purpose	Type-safe SQLite database wrapper
Location	.build/checkouts/GRDB.swift (auto-managed by SPM)

GRDB.swift is used for:

• Local database storage (sessions, messages, audit logs)
• Type-safe query building
• Database migrations
• Future: SQLCipher encryption support

Note: The .build/ directory is auto-managed by Swift Package Manager and should be in .gitignore. Dependencies are resolved automatically when you run swift package resolve or swift build.

Adding SQLCipher Support (Future)

To enable database encryption, replace the GRDB dependency with:

// In Package.swift
.package(url: "https://github.com/nicoschtein/GRDB.swift.git", branch: "SQLCipher")

Planned Dependencies (Not Yet Added)

Dependency	Purpose	Status
Node.js (bundled)	Playwright runtime	Pending
Playwright	Browser automation	Pending

Architecture

NextStepAI follows a modular architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│                    NextStepAIApp (SwiftUI)                  │
├─────────────────────────────────────────────────────────────┤
│  NextStepAICore  │  NextStepAIPolicy  │  NextStepAIProviders│
├─────────────────────────────────────────────────────────────┤
│  NextStepAITools │  NextStepAISecrets │  NextStepAIBrowser  │
├─────────────────────────────────────────────────────────────┤
│                    NextStepAIAudit                          │
└─────────────────────────────────────────────────────────────┘

Security Model

1. Capability-based permissions - Tools require explicit grants
2. Security levels - Lockdown, Read-Only, Standard, Elevated
3. Approval flows - Risky actions require user confirmation
4. Secret handles - AI model never sees raw credentials
5. Domain allowlists - Browser restricted to approved sites
6. Audit logging - Tamper-evident logging with hash chains

Development

Building

swift build                    # Debug build
swift build -c release         # Release build

Testing

swift test                     # Run all tests
swift test --filter CoreTests  # Run specific test target

Cleaning

swift package clean            # Clean build artifacts
rm -rf .build                  # Full clean (re-downloads dependencies)

Documentation

• SPEC.md - Product specification
• TECHNICAL-IMPLEMENTATION-PLAN.md - Implementation plan
• CLAUDE.md - Development context for resuming work

License

[License information here]