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/johnbean393/Sidekick 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 4 active contributors
• MIT licensed
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ No CI workflows detected

_{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 johnbean393/Sidekick repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/johnbean393/Sidekick.

What it runs against: a local clone of johnbean393/Sidekick — 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 johnbean393/Sidekick | 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 ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of johnbean393/Sidekick. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/johnbean393/Sidekick.git
#   cd Sidekick
#
# 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 johnbean393/Sidekick and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "johnbean393/Sidekick(\\.git)?\\b" \\
  && ok "origin remote is johnbean393/Sidekick" \\
  || miss "origin remote is not johnbean393/Sidekick (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 ".github/ISSUE_TEMPLATE/bug_report.md" \\
  && ok ".github/ISSUE_TEMPLATE/bug_report.md" \\
  || miss "missing critical file: .github/ISSUE_TEMPLATE/bug_report.md"
test -f "About/mission.md" \\
  && ok "About/mission.md" \\
  || miss "missing critical file: About/mission.md"
test -f "Features/conversations.md" \\
  && ok "Features/conversations.md" \\
  || miss "missing critical file: Features/conversations.md"
test -f "Features/localModels.md" \\
  && ok "Features/localModels.md" \\
  || miss "missing critical file: Features/localModels.md"
test -f "Features/experts.md" \\
  && ok "Features/experts.md" \\
  || miss "missing critical file: Features/experts.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/johnbean393/Sidekick"
  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).

Sidekick is a native macOS application that enables local-first AI conversations powered by llama.cpp, allowing users to chat with local GGUF models (like Qwen3.5) that can retrieve and reference information from files, folders, and websites without cloud dependencies. It implements RAG (Retrieval Augmented Generation) to contextualize LLM responses with user-owned documents and supports OpenAI-compatible APIs as a fallback for additional model options. Monolithic Swift macOS app: likely organized with SwiftUI views in the main target, llama.cpp bindings/wrapper layer for inference, and modular feature groups (Experts, Canvas, Memory, Function Calling) as separate SwiftUI view hierarchies. Configuration and state likely managed in a central settings/preferences layer given the diverse feature toggles visible in feature screenshots.

macOS users (students, researchers, professionals) who need AI assistance with document analysis, fact verification, and research while maintaining data privacy and offline operation. Developers contributing to the repo are primarily Swift developers building native macOS applications with AI capabilities.

The project shows active development with 1.5M+ lines of Swift code and a comprehensive feature set (Experts, Deep Research, Function Calling, Memory, Canvas), suggesting maturity beyond experimental. Without visible GitHub stars or recent commit timestamps in the provided data, assess by the breadth of features documented in Docs Images/ (60+ feature screenshots) and the structured codebase organization, indicating solid production readiness.

Primary risk is single-maintainer dependency (johnbean393 as sole owner per repo name). Risks include: llama.cpp version pinning constraints (embedded inference engine), potential Swift ecosystem churn with macOS SDK updates, and RAG pipeline fragility if embedding/retrieval models fail silently. No test directory visible in top 60 files suggests limited automated test coverage.

Active feature expansion across multiple domains: Memory system enhancements, Deep Research multi-step workflows, Canvas-based data visualization and selective editing, Function Calling integration, image generation support, and local model library management. The breadth of documented features in Docs Images/ (spanning Conversations, Experts, Memory, Deep Research, Function Calling) suggests ongoing core feature development rather than maintenance-mode operation.

Clone the repository: git clone https://github.com/johnbean393/Sidekick.git && cd Sidekick. Open the Xcode project: open Sidekick.xcodeproj (inferred from Swift-heavy structure). Build and run via Xcode's run button targeting a macOS deployment target or command-line: xcodebuild -scheme Sidekick -configuration Debug.

Daily commands: After cloning: (1) xcodebuild -scheme Sidekick -configuration Debug (CLI build), or (2) open Sidekick.xcodeproj in Xcode and press Cmd+R. The app will launch as a macOS native application. Requires macOS 11+ (typical SwiftUI requirement) and available disk space for model downloads (GGUF models range 4GB–70GB).

• .github/ISSUE_TEMPLATE/bug_report.md — Defines bug reporting standards that contributors must follow for issue triage
• About/mission.md — Core mission statement that guides all architectural and feature decisions
• Features/conversations.md — Documents the primary chat interaction model that is central to the entire application
• Features/localModels.md — Describes integration with llama.cpp backend, the critical inference engine
• Features/experts.md — Explains the expert/specialized prompt system that differentiates Sidekick from generic LLM interfaces
• Features/webSearch.md — Documents web search integration capability required for expanded context beyond local files
• Markdown/Features/conversations.md — Alternative documentation format for conversations feature, likely generated or mirrored content

• Inference Engine (llama.cpp) (C++ llama.cpp, GGUF model format, Metal/CUDA for acceleration) — Core token generation and model loading; handles context window management and streaming responses
  • Failure mode: Model fails to load, out-of-memory errors, or token generation hangs → fallback to remote model or error message
• Expert System (Prompt templating, user-defined expert configurations stored in JSON/plist) — Manages specialized prompts and system instructions; routes user queries to domain-specific reasoning paths
  • Failure mode: Expert not found or prompt malformed → falls back to default system prompt
• File/Folder Context Engine (File system APIs, document parsing (PDF, DOCX, TXT), embedding generation) — Scans user directories, indexes documents, and embeds relevant context for LLM queries
  • Failure mode: File access denied, parse error, or embedding failure → skip file and log warning
• Chat Interface & Rendering (SwiftUI, WebKit for rendering, custom markdown parser) — Displays conversation history, formats LLM responses with Markdown/LaTeX/code blocks, handles user input
  • Failure mode: Render timeout or malformed response → graceful degradation to plain text view
• Tool Suite (Diagrammer, Slide Studio, Detector) (Template generation, format export (SVG, PPTX, JSON)) — Specialized outputs for diagrams, presentations, and analysis; converts LLM generations into structured formats
  • Failure mode: Export format unsupported or template validation fails → display raw LLM output with warning
• Web Search Integration — Optional external context enrichment via Tavily API; allows LLM to

Add a New Tool Feature

1. Create feature documentation describing the tool's purpose, UI, and user workflow (Features/Tools/newTool.md)
2. Document the tool's capabilities and limitations alongside existing tools (Features/Tools/)
3. Add screenshot examples to the documentation images folder following naming conventions (Docs Images/Features/Tools/NewTool/)
4. Mirror documentation to Markdown folder for multi-format support if needed (Markdown/Features/Tools/newTool.md)

Add a New Core Feature

1. Create main feature documentation file (Features/newFeature.md)
2. Add supporting documentation screenshot folder (Docs Images/Features/NewFeature/)
3. Document interaction with existing features (experts, conversations, models) (Features/newFeature.md)
4. Create mirrored markdown documentation for alternative distribution (Markdown/Features/newFeature.md)

Expand Model Support

1. Document new model type in appropriate feature file (Features/localModels.md or Features/remoteModels.md)
2. Add UI workflow screenshots showing model selection and configuration (Docs Images/Features/Local Models/ or Docs Images/Features/Remote Models/)
3. Update mission documentation if this enables new user capabilities (About/mission.md)

Add Integration Capability

1. Create feature documentation describing the integration endpoint and data flow (Features/newIntegration.md)
2. Document how the integration fits within conversation and expert systems (Features/newIntegration.md)
3. Add configuration and setup screenshots (Docs Images/Features/NewIntegration/)
4. Reference in related feature documentation (webSearch, localModels, etc.) (Features/*.md)

• llama.cpp Backend — Enables local LLM inference without external dependencies or internet requirements; core to 'local-first' philosophy
• macOS Native App — Leverages system integration for file access, inline writing assistant, and seamless OS-level feature access
• Expert/Specialist Prompts — Allows domain-specific reasoning without model retraining; users can customize LLM behavior for their use cases
• OpenAI-Compatible APIs — Provides flexibility for users wanting cloud models while maintaining offline-first architecture
• Markdown Documentation — Reflects product-first design philosophy; documentation drives feature discovery and user understanding

• Local inference engine (llama.cpp) vs cloud-only API

  • Why: Prioritizes privacy and offline capability over latency and cutting-edge model availability
  • Consequence: Users must manage their own model files and hardware; slower responses than cloud APIs but zero data transmission

• Support both local and remote models simultaneously

  • Why: Accommodates users with different resource constraints and privacy requirements
  • Consequence: Increased UI complexity for model selection; code must handle two distinct inference paths

• Specialized tool features (Diagrammer, Slide Studio, Detector) vs single unified chat

  • Why: Enables expert-level outputs in specific domains beyond generic text generation
  • Consequence: Larger codebase and more feature maintenance; clearer value proposition for different workflows

• File/folder indexing for context vs real-time parsing

  • Why: Reduces latency for large knowledge bases and repeated queries
  • Consequence: Stale context risk if files are modified between indexing cycles; requires cache invalidation logic

• Cross-platform support (macOS only)
• Real-time collaboration on conversations
• Built-in authentication or multi-user accounts
• Direct file editing capabilities within the app
• Support for proprietary LLM formats (only GGUF models)
• Browser or web-based access (native app only)

llama.cpp version lock: the embedded C inference engine has strict ABI compatibility requirements; updating it may require recompiling all bindings. Model discovery/download: GGUF model sources (HuggingFace, Ollama) may enforce rate limiting or require authentication. RAG embedding model overhead: embedding large document sets (1000+ files) locally can consume significant RAM and CPU; no visible caching strategy in file list. SwiftUI state management: complex interactions between Experts, Memory, and canvas features suggest potential state synchronization bugs if not carefully architected. sandboxing constraints: macOS app sandbox may restrict file system access to user-selected folders only, complicating bulk document ingestion.

• Retrieval-Augmented Generation (RAG) — Core mechanism enabling Sidekick to ground LLM responses in user documents; understanding chunking, embedding, and retrieval ranking is essential for modifying expert resource behavior
• GGUF (GPT-Generated Unified Format) — File format for quantized LLMs that llama.cpp executes; understanding quantization levels (Q4, Q8) and token context limits is crucial for model selection and performance tuning
• Function Calling (Tool Use) — Sidekick implements LLM-driven function calls for structured output (email drafting, financial metrics); understanding structured prompts and response parsing prevents hallucination in tool invocation
• Semantic Chunking — Documents are split into meaningful units for RAG retrieval; naive chunking degrades relevance; understanding sentence-boundary detection and semantic clustering improves expert resource quality
• macOS Sandboxing & Entitlements — App.entitlements file constrains file system and network access; contributes must navigate sandbox restrictions when implementing file picker and URL fetch features
• SwiftUI State Management (Observable Objects) — Sidekick's multi-feature architecture (Experts, Memory, Canvas, Conversations) requires coordinating state across SwiftUI view hierarchies; understanding @StateObject, @ObservedObject, and @EnvironmentObject prevents sync bugs
• Token Limits and Context Windows — Local GGUF models have fixed context window sizes (2K–128K tokens); RAG must fit retrieved documents + user query within limits; misunderstanding causes truncation and information loss

• ggerganov/llama.cpp — Core inference engine dependency; Sidekick wraps this C library for local GGUF model execution
• lm-sys/FastChat — Alternative Python-based LLM inference and serving; relevant for understanding OpenAI API fallback compatibility targets
• openai/gpt-4-vision-system-card — Reference for function calling and structured output patterns that Sidekick implements for tool use
• imartinez/privateGPT — Similar local-first RAG application (Python-based); demonstrates document ingestion and retrieval patterns Sidekick adapts for macOS
• Apple/swift-ai — Apple's official Swift AI framework; potential future integration path for native ML/inference without C bindings

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.

Create comprehensive documentation for Expert system and Function Calling features

The file structure shows extensive feature documentation images for Experts (9 images) and Function Calling (3 images), but there's no dedicated markdown documentation file explaining how to create, configure, and use Expert profiles or how Function Calling works. This is a high-value feature based on the number of UI screenshots, and new users need clear written guides beyond the README.

• [ ] Create Docs/EXPERTS.md documenting Expert creation, prompt engineering, resource use settings, and examples from the screenshots in Docs Images/Features/Experts/
• [ ] Create Docs/FUNCTION_CALLING.md explaining what Function Calling is, how to enable it (reference functionsToggle.png), use cases, and limitations
• [ ] Create Docs/TOOLS.md as an overview linking to individual tool documentation (Detector, Diagrammer, Inline Writing Assistant, Slide Studio)
• [ ] Link these new docs from main README.md under a 'Documentation' section

Add GitHub Actions workflow for macOS app release automation

The repo has .github/ISSUE_TEMPLATE/ configured but no visible CI/CD workflows (.github/workflows/ directory). Given this is a native macOS app with releases and version increments (increment.md issue template exists), automated building, signing, and notarization workflows would significantly reduce manual release work and improve reliability.

• [ ] Create .github/workflows/build.yml to compile the macOS app on push to main branch
• [ ] Create .github/workflows/release.yml triggered on version tags (e.g., v1.0.0) to build, code-sign, notarize, and create GitHub Releases
• [ ] Document macOS code signing and notarization setup requirements in CONTRIBUTING.md
• [ ] Add a RELEASE.md documenting the release process for maintainers

Create feature documentation for Deep Research and Memory systems

The file structure shows Deep Research (4 images showing progression, activation, follow-up, report) and Memory (4 images) as sophisticated features, but no detailed written guides exist. These are complex user-facing features that deserve dedicated documentation with screenshots and configuration guidance.

• [ ] Create Docs/DEEP_RESEARCH.md explaining the Deep Research workflow, how it differs from normal chat, how to activate it, and interpret the progress/report outputs from the existing screenshots
• [ ] Create Docs/MEMORY.md documenting how memory works, memory settings configuration (reference memorySettings.png), privacy implications, and best practices
• [ ] Include specific screenshots from Docs Images/Features/Deep Research/ and Docs Images/Features/Memory/ in the markdown files
• [ ] Add a section in main README linking to these advanced feature guides

• Add unit tests for RAG chunking logic: create Tests/ directory with tests for document splitting strategies (sentence-level, token-level, semantic), currently no test coverage visible for core retrieval pipeline.
• Expand documentation in About/mission.md and add inline code comments to Swift files explaining Expert resource resolution and scope isolation; contributors report confusion about how resources are loaded and prioritized during RAG.
• Implement missing error handling UI for model download failures: add retry logic and user-facing toast notifications when GGUF model downloads timeout or fail, currently silent failures suspected in model library feature.

The Sidekick application presents several security concerns despite being marketed as a 'local first' privacy-focused tool. The primary risks include: (1) lack of visible input validation for prompt injection attacks, (2) uncontrolled file system access to user data, (3) missing dependency visibility and auditing, (4) unclear credential management for API keys, (5) unvalidated website content processing, and (6) absence of visible encryption for stored data. While running locally is a security advantage, the implementation details suggest potential gaps in protecting sensitive user data and indexed files. The application should prioritize implementing input sanitization, secure credential storage, encryption at rest, and strict access controls before being considered suitable for handling sensitive personal information.

• High · Local LLM Processing Without Input Validation — Core chat processing logic (not visible in provided files). The application processes user input directly through an LLM without visible input sanitization mechanisms. This could potentially allow prompt injection attacks where malicious users craft inputs to manipulate the LLM's behavior or extract sensitive information from indexed files. Fix: Implement strict input validation and sanitization. Add prompt injection detection mechanisms. Consider implementing sandboxing for LLM execution. Apply rate limiting to prevent abuse.
• High · File System Access Without Visible Access Controls — File indexing and processing system. The application indexes and processes files, folders, and website content from the user's Mac. Without visible permission controls in the file structure, there's a risk of unauthorized access to sensitive files or unintended data exposure through LLM responses. Fix: Implement granular file access controls. Create an allowlist/blocklist system for sensitive file types and directories. Add user confirmation prompts before indexing system directories. Implement file type restrictions and scan for sensitive file patterns.
• High · Dependency Management Visibility — Package.swift or equivalent dependency manifest. The provided dependency file content is empty. Without visibility into actual dependencies used by this Xcode/Swift project, there's no way to identify vulnerable libraries, transitive dependencies, or supply chain risks. Fix: Maintain explicit dependency declarations. Regularly audit dependencies using tools like Swift Package Manager security warnings. Use dependency pinning for critical libraries. Implement automated security scanning in CI/CD.
• Medium · API Key Storage for Remote Models — Remote Models feature settings storage. The application supports OpenAI-compatible APIs and remote models. The file structure shows remote model settings but no visible secure credential storage mechanism (Keychain integration, encryption, etc.) is documented. Fix: Store API keys and credentials in macOS Keychain, never in plaintext. Use environment variables for development. Implement credential encryption at rest. Add secure deletion on logout. Implement key rotation mechanisms.
• Medium · Website Content Processing Without Security Headers Validation — Website content fetching and processing. The application processes website content directly. There's no visible validation of website security headers, SSL/TLS certificate verification, or protection against malicious content from compromised websites. Fix: Validate SSL/TLS certificates before fetching content. Implement HSTS checking. Sanitize HTML/JavaScript from fetched content. Use Content Security Policy principles for processing. Implement user warnings for suspicious URLs.
• Medium · Data Persistence Without Visible Encryption — Local data storage system. The application stores conversations and indexed content on disk. Without visible encryption mechanisms in the file structure, sensitive conversation data and indexed files could be vulnerable to disk access attacks. Fix: Implement encrypted storage using Data Protection APIs. Use file-level encryption for sensitive data. Implement secure deletion of conversations when requested. Use encrypted databases for storing conversation history.
• Low · Missing Security Headers Documentation — Overall security architecture. No visible security headers, CORS policies, or IPC security configurations documented. While this is a native macOS app, inter-process communication could present risks. Fix: Document and implement proper IPC security. Use signed and sandboxed code. Implement proper entitlements for macOS. Document security assumptions.

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.