Skip to content
CodeLayersCodeLayers
Home
Navigation

Troubleshooting & FAQ

Common issues and how to resolve them.

Connection Issues

Device can't find CLI / "No Projects Found"

Symptoms:

  • App shows "No projects" or "Searching..."
  • CLI says "Watching..." but the app doesn't see it

Solutions:

  1. Check CLI is running and connected

    codelayers status

    Should show "Backend WebSocket connected"

  2. Check internet connection

    • Both devices need internet access to connect to the backend
    • Try opening a website on both devices to verify

  3. Verify same mnemonic

    • Both CLI and your device must use the same 12-word phrase (synced automatically via iCloud Keychain)
    • Check sync ID matches: codelayers status shows your sync ID

  4. Restart the watch process

    # Stop and restart CLI
codelayers stop
codelayers watch .

  5. Re-authenticate

    codelayers logout
codelayers login
codelayers watch .

"Connection Lost" / Frequent Disconnects

Solutions:

  1. Check internet stability

    • The backend WebSocket needs a stable internet connection
    • Try a speed test or ping test to verify connectivity

  2. Check for sleep/lock

    • Mac sleeping stops CLI
    • Prevent sleep: caffeinate -i codelayers watch .

  3. Update CLI

    codelayers --version  # Check version
brew upgrade codelayers

  4. Check backend status

    • Rare, but backend may have maintenance windows
    • Check https://status.codelayers.ai if issues persist

Backend connection issues

Solutions:

  1. Check internet connection on Mac

  2. Verify authentication

    codelayers status

    Should show "Logged in as..." and "WebSocket connected"

  3. Re-login

    codelayers logout
codelayers login

  4. Check firewall

    • Ensure outbound HTTPS (443) and WSS connections are allowed

Authentication Issues

"Mnemonic doesn't match" / "Unable to decrypt"

Symptoms:

  • App shows "Decryption failed"
  • Data appears as garbled text

Cause: The mnemonic on your device doesn't match the one used by CLI.

Solutions:

  1. Verify mnemonic is identical

    • Every word must match exactly
    • Order matters
    • Check for similar-looking words (e.g., "there/three")

  2. Re-import on your device

    • Settings → Privacy → Re-import Recovery Phrase
    • Enter all 12 words carefully

  3. Check CLI mnemonic

    codelayers status

    Shows sync ID - compare with the sync ID shown in the app

"Invalid mnemonic" when logging in

Solutions:

  1. Check word count - Must be exactly 12 words
  2. Check for typos - All words must be from BIP-39 wordlist
  3. No extra spaces - Single space between words
  4. Case doesn't matter - "Apple" = "apple"

Can't generate new mnemonic

Solutions:

  1. Force re-login

    codelayers login --force

  2. Clear existing credentials

    codelayers logout
rm -rf ~/.codelayers/credentials.json
codelayers login

Sync Issues

Initial sync takes forever

Normal times:

  • 100 files: ~10 seconds
  • 1000 files: ~1 minute
  • 5000 files: ~5 minutes

If much slower:

  1. Large files - Check for binary files or huge JSON
  2. Many dependencies - Complex codebases take longer
  3. Network speed - Check upload bandwidth
  4. CPU load - Parsing is CPU-intensive

Speed up tips:

  • Add large/binary files to .gitignore
  • Create .codelayersignore to skip directories: 
    node_modules/
target/
build/
.git/

"Sync failed" / Upload errors

Solutions:

  1. Check network - Stable internet connection?
  2. Check disk space - Cache needs space
  3. Retry 
    codelayers sync --clean
  4. Check logs 
    codelayers watch -d  # Debug mode

Changes not appearing on your device

Solutions:

  1. Check file is saved - Unsaved changes won't sync
  2. Check file type - Only supported languages are parsed
  3. Wait for debounce - 300ms delay before processing
  4. Force refresh in the app: Pull down gesture or tap refresh

Graph looks wrong / Missing connections

Solutions:

  1. Clean re-sync

    codelayers sync --clean

  2. Check language support - Is your language in the supported list?

  3. Check import style - Some dynamic imports may not be detected

App Issues

App crashes on launch

Solutions:

  1. Force quit and relaunch
  2. Restart your device
  3. Reinstall app
  4. Clear app data: Settings → Apps → CodeLayers → Clear Data

Poor performance / Low frame rate

Solutions:

  1. Close other apps - Free up resources on your device
  2. Reduce visible nodes - Focus on a subdirectory rather than the entire codebase
  3. For very large codebases (5000+ files) - Consider syncing individual packages

Visualization is empty / All nodes at origin

Solutions:

  1. Wait for load - Large graphs take time to layout
  2. Check project has code - Empty or tiny repos may not visualize well
  3. Re-sync from CLI

Labels not showing / Text unreadable

Solutions:

  1. Zoom in - Labels appear when you're closer to nodes
  2. Adjust text size - Use visionOS Settings → Accessibility → Display → Text Size

AI Chat Issues

"AI chat unavailable"

Cause: CLI not running with --agent flag.

Solution:

codelayers watch --agent claude  # or gemini/codex

AI not responding

Solutions:

  1. Check agent is installed

    claude --version  # For Claude
gemini --version  # For Gemini
codex --version   # For Codex

  2. Check agent authentication - Each AI needs its own API key/login

  3. Restart watch with agent

    codelayers stop
codelayers watch --agent claude

AI can't see my code

Note: AI agents run locally on your Mac and can see your plaintext code. This is required for them to answer questions.

If AI seems unaware of your code:

  1. Make sure the agent subprocess started correctly
  2. Check CLI logs for errors
  3. Try a simpler question first

CLI Issues

"Command not found: codelayers"

Solutions:

  1. Check installation

    which codelayers
brew list codelayers

  2. Reinstall

    brew install codelayers-ai/tap/codelayers

"Permission denied"

Solutions:

  1. Check Homebrew permissions

    brew doctor

  2. macOS Gatekeeper

    • System Preferences → Security → "Allow anyway"

High CPU usage

Normal: Initial parsing uses significant CPU briefly.

If persistent:

  1. Check for loops - Is the same file changing repeatedly?
  2. Exclude directories - Add to .codelayersignore
  3. Check log output - codelayers watch -d

High memory usage

Solutions:

  1. Large codebases use more memory - expected for 10k+ files
  2. Clear cache 
    rm ~/.codelayers/ast_cache.db

FAQ

General

Q: What happens if I lose my mnemonic? A: Your encrypted data cannot be recovered. You would need to start fresh with a new mnemonic and re-sync your repositories. Always backup your 12 words.

Q: Can multiple people view the same codebase? A: Yes, if they all have the same mnemonic. Share your 12-word phrase securely with team members who need access.

Q: Does CodeLayers work offline? A: Partially. Once synced, the app caches the graph locally. You can view cached data offline, but won't receive real-time updates until reconnected to the backend.

Q: Which files are ignored? A: By default: .git/, node_modules/, target/, build/, .venv/, and files in .gitignore. Create .codelayersignore for custom exclusions.

Privacy

Q: Do you have access to my code? A: No. All code is encrypted with your mnemonic before leaving your machine. We only store encrypted blobs.

Q: Is the AI chat private? A: AI agents (Claude, Gemini, Codex) run locally on your Mac and see your plaintext code. Their providers' privacy policies apply. The messages you exchange are encrypted when stored on our backend.

Q: Can I self-host the backend? A: Not currently. The backend code is not open-source. However, all data is end-to-end encrypted with your mnemonic—the backend only sees encrypted blobs.

Compatibility

Q: Will you support more languages? A: Yes, we're adding more tree-sitter grammars. Kotlin, Scala, and Elixir are planned.

Q: What devices does CodeLayers support? A: CodeLayers is available on iPhone, iPad, and Apple Vision Pro. The CLI runs on macOS with Apple Silicon.

Q: Does it work with monorepos? A: Yes, but very large monorepos (50k+ files) may be slow. Consider syncing individual packages.

Pricing

Q: Is CodeLayers free? A: Check codelayers.ai/pricing for current pricing.

Q: Is there a free trial? A: Check codelayers.ai for trial information.

Getting Help

When reporting issues, please include:

  • CLI version (codelayers --version)
  • Operating system and version
  • Device model and OS version
  • Steps to reproduce
  • Error messages (with debug output: codelayers watch -d)