Native macOS CLI tool for Swift codebase intelligence — find critical files, generate dependency graphs, learning paths, and detailed reports.

Built 100% in Swift using Apple-native technologies. Fully offline. No network required. No telemetry. No accounts.

AI-powered features (natural-language Q&A) are available as a separate opt-in — see AI Integration (Opt-In).

cd SwiftCodeContext # Projects under 200K lines — just run directly swift run codecontext analyze ~/path/to/your/project --open # Large projects (200K+ lines) — release build is 5–10× faster swift build -c release .build/release/codecontext analyze ~/path/to/your/project --open

--open opens the HTML report in Safari.

Every core feature runs entirely on your machine:

• Source parsing — Apple's native SwiftSyntax, no external services
• Dependency graphs & PageRank — computed locally
• Git history analysis — reads your local .git directory
• HTML report generation — self-contained, no CDN links, no external assets
• Caching — actor-based file cache stored on disk

Your code never leaves your machine unless you explicitly enable the optional AI integration and send a query.

cd SwiftCodeContext # Build swift build # Analyze a Swift project swift run codecontext analyze /path/to/your/swift/project # See all commands swift run codecontext --help

cd SwiftCodeContext # Debug build (fast compilation) swift build # Run directly swift run codecontext analyze ~/Projects/MyApp # Release build (optimized, ~3× faster runtime) swift build -c release # The binary is at: .build/release/codecontext

swift build -c release sudo cp .build/release/codecontext /usr/local/bin/ # Now use from anywhere: codecontext analyze ~/Projects/MyApp codecontext evolution --months 12

swift build -c release && sudo cp .build/release/codecontext /usr/local/bin/ && echo "✅ installed"

open Package.swift

In Xcode:

1. Select the codecontext scheme
2. Edit Scheme → Run → Arguments → add: analyze /path/to/your/project
3. ⌘R to build and run

# Analyze current directory codecontext analyze # Analyze specific path codecontext analyze ~/Projects/MyApp # With options codecontext analyze ~/Projects/MyApp --no-cache --verbose --open

# Default: 6 months back, 30-day intervals codecontext evolution # Custom range codecontext evolution --months 12 --interval 7

codecontext init # Creates .codecontext.json with sensible defaults

The generated HTML report is a single self-contained file — open it anywhere, share it, archive it. No internet connection needed to view it.

1. Summary — total files, lines of code, declarations by type (structs, classes, enums, protocols, actors), and package count

2. Team Contribution Map — developer activity tracking with files modified, commit counts, and first/last change dates

3. Dependencies & Imports — comprehensive classification into Apple frameworks, external dependencies, and local Swift packages with interactive tag clouds

4. Assets — media resource analysis showing total size, file count by type, and top 3 heaviest files with their individual sizes

5. Hot Zones — files with the highest PageRank scores, identifying the most connected and architecturally significant code. Each entry includes clickable module badges and inline documentation previews

6. Module Insights — package penetration analysis showing which modules are imported by the most other packages (foundational dependencies), plus quality metrics including TODO/FIXME density and technical debt indicators

7. Longest Functions — ranked list of functions by line count, with clickable module badges and quick navigation to potential refactoring candidates

8. Packages & Modules — detailed breakdown of each local Swift package:

   • Complete file inventory sorted by lines of code
   • Declaration statistics by type (classes, structs, enums, protocols, actors, extensions)
   • Interactive force-directed dependency graph per package, colored by declaration type (🔵 classes, 🟢 structs, 🟡 enums, 🔴 actors)
   • File-level annotations with inline documentation previews
   • Precise line counts and declaration tags for every file
   • Package-level metrics including total files, lines, and declaration distribution

Create .codecontext.json in your project root (or run codecontext init):

{ "excludePaths": [".git", ".build", "DerivedData", "Pods", "Carthage"], "maxFilesAnalyze": 5000, "gitCommitLimit": 1000, "enableCache": true, "enableParallel": true, "hotspotCount": 15, "fileExtensions": ["swift"] }

All options above are offline. No network configuration needed.

This is entirely optional. Every feature described above works without it.

If you want to ask natural-language questions about your codebase, you can enable the AI module. This sends a context summary to an external LLM provider, so review your provider's data policies before enabling.

Add an ai block to your .codecontext.json:

{ "ai": { "enabled": false, "provider": "anthropic", "apiKey": "", "model": "claude-sonnet-4-20250514" } }

codecontext ask "Where is the authentication logic?" codecontext ask "What would break if I refactored UserService?"

When you run ask, a summary of your project structure and relevant code context is sent to the configured provider. Raw source files are not uploaded in full — the tool assembles a focused context window. No data is sent for any other command (analyze, evolution, init).

SwiftCodeContext/ ├── Package.swift ├── Sources/CodeContext/ │ ├── CLI/ │ │ ├── CodeContextCLI.swift # @main entry point │ │ ├── AnalyzeCommand.swift # Main analysis command │ │ ├── AskCommand.swift # AI Q&A command (opt-in) │ │ ├── EvolutionCommand.swift # Temporal analysis │ │ └── InitCommand.swift # Config initialization │ ├── Core/ │ │ ├── AnalysisPipeline.swift # Shared pipeline logic │ │ ├── Config/ │ │ │ └── CodeContextConfig.swift # Config models + loader │ │ ├── Cache/ │ │ │ └── CacheManager.swift # Actor-based file cache │ │ ├── Parser/ │ │ │ ├── ParsedFile.swift # Models + protocol │ │ │ ├── SwiftParser.swift # Swift source parser │ │ │ ├── ObjCParser.swift # ObjC header parser │ │ │ ├── ParserFactory.swift # Parser dispatch │ │ │ └── ParallelParser.swift # Concurrent parsing │ │ ├── Scanner/ │ │ │ ├── RepositoryScanner.swift # Directory walker │ │ │ └── GitAnalyzer.swift # Git history via Process │ │ ├── Graph/ │ │ │ └── DependencyGraph.swift # Graph + PageRank │ │ ├── Generator/ │ │ │ └── LearningPathGenerator.swift │ │ ├── Temporal/ │ │ │ └── TemporalAnalyzer.swift # Evolution tracking │ │ ├── AI/ │ │ │ └── AICodeAnalyzer.swift # URLSession-based AI (opt-in) │ │ └── Exceptions/ │ │ └── CodeContextError.swift │ └── Output/ │ └── ReportGenerator.swift # HTML report └── Tests/CodeContextTests/ └── CodeContextTests.swift 

swift test

• macOS 13+ (Ventura or later)
• Xcode 15+ / Swift 5.9+
• git (comes with Xcode Command Line Tools)
• No internet connection required for core features