The Problem
Researchers and writers often need a fast, terminal‑native way to browse and edit Markdown while keeping links, outlines, and graph views in sync. Conventional GUI editors add latency and break the keyboard‑only workflow, especially on remote or low‑resource environments.
What This Does
ekphos provides a single‑binary, ncurses‑style interface that renders Markdown, shows a navigation sidebar, and maintains a bidirectional link graph. The core logic lives in src/main.rs (CLI entry point) which boots the app module (src/app/mod.rs). UI components such as the editor, sidebar, and graph view are under src/ui/, while Vim‑style editing is implemented in src/vim/ (e.g., src/vim/mode.rs, src/vim/command.rs). Theme definitions are simple TOML files in themes/ (e.g., dracula.toml). The project is packaged as a Rust crate (Cargo.toml) and can be containerised via the Dockerfile.
How To Use It
Setup – Build or install the binary with Cargo:
Install from crates.io
cargo install ekphos
Or build locally
git clone https://github.com/hanebox/ekphos.git cd ekphos make run # defined in Makefile; runs cargo run
Configuration – Runtime configuration is parsed by src/config.rs. No default config file is shipped; the binary creates a user‑specific config on first run (see ekphos --reset in the README). Adjustments must be made via the CLI flags documented in the external docs (docs.ekphos.xyz).
Running – Launch the editor with the binary, optionally passing a Markdown file:
ekphos notes.md
The program reads the file, builds an internal graph (src/graph/mod.rs), and presents the UI. Inline images require a compatible terminal (iTerm2, Kitty, WezTerm, Ghostty, or any Sixel‑capable emulator) as noted in the README.
Docker – A container image can be built with the standard Dockerfile:
docker build -t ekphos . docker run -it --rm -v "$PWD:/work" ekphos notes.md
(Explicit usage instructions are not present in the repo.)
Real‑World Use
A researcher keeps a directory of Markdown notes. Running ekphos inside that directory lets them jump between linked notes via the sidebar (src/ui/sidebar.rs) and visualise the knowledge graph (src/ui/graph_view.rs). A typical workflow:
cd research/notes ekphos Press Ctrl‑p (Vim “preview”) to open linked note in a split pane Use : commands from src/vim/command.rs to search or tag
All actions stay within the terminal, preserving the remote SSH session.
Code Health & Issues
Medium – No unit or integration tests – repository lacks any tests/ directory; code paths in src/vim/, src/editor/, and src/ui/ are unverified. Medium – No CI/CD pipeline – no .github/workflows, circleci, or similar; builds and tests are not automatically gated. Low – Sparse inline documentation – only a handful of README.md and src/editor/README.md; most modules lack /// comments, making API discovery harder. Low – Configuration opacity – src/config.rs reads a user config but the repository provides no example file or schema, forcing users to rely on runtime prompts. Low – External documentation dependency – core usage details are hosted off‑repo (docs.ekphos.xyz); if the site is unavailable, onboarding suffers. Low – Potential unsafe patterns – the UI uses crossterm/tui crates (inferred from imports) but error handling around terminal size changes is not evident; may cause panics on resize.
No security‑related secrets are present, and the MIT license is clearly declared.
The Bottom Line
ekphos delivers a functional, fast terminal Markdown research tool with a well‑structured Rust codebase and clear UI modules. Its main drawbacks are the lack of automated tests/CI and limited in‑repo documentation, which increase onboarding risk for new adopters. It is a solid fit for solo developers or small teams comfortable with Rust and terminal workflows, but larger organizations should consider adding test coverage and CI before production use.