Skip to content

Getting Started

Jump to bottom
CassiusAmicus edited this page Jul 7, 2026 · 1 revision

Getting Started

Requirements

  • Go 1.21+ — the only build dependency
  • A modern browser (Chrome, Firefox, Safari, Vivaldi, etc.)
  • Git (optional, used for automatic snapshots)

Building and running

git clone https://github.com/cassiusamicus/epicorg.git
cd epicorg
make build          # produces ./epicorg binary
./epicorg ~/org     # serve the ~/org directory

The server starts on port 8080 by default. Open http://localhost:8080 in your browser.

Options

./epicorg                        # serve current directory
./epicorg ~/notes                # serve a specific directory
./epicorg -addr :9090 ~/notes    # custom port

Opening a file

When you first open the app you will see a file list in the sidebar. Click any .org file to open it. The outline loads immediately — all editing is local with no network round-trip.

If your directory contains no .org files, create one:

  1. Click + New file at the bottom of the sidebar file list, or
  2. Create a .org file in your directory with any text editor and refresh.

Auto-save and Git snapshots

Epicorg saves your work automatically every 3 seconds when anything has changed. You will see a sync indicator (✓ Saved / ⟳ Syncing) in the header.

If the directory is a git repository, Epicorg also commits snapshots:

  • On file open — baseline snapshot for three-way merge conflict detection
  • After 20 minutes idle — periodic snapshot
  • On shutdown (SIGTERM/SIGINT) — final snapshot

These commits are made only to the single .org file you are editing, never to unrelated files.

Conflict detection

If the same .org file is edited externally (e.g. by Emacs or another process) while Epicorg has it open, the next save will detect the conflict via SHA-256 hash comparison and attempt a three-way merge using git merge-file. Conflict markers are written to the file and surfaced in the UI.

Clone this wiki locally