Synapxis

A terminal-based tool for personal knowledge management using the Zettelkasten method. Create atomic notes and link them to form a networked graph of ideas.

Python (Textual)Rust (Backend)TUI

Features and Usage

Hybrid Rust/Python Engine

The application uses Python (Textual) for the UI and a compiled Rust backend for performance.

High Definition Rendering: Uses Unicode Braille patterns (2x4 dot matrix) for sub-pixel precision.
Performance: Native Rust graph physics allow smooth interactions with large datasets.

Graph Visualization

Force-Directed Physics: Connected notes pull together; unconnected notes push apart.
Community Detection: Clusters of interconnected notes are automatically assigned distinct colors.

Spotlight Mode

Hovering over a node dims the background to focus on neighbors.

Graph Search

Press F to search and center on a note.

Drag & Drop

Click and drag nodes to customize the layout manually.

Layout Persistence

Node positions are saved to disk automatically.

Wikilinks & Autocomplete

Link: Type [[ while editing to open the Autocomplete Menu.
Select: Use Up/Down arrows or Mouse to select a note.

Creates a bidirectional connection visualized as a line in the Graph View.

Export Studio

Share your thoughts outside the terminal.

Press Alt + E inside a note

MarkdownHTMLPDF

Tagging & Custom Colors

Organize

Type tags like #ideas or #project directly in your text.

Customize

Press S on the main menu to open Settings and assign specific colors to tags.

Recommended Terminals

Synapxis is a TUI. For the best Braille rendering and color accuracy, use a GPU-accelerated terminal:

Ghostty

Modern, cross-platform, native TUI support.

Alacritty

Highly performance-focused, minimal latency.

WezTerm

Strong image protocols and GPU rendering.

iTerm2 (macOS)

Fix: Settings > Profiles > Keys > Set "Left Option Key" to Esc+.

Prerequisites

Run the following to check if you have the necessary tools:

# Check Python (Must be 3.8+)
python3 --version

# Check Git
git --version

Missing Tools?

Install via package manager:

# Debian / Ubuntusudo apt update && sudo apt install python3 git

# macOS (Homebrew)brew install python git

# Fedorasudo dnf install python3 git

# Arch Linuxsudo pacman -S python git

Installation

Option A: Automatic Recommended

Creates a sandboxed environment (.venv), compiles the Rust engine, and sets up aliases.

curl -fsSL https://snx.codefxr.com/install | bash

Install Location: ~/.synapxis

Data Location: ~/.synapxis_v2/notes.db

Aliases: synapxis, snx

Option B: Manual

git clone https://github.com/CodeFXR/Synapxis.git
cd Synapxis

# 1. Create Environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install Dependencies
pip install textual networkx scipy numpy textual-image maturin aiosqlite

# 3. Compile Rust Backend (Requires cargo)
# If skipped, the app will run in standard definition mode.
cd rust_core
maturin develop --release
cd ..

# 4. Run
python main.py

Keyboard Shortcuts

Context	Shortcut	Action
Note View	Alt + N	New Page
	Alt + F	Search Notes
	Alt + E	Export Note
	Alt + B	Show Backlinks
	Alt + G	Switch to Graph
	[[	Link Autocomplete
Graph View	F	Find Node
	Mouse Drag	Pan / Move Node
	Scroll	Zoom In/Out

Troubleshooting

Issue: "Rust backend missing" / Blocky Graphics

Cause: The synapxis_rs binary was not compiled found.

Solution: Install Rust and re-run the installer.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Issue: "Command not found: synapxis"

Cause: Shell configuration not reloaded.

Solution: Reload your config:

source ~/.bashrc # Or ~/.zshrc for macOS

Issue: Graph View is empty

Cause: The graph engine hides isolated nodes to reduce noise.

Solution: Create at least two notes and link them using [[WikiLink]] syntax.

Uninstalling / Resetting

# Reset Data (Deletes Notes)

rm -rf ~/.synapxis_v2

# Uninstall App

rm -rf ~/.synapxis