Documentation
Reference
FAQ

FAQ

Find answers to common questions about HeroJournal. If your question isn’t answered here, please open an issue on GitHub.

General Questions

Where is my data stored?

All data is stored locally on your computer:

Platform Location
macOS ~/.config/HeroJournal/
Windows %APPDATA%\HeroJournal\
Linux ~/.config/HeroJournal/

Your data never leaves your device unless you explicitly enable Git sync or AI features.

Is my data sent to the cloud?

No. HeroJournal is 100% offline by default. Data is only transmitted if you:

  1. Enable AI integration - Prompts are sent to your chosen AI provider
  2. Enable Git sync - Data is synced to your Git repository
  3. Export - Files are saved where you specify

Can I use HeroJournal without an internet connection?

Yes! HeroJournal works completely offline. Only AI and Git features require internet access, and both are optional.

Is HeroJournal free?

Yes, HeroJournal is free and open source.

Installation & Setup

Why can’t I open the app on macOS?

macOS shows a security warning because HeroJournal isn’t notarized by Apple. This is normal for open-source apps.

Solution:

  1. Right-click the app
  2. Select Open
  3. Click Open in the dialog

Or go to System Settings > Privacy & Security and click Open Anyway.

Why does Windows show a SmartScreen warning?

Windows SmartScreen warns about apps from unknown publishers.

Solution:

  1. Click More info
  2. Click Run anyway

How do I update HeroJournal?

Currently, updates require manual download:

  1. Download the new version from GitHub
  2. Install over the existing version
  3. Your data is preserved

Achievements

How many achievements can I store?

There’s no hard limit. HeroJournal has been tested with hundreds of achievements without performance issues.

Can I import achievements from another app?

Not directly. However, you can:

  1. Export from your other app to CSV
  2. Manually create achievements in HeroJournal
  3. Or use the backup import feature if you have a compatible JSON file

Why are my achievements not showing?

Check your date filter! If you have a specific period selected, achievements outside that period won’t appear. Click the date filter and select All Time.

Can I recover deleted achievements?

If you have:

  • Git sync enabled - Restore from version history
  • Recent backup - Import the backup
  • Neither - Unfortunately, deletion is permanent

AI Features

Why isn’t AI working?

Check these common issues:

  1. AI not enabled - Go to Settings > AI and enable it
  2. No API key - Enter and save your API key
  3. Invalid API key - Test connection to verify
  4. No credits - Check your AI provider account balance
  5. Ollama not running - Start Ollama with ollama serve

Which AI provider should I use?

Provider Best For
OpenAI General use, reliable quality
Anthropic Writing quality, longer content
Ollama Privacy, no API costs
Google Alternative to OpenAI

Is my achievement data sent to the AI?

When using AI features, only the current achievement context is sent:

  • Title
  • Notes
  • Existing altitude text (if improving)
  • Your prompt/request

Your full achievement history is not sent.

Git Sync

Why does Git authentication fail?

Common causes:

  1. Token expired - Generate a new personal access token
  2. Wrong token scope - Ensure repo scope is enabled
  3. Typo in URL - Verify repository URL
  4. Private repo access - Ensure you have access

Can I use SSH instead of HTTPS?

Yes! Use an SSH URL like git@github.com:username/repo.git and ensure your SSH key is configured.

What happens if I edit on two devices?

If you edit on both devices before syncing, HeroJournal detects the conflict and lets you choose which version to keep or merge manually.

Exports

What format should I use for performance reviews?

Excel (.xlsx) is usually best for sharing with managers - it looks professional and is easy to read.

Can I customize export templates?

Not currently. All exports use the built-in templates. Custom templates may be added in a future version.

Why is my export missing achievements?

Exports respect your current date filter. If you only see some achievements in the app, that’s what will be exported. Set filter to All Time to export everything.

Backups

How do I move to a new computer?

  1. On old computer: Create a backup (Settings > Backup)
  2. Transfer the backup file to new computer
  3. Install HeroJournal on new computer
  4. Import the backup (Settings > Backup > Import)

I forgot my backup password

Unfortunately, encrypted backups cannot be recovered without the password. This is by design for security.

Prevention: Store backup passwords in a password manager.

How often should I back up?

Recommended schedule:

  • Weekly for regular backups
  • Before updates to HeroJournal or your OS
  • After bulk edits to many achievements

Troubleshooting

HeroJournal is slow

Try these steps:

  1. Restart the app
  2. Check if you have hundreds of achievements (try filtering)
  3. Disable Git auto-sync if network is slow
  4. Check available disk space

The app crashes on startup

  1. Check if another instance is running
  2. Try deleting the config folder and restarting
  3. Reinstall HeroJournal

Export fails

  1. Check you have write permission to save location
  2. Try a different location
  3. Ensure enough disk space
  4. Try a different format

AI responses are poor quality

  1. Provide more context (title, notes)
  2. Try a different model
  3. Be more specific in your requests
  4. Use the chat for back-and-forth refinement

Getting Help

How do I report a bug?

  1. Go to GitHub Issues
  2. Click New Issue
  3. Include:
    • What you expected
    • What actually happened
    • Steps to reproduce
    • Your OS and HeroJournal version

How do I request a feature?

  1. Go to GitHub Issues
  2. Click New Issue
  3. Describe the feature and why it would be useful

Where can I get support?

  • Check this FAQ first
  • Search GitHub Issues for similar problems
  • Open a new issue if needed
Last updated on
Keyboard Shortcuts