If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kean/Pulse shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3w ago
• 14 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kean/Pulse repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kean/Pulse.

What it runs against: a local clone of kean/Pulse — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kean/Pulse | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 49 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kean/Pulse. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kean/Pulse.git
#   cd Pulse
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kean/Pulse and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kean/Pulse(\\.git)?\\b" \\
  && ok "origin remote is kean/Pulse" \\
  || miss "origin remote is not kean/Pulse (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Demo/Sources/Pulse.xcodeproj/project.pbxproj" \\
  && ok "Demo/Sources/Pulse.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: Demo/Sources/Pulse.xcodeproj/project.pbxproj"
test -f "Demo/Sources/Package.swift" \\
  && ok "Demo/Sources/Package.swift" \\
  || miss "missing critical file: Demo/Sources/Package.swift"
test -f "Demo/Sources/Integrations/IntegrationsExamples/URLSessionAutomatedIntegration.swift" \\
  && ok "Demo/Sources/Integrations/IntegrationsExamples/URLSessionAutomatedIntegration.swift" \\
  || miss "missing critical file: Demo/Sources/Integrations/IntegrationsExamples/URLSessionAutomatedIntegration.swift"
test -f "Demo/Sources/Shared/MockStore.swift" \\
  && ok "Demo/Sources/Shared/MockStore.swift" \\
  || miss "missing critical file: Demo/Sources/Shared/MockStore.swift"
test -f "Demo/Sources/iOS/Pulse_Demo_iOSApp.swift" \\
  && ok "Demo/Sources/iOS/Pulse_Demo_iOSApp.swift" \\
  || miss "missing critical file: Demo/Sources/iOS/Pulse_Demo_iOSApp.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 49 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~19d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kean/Pulse"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Pulse is a native Swift logging framework for Apple platforms that captures and displays URLSession network requests and system logs directly within iOS/tvOS/macOS/watchOS apps using SwiftUI. It records events from URLSession and libraries like Alamofire, storing logs locally on-device and enabling real-time inspection, filtering, and sharing to Pulse Pro (a companion macOS app) without acting as a network proxy. Single-package structure: /Sources contains the core Pulse framework; /Demo contains Xcode project with integration examples for Alamofire, Moya, and URLSession (both manual and automated). Integration examples in Demo/Sources/Integrations/IntegrationsExamples/ demonstrate real-world usage patterns. Companion framework PulseUI and PulseLogHandler are referenced in docs but likely separate repos.

iOS/macOS developers and QA teams who need to debug network requests and view application logs on test devices without external tools. They integrate PulseUI views directly into debug builds to inspect logs, filter by request/response, and export logs for bug reports.

Production-ready and actively maintained. The repo shows Swift 5.10+ support, Xcode 15.4+ requirements, and a mature multi-platform architecture (iOS 15+, tvOS 15+, watchOS 8+, macOS 12+, visionOS 1+). CI/CD is configured via .github/workflows/ci.yml and validation scripts exist (.scripts/validate.sh, .scripts/test.sh). However, specific commit recency and open issue counts are not visible in provided data.

Low risk for active use. Single maintainer (kean) is known for well-maintained Swift libraries. No large dependency tree evident from file list (only shell scripts and build configuration visible). Main risks: tight coupling to URLSession internals may break with iOS updates, and remote logging feature requires proper security review for production. Breaking changes documented in CHANGELOG.md suggest transparent versioning.

The repository actively supports latest Apple platforms (visionOS added in v5.0). Demo app includes integration examples for popular networking libraries. Validation and linting scripts (.scripts/lint.sh, .scripts/build.sh) indicate ongoing quality checks. Specific recent changes are not visible, but README references Pulse Pro as an active companion product.

Clone and open the demo: git clone https://github.com/kean/Pulse.git && cd Pulse && open Demo/Pulse.xcodeproj. Run build script to validate: .scripts/build.sh. Run tests: .scripts/test.sh. No external dependencies or package managers required for initial exploration.

Daily commands: Open Demo/Pulse.xcodeproj in Xcode 15.4+, select target 'Pulse Demo iOS' or 'Pulse Demo tvOS' or 'Pulse Integration Examples iOS', and press Cmd+R. Build script: .scripts/build.sh (check contents for exact invocation). Swift package: swift build if using SPM directly.

• Demo/Sources/Pulse.xcodeproj/project.pbxproj — Primary Xcode project configuration for the Pulse framework and demo apps across iOS, tvOS, and macOS platforms.
• Demo/Sources/Package.swift — Swift Package Manager manifest defining Pulse library targets, dependencies, and platform support.
• Demo/Sources/Integrations/IntegrationsExamples/URLSessionAutomatedIntegration.swift — Core URLSession integration example showing how Pulse automatically captures network requests from URLSession.
• Demo/Sources/Shared/MockStore.swift — Mock data store implementation demonstrating how Pulse stores and manages logged network requests and events.
• Demo/Sources/iOS/Pulse_Demo_iOSApp.swift — Entry point for iOS demo app that integrates Pulse logging and UI into a SwiftUI application.
• CHANGELOG.md — Release history and API changes documenting breaking changes and new features contributors must track.
• .github/workflows/ci.yml — CI/CD pipeline defining test, lint, and build requirements that all PRs must pass.

• URLSession Integrations (Automated & Manual) (URLSession, URLSessionDataTask, URLSessionDelegate) — Transparent or explicit request/response capture via URLSession delegates and task observers
  • Failure mode: If delegate not registered, requests pass through unlogged; if response parsing fails, malformed log entries created
• Third-Party Framework Adapters (Alamofire plugin system, Moya plugin architecture) — Alamofire, Moya, and other networking library integrations that bridge to Pulse logging
  • Failure mode: If adapter not installed, framework requests bypass Pulse; mismatched library versions cause runtime errors
• MockStore (Swift collections, optional file I/O, date/timestamp management) — In-memory and optional persistent storage for captured network requests, logs, and metadata
  • Failure mode: Memory overflow if logs unbounded; disk full if persistence enabled; data loss on app crash if not flushed
• PulseUI (SwiftUI Views) (SwiftUI, Navigation, state management) — User-facing console displaying logs, network timeline, request/response details with filtering and export
  • Failure mode: Large datasets cause UI lag; memory pressure if rendering thousands of log entries at once
• Platform-Specific App Delegates (UIKit AppDelegate, SwiftUI App protocol, platform APIs) — iOS AppDelegate, SceneDelegate, and tvOS/macOS equivalents managing Pulse initialization and lifecycle
  • Failure mode: If Pulse not initialized early, network requests before setup are missed

Add a New Network Framework Integration

1. Create new integration file in Demo/Sources/Integrations/IntegrationsExamples/ following URLSessionAutomatedIntegration.swift pattern (Demo/Sources/Integrations/IntegrationsExamples/{NewFramework}Integration.swift)
2. Implement network request interception using the framework's delegate/proxy mechanism (Demo/Sources/Integrations/IntegrationsExamples/{NewFramework}Integration.swift)
3. Register the integration in MockStore to capture and store requests (Demo/Sources/Shared/MockStore.swift)
4. Add integration example to ViewController.swift or demo screens (Demo/Sources/Integrations/IntegrationsExamples/DebugAnalyticsView.swift)

Add a New Demo Screen

1. Create SwiftUI View file in Demo/Sources/iOS or tvOS directories (Demo/Sources/iOS/YourFeatureView.swift)
2. Import Pulse and integrate PulseUI components for log display (Demo/Sources/iOS/YourFeatureView.swift)
3. Add navigation entry in the main app view (Demo/Sources/iOS/Pulse_Demo_iOSApp.swift)

Add Platform Support (New Apple OS)

1. Create new platform directory in Demo/Sources/{PlatformName}/ with app entry point (Demo/Sources/{PlatformName}/Pulse_{PlatformName}App.swift)
2. Create Assets.xcassets with app icons in platform-specific format (Demo/Sources/{PlatformName}/Assets.xcassets)
3. Add target to Package.swift with platform-specific constraints (Demo/Sources/Package.swift)
4. Add build scheme to Xcode project for the new platform (Demo/Pulse.xcodeproj/project.pbxproj)

• SwiftUI — Modern, declarative UI framework native to Apple platforms enabling cross-device UI code reuse for iOS, tvOS, and macOS
• URLSession Delegation — Standard Apple framework for HTTP networking; Pulse intercepts via delegates without requiring proxy infrastructure
• Swift Package Manager — Native Swift dependency management enabling modular architecture and easy integration into developer workflows
• LocalStorage/CoreData approach — Logs stored locally on-device ensuring privacy and security; never transmitted unless explicitly shared by user

• Not a network proxy; transparent logging via framework integration instead

  • Why: Avoids system-level proxy setup complexity and works with HTTPS without cert installation
  • Consequence: Cannot log requests from frameworks that don't use URLSession; requires explicit integration per library

• In-app console UI with optional remote export to Pulse Pro

  • Why: Keeps logs private by default while enabling optional cloud viewing; no mandatory backend dependency
  • Consequence: Real-time remote viewing requires opt-in; developers must decide when to enable network transmission

• SwiftUI-only UI (no UIKit fallback)

  • Why: Simplifies codebase and aligns with Apple's modern framework direction
  • Consequence: Requires iOS 13.1+ / tvOS 13.0+ / macOS 10.15+; cannot support older OS versions

• Does not handle authentication or credential management
• Not a real-time packet sniffer or system-level network proxy
• Does not support Linux or non-Apple platforms
• Not designed for production apps (intended for test builds and QA)
• Does not replace dedicated network debugging tools like Proxyman or Charles

No package manager (CocoaPods, Carthage) configuration visible — must use SPM or Xcode project directly. Swift 5.10 minimum is strict; older Xcode versions will fail silently. Remote logging feature (mentioned in README) may require API key configuration not documented in provided file list. URLSession interception relies on swizzling or delegation hooks that may conflict with other logging libraries or proxies.

• URLSession Delegation and Interception — Pulse captures network traffic by hooking into URLSessionDelegate callbacks; understanding delegation is essential to grasp how Pulse intercepts requests without breaking normal flow
• SwiftUI ObservableObject and State Management — Pulse UI uses ObservableObject to reactively display logs; you need this pattern to add custom filtering or export features to PulseUI
• Conditional Compilation and Platform Targets — Pulse supports 5 different Apple platforms (iOS, tvOS, watchOS, macOS, visionOS) via conditional compilation flags (#if os(iOS) etc.); critical for understanding multi-platform code organization
• URLSessionConfiguration and Custom Delegates — Pulse may require custom URLSessionConfiguration to inject its logging delegate; understanding config is key to making Pulse work with existing session setups
• Persistent Local Storage (Core Data or SQLite) — Logs must persist across app launches; Pulse stores them locally without cloud sync — understanding the storage layer is crucial for adding search, archival, or encryption features
• Message Passing and Weak References in Swift — Network logging involves capturing requests from background URLSession tasks; weak/strong reference cycles are common pitfalls in delegate-based logging
• SwiftUI Environment and Dependency Injection — PulseUI views are injected into app hierarchies via @EnvironmentObject; understanding SwiftUI dependency patterns is required to integrate Pulse console into your own screens

• Alamofire/Alamofire — Pulse integrates with Alamofire for network logging; Alamofire users are primary audience for this integration
• kean/Get — Sibling library by same author; Get is a type-safe HTTP client that works seamlessly with Pulse logging
• apple/swift-log — Pulse provides a SwiftLog backend (PulseLogHandler) to capture structured logs alongside network events
• pointfreeco/swift-composable-architecture — Reference architecture for state management in SwiftUI apps that use Pulse for logging effects and side effects
• realm/realm-swift — Potential alternative persistence layer if Pulse storage is considered; many iOS apps pair both for data + logging

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for URLSession integration layer

The repo contains multiple integration examples (AlamofireIntegration.swift, MoyaIntegration.swift, URLSessionManualIntegration.swift) but there's no evidence of unit tests for the core URLSession logging mechanism. Testing the network interception, request/response capture, and edge cases (redirects, errors, large payloads) would ensure reliability across integrations and prevent regressions.

• [ ] Create Tests/ directory structure mirroring Sources/
• [ ] Add unit tests in Tests/URLSessionLoggingTests.swift for request/response capture
• [ ] Test edge cases: redirects, authentication failures, timeouts, large file uploads/downloads
• [ ] Reference Demo/Sources/Integrations/IntegrationsExamples/URLSessionManualIntegration.swift and URLSessionAutomatedIntegration.swift
• [ ] Update .scripts/test.sh to run the new test suite

Add tvOS-specific integration tests and examples

The repo has tvOS support (Demo/Sources/tvOS exists with assets) and tvOS scheme (Pulse Demo tvOS.xcscheme), but there are no dedicated tvOS integration examples or tests. tvOS has unique constraints (no URLSession backgrounding, limited UI patterns) that should be documented and tested to ensure feature parity.

• [ ] Create Demo/Sources/tvOS/IntegrationsExamples/ directory
• [ ] Add tvOS-specific integration examples (e.g., TVOSURLSessionIntegration.swift) handling tvOS limitations
• [ ] Document tvOS-specific setup and limitations in a tvOS_INTEGRATION.md file
• [ ] Add tvOS-specific test target in Demo/Pulse.xcodeproj using Demo/Sources/tvOS/Assets.xcassets as reference
• [ ] Update CI workflow (.github/workflows/ci.yml) to build and test tvOS scheme

Create integration documentation for Moya and Alamofire with examples

The repo contains AlamofireIntegration.swift and MoyaIntegration.swift but lacks integration guides. New contributors and users struggle to understand how to wire these frameworks. A dedicated guide with working examples, common pitfalls, and version compatibility would improve adoption.

• [ ] Create INTEGRATIONS.md at repo root documenting Alamofire, Moya, and Get integrations
• [ ] Reference existing Demo/Sources/Integrations/IntegrationsExamples/AlamofireIntegration.swift and MoyaIntegration.swift
• [ ] Include code snippets for: setup, initialization, configuration options, and troubleshooting
• [ ] Add version compatibility matrix (Pulse version vs Alamofire/Moya versions)
• [ ] Cross-reference from README.md with link to INTEGRATIONS.md

• Add SwiftUI preview coverage for PulseUI components referenced in docs but not visible in demo — start in Demo/Sources/Integrations/ by creating preview-enabled views
• Expand integration examples: create Demo/Sources/Integrations/IntegrationsExamples/URLEncodedFormIntegration.swift demonstrating form-encoded POST requests, currently only JSON examples exist
• Document the storage mechanism (Core Data vs filesystem) in README — inspect actual log storage implementation in Sources/ and update README.md with architecture diagram

Pulse is a network logging framework with a moderate security posture. The primary concerns are around sensitive data exposure through logging (captured credentials, API keys, PII), local log storage security, and the risk of accidental data leakage when sharing logs. The framework itself appears well-structured and maintained. Main recommendations focus on implementing robust sensitive data filtering, encryption at rest for stored logs, user warnings for share functionality, and comprehensive security documentation. The framework should provide clear APIs and configurations for users to control what data gets logged and how it's protected.

• Medium · Potential Sensitive Data Logging in Network Logger — Pulse framework core logging functionality (network request interception). Pulse is a network logging framework that records URLSession requests and responses. There is a risk that sensitive data (API keys, authentication tokens, personal information) could be inadvertently logged if proper filtering is not implemented. The framework stores logs locally, but without explicit sensitive data filtering mechanisms, this could expose credentials. Fix: Implement comprehensive sensitive data filtering mechanisms, provide configuration options to redact headers (Authorization, X-API-Key, etc.), request/response bodies containing sensitive patterns, and document best practices for users to avoid logging sensitive data. Consider implementing automatic redaction of common sensitive header patterns.
• Medium · Local Log Storage Security — Local storage mechanism for logs. The framework stores logs locally on the device ('Logs are stored locally and never leave your devices'). Without proper file-level encryption or access controls, sensitive logged data could be exposed if the device is compromised or accessed by malicious actors with file system access. Fix: Implement file-level encryption for stored logs using platform APIs (FileProtection on iOS, NSData encryption), set appropriate file permissions, and provide options for users to encrypt sensitive log data at rest. Consider using the device's secure enclave where applicable.
• Medium · Log Share Functionality - Potential Data Leakage — Log sharing and export functionality. The ability to 'Share logs' (mentioned in README) could lead to accidental exposure of sensitive information if users are not properly warned about the content being shared. The sharing mechanism may expose all captured data including headers, body content, and potentially PII. Fix: Implement warnings before sharing logs, provide a preview/sanitization feature, allow users to exclude sensitive headers/data before export, add metadata about what data is included in the share, and implement clear user consent flows for data sharing.
• Low · Third-party Framework Integration Risk — Demo/Sources/Integrations/ - AlamofireIntegration.swift, MoyaIntegration.swift. The framework integrates with multiple third-party libraries (Alamofire, Moya, Get frameworks shown in demo integrations). These dependencies may introduce vulnerabilities that could compromise the logging system. Fix: Maintain an inventory of all third-party dependencies, regularly audit them for known vulnerabilities using tools like OWASP Dependency-Check or Swift Package vulnerability scanners, pin dependency versions to known-safe releases, and keep documentation current on compatible versions.
• Low · Missing Security Documentation — README and documentation files. No explicit security guidelines or privacy policy visible in the provided file structure. Users may not understand the security implications of using this logging framework or the risks of storing network logs. Fix: Create comprehensive security documentation including: what data is logged, security best practices, how to properly sanitize logs before sharing, encryption options, compliance considerations (GDPR, CCPA), and clear warnings about sensitive data handling.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.