vimango

Vimango

So this is basically an application to store notes and other documents.

The notes are stored in a local sqlite database that can be synced to a remote server so you can access and update notes from multiple devices.

There are a few semi-notable features:

• Markdown rendering of notes in the terminal based on charm's glamour package
• Images in the terminal are supported using the kitty unicode placeholder protocol
• Google Drive image support (optional) - Pull images directly from Google Drive into your notes
  • The markdown syntax is ![alt text](gdrive:<file id>)
  • Images are cached both in-memory (via kitty) and on disk (as Base64 PNG files)
  • See Google Drive Setup below for configuration
• Terminal Markdown rendering supports kitty's text sizing protocol
• For HTML rendering, there is a built-in webviewer that uses the go bindings to the webview library
• Syncing of notes to a remote PostgreSQL database (optional)
• Note editing supports full vim keybindings via libvim, which was originally develeped to support the Onivim 2 editor
• There is full-text search via sqlite's fts5 extension
• Spell checking through the use of the hunspell library
• You can launch deep research via Claude and the results will be stored as a note

This wasn't developed thinking anyone else would use it so there isn't an installable package. You'll need to clone the repository and build it yourself. There are a few dependencies that you'll need to have installed first. These are:

• Go 1.20 or later
• SQLite3 development files
• Hunspell development files
• libvim.a (must be built from source — see Building libvim.a below)

Building libvim.a

The libvim.a static library provides vim modal editing via CGO. It must be compiled from source because the binary differs between macOS and Linux. This is only needed for CGO builds — pure Go builds (CGO_ENABLED=0) with the --go-vim flag do not require it.

Source: Clone onivim/libvim and build in its src/ directory.

macOS (Apple Silicon / Homebrew)

Install prerequisites:

brew install ncurses gettext

Configure and build:

cd /path/to/libvim/src
./configure --disable-selinux --with-tlib=ncurses \
  CFLAGS="-I/opt/homebrew/opt/ncurses/include -I/opt/homebrew/include \
    -Wno-error=implicit-function-declaration -Wno-error=implicit-int \
    -Wno-error=int-conversion -Wno-error=incompatible-function-pointer-types \
    -Wno-error=unused-but-set-variable -Wno-error=deprecated-non-prototype" \
  LDFLAGS="-L/opt/homebrew/opt/ncurses/lib -L/opt/homebrew/lib"
make libvim.a

The -Wno-error flags are needed because Xcode's Clang is stricter than GCC and treats certain legacy C patterns as errors.

Copy to the vimango project root:

cp libvim.a /path/to/vimango/

Linux

Install prerequisites:

Debian/Ubuntu:

sudo apt-get install libtinfo-dev libacl1-dev

Arch Linux:

sudo pacman -S ncurses acl

Configure and build:

cd /path/to/libvim/src
./configure --disable-selinux CFLAGS=-fPIC
make libvim.a

The -fPIC flag is required on Linux for position-independent code.

Copy to the vimango project root:

cp libvim.a /path/to/vimango/

Build Notes

• The libvim.a file must be placed in the vimango project root directory (next to go.mod).
• You do not need to copy or regenerate auto/config.h or auto/pathdef.c from your libvim build; the versions checked into this repo work on both platforms.
• If you only want to run vimango without libvim (pure Go mode), skip this step and build with CGO_ENABLED=0 go build --tags=fts5, then run with --go-vim.

Quick Start

First-time setup (recommended):

# 1. Clone the repository
git clone https://github.com/slzatz/vimango.git
cd vimango

# 2. Build libvim.a and copy to this directory (see "Building libvim.a" above)
#    Or skip this step and use --go-vim for pure Go vim

# 3. Build the application
CGO_ENABLED=1 go build --tags="fts5,cgo"

# 4. Run first-time setup (creates config.json and databases)
./vimango --init

# 5. Run the application
./vimango

Manual setup (alternative):

1. Copy the example config: cp config.json.example config.json
2. Edit config.json with your settings (see below)
3. Create SQLite databases manually or let --init do it
4. Build: CGO_ENABLED=1 go build --tags="fts5,cgo"
5. Run: ./vimango

Configuration

The config.json file structure (copy from config.json.example):

{
  "options": {
    "type": "folder",
    "title": "vimango"
  },
  "postgres": {
    "host": "",
    "port": "",
    "user": "",
    "password": "",
    "db": "vimango"
  },
  "sqlite3": {
    "db": "vimango.db",
    "fts_db": "fts5_vimango.db"
  },
  "chroma": {
    "style": "gruvbox_mod.xml"
  },
  "claude": {
    "api_key": ""
  },
  "glamour": {
    "style": "darkslz.json"
  }
}

Notes on configuration:

• options: Notes can be tagged with both "contexts" and "folders" - two parallel tagging systems
• postgres: Remote sync is optional - leave empty if not using remote sync
• sqlite3: Local database settings - these files will be created automatically
• chroma: Syntax highlighting style for code blocks in markdown
• glamour: Markdown rendering style - darkslz.json and default.json are included
• claude: API key for deep research feature (optional)

The full application makes heavy use of CGO to access various C libraries but it can be compiled without using CGO.

So if this hasn't been offputting enough, after you can clone the repository you can build as follows:

• Linux with CGO: CGO_ENABLED=1 go build --tags="fts5,cgo" (includes libvim, hunspell, sqlite3)
• Linux Pure Go: CGO_ENABLED=0 go build --tags=fts5 (no CGO dependencies)
• Windows Cross-Compilation: GOOS=windows GOARCH=amd64 go build --tags=fts5 (pure Go only)

The main runtime options are:

• --help, -h: Display help message with all available options and exit
• --go-vim: Use pure Go vim implementation (default: CGO-based libvim)
• --go-sqlite: Use pure Go SQLite driver (modernc.org/sqlite) - default
• --cgo-sqlite: Use CGO SQLite driver (mattn/go-sqlite3)

If you actually manage to get the application running there is a help system:

• :help - Show all available ex commands organized by category
• :help normal - Show all normal mode commands organized by category
• :help <command> - Show detailed help for specific ex command with usage and examples
• :help <key> - Show detailed help for specific normal mode command (e.g., :help Ctrl-H)
• :help <category> - Show all commands in a specific category (e.g., :help Navigation)

Google Drive Setup (Optional)

Google Drive integration is optional. The application works fine without it - you just won't be able to display images stored in Google Drive. If you try to view a gdrive: image without credentials configured, you'll see a message explaining how to set it up.

If you want to use Google Drive images in your notes, follow these steps:

1. Create a Google Cloud Project

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the Google Drive API for your project:
   • Go to "APIs & Services" → "Library"
   • Search for "Google Drive API" and enable it

2. Create OAuth 2.0 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth client ID"
3. If prompted, configure the OAuth consent screen first:
   • Choose "External" user type (unless you have a Workspace account)
   • Fill in the required fields (app name, user support email, developer email)
   • Add yourself as a test user
4. Create an OAuth client ID:
   • Application type: Desktop app
   • Name: "Vimango" (or whatever you prefer)
5. Download the credentials JSON file

3. Configure Vimango

1. Rename the downloaded file to go_credentials.json
2. Place it in the vimango directory (same directory as the executable)
3. Run vimango - on first run, it will:
   • Print an authorization URL
   • Open the URL in your browser (or copy/paste it)
   • Sign in with your Google account and authorize the app
   • Paste the authorization code back into the terminal
4. A token.json file will be created to store your access token

4. Using Google Drive Images

To include a Google Drive image in a note, use the syntax:

![description](gdrive:FILE_ID)

Where FILE_ID is the Google Drive file ID. You can find this in the file's URL: https://drive.google.com/file/d/FILE_ID/view

Security Notes

• go_credentials.json contains your OAuth client credentials - don't share it
• token.json contains your access token - don't share it
• Both files should be added to .gitignore (they already are in this repo)

Here is a screenshot: