bocan/codex

📝 Codex

A wiki and document store built with React and Express.

Single-user personal knowledge base - A full-stack TypeScript application that provides a beautiful, intuitive interface for creating and managing markdown documents organized in a hierarchical folder structure.

⚠️ Note: Codex is designed as a single-user application. It does not support concurrent multi-user editing or collaboration features. Perfect for personal wikis, note-taking, and documentation.

✨ Features

• 📁 Folder Management: Create, delete, and rename folders in a collapsible tree view with right-click context menus
• 📝 Markdown Pages: Create and edit markdown documents with GitHub Flavored Markdown support
• 🧩 Smart Templates: Create new pages from reusable templates (stored under data/templates/)
• 📊 Mermaid Diagrams: Render Mermaid code fences in preview/reading mode, with export/download support
• 🎨 Three-Pane Layout: Folder tree (left), markdown editor (center), live preview (right)
• 📐 Fully Resizable: Drag to resize both horizontal panes (left/right) and vertical sections (folder tree/page list)
• 🌓 Theme Options: Auto-detects system theme preference with manual override - cycles through auto/light/dark/high-contrast modes
• ♿ Accessibility: Full ARIA labels, semantic HTML, high-contrast theme, and improved color contrast for WCAG compliance
• 📤 Move Pages: Elegant folder picker to move pages between folders via right-click menu
• 💾 Smart Auto-save: 10-second throttled saves with 5-second typing debounce - prevents excessive saves while keeping your work safe
• 🔄 Live Preview: Real-time markdown preview that updates instantly as you type (no waiting for saves)
• 🔗 Internal Links: Click links to other .md files to navigate within the app; anchor links scroll to headings
• 📜 Version History: Git-backed version control with visual diff highlighting (green/red for additions/deletions)
• 🔍 Restore Versions: Browse and restore any previous version of your documents
• 📖 Reading Mode: Open any page in a new window for distraction-free reading
• 🔃 Synchronized Scrolling: Editor scroll position syncs to preview pane
• 📄 Auto-select README: Navigating to a folder automatically opens its README.md if present
• 🔎 Full-Text Search: Quick search across all pages with keyboard shortcut (⌘K/Ctrl+K) and relevance-ranked results
• 📑 Table of Contents: Auto-generated, collapsible TOC for easy document navigation with active section highlighting
• 🎤 Speech-to-Text: Dictate content using Web Speech API (Chrome/Edge/Safari)
• ⚡ Performance Caching: Server-side caching layer with 30-second TTL for fast folder/page loading
• 🌐 RESTful API: Programmatic access to all folder and page operations
• ✅ Tested: Comprehensive test suite for both backend and frontend
• 🎯 Collapsible Panes: Hide sidebars for distraction-free writing
• 🚀 Fast & Lightweight: Built with Vite for lightning-fast development
• 🔐 Password Protection: Simple password-based authentication to secure your data
• 🛡️ Security Features: Rate limiting, request logging, and security headers

🧩 Smart Templates

When creating a new page, Codex can start from a template instead of a blank page.

• Templates live in data/templates/*.md
• Optional frontmatter at the top of the template file:
  • template: Your Template Name (display name)
  • autoname: true|false (auto-generate a filename when creating)
• The frontmatter is stripped from the created page content automatically

📊 Mermaid Diagrams

Codex supports Mermaid diagrams in markdown via fenced code blocks:

md
```mermaid
graph TD
  A --> B
```

• Diagrams render in the live preview and in reading mode (open in new window)
• You can download rendered diagrams as SVG
• Export flows (e.g. Word/PDF) include diagrams as images rather than raw Mermaid text

🔐 Security & Logging

Codex includes several security features to protect your data:

Authentication

• Password-based login with bcrypt hashing (10 salt rounds)
• Session management using httpOnly cookies (24-hour expiration)
• Authentication can be disabled by not setting AUTH_PASSWORD (not recommended for public deployments)

Rate Limiting

• Login endpoint is rate-limited to 5 attempts per 15 minutes per IP address
• Prevents brute force password attacks
• Returns 429 Too Many Requests when limit is exceeded

Logging

All login attempts are logged with timestamps and IP addresses:

• ✓ Successful login from 192.168.1.100 - Successful authentication
• ✗ Failed login attempt from 192.168.1.100 - Invalid password
• Login attempt without password from 192.168.1.100 - Missing password
• Login attempt when auth disabled from 192.168.1.100 - Auth not configured

HTTP request logging (via morgan):

• Development: Concise colored output showing method, URL, status, and response time
• Production: Combined Apache-style logs with full details

Security Headers

Helmet middleware provides:

• Content Security Policy (CSP)
• X-Frame-Options (clickjacking protection)
• X-Content-Type-Options (MIME sniffing protection)
• Strict-Transport-Security (HTTPS enforcement in production)
• And other security headers

Best Practices

• Always set a strong AUTH_PASSWORD for deployments
• Use a unique SESSION_SECRET in production
• Enable HTTPS in production (NODE_ENV=production)
• Monitor logs for suspicious login patterns
• Consider deploying behind a reverse proxy (nginx, Caddy) for additional security

♿ Accessibility Features

Codex is designed to be accessible to all users, including those using assistive technologies:

Screen Reader Support

• Comprehensive ARIA labels on all interactive elements
• Semantic HTML structure using <header>, <nav>, <main>, <section>, <aside>, and <article> elements
• Live regions (aria-live) announce dynamic content updates
• Proper roles (role="tree", role="button", role="dialog") for enhanced navigation
• Keyboard navigation support with proper focus management and tabIndex attributes
• Descriptive labels explain the state and purpose of all controls

Visual Accessibility

• Four theme options: Auto (follows system), Light, Dark, and High-Contrast
• High-contrast mode provides maximum visual clarity:
  • Pure black (#000) background with white (#fff) text
  • Yellow (#ffff00) secondary text for clear distinction
  • Cyan (#00ffff) accent colors for links and interactive elements
  • White borders for clear element separation
• Improved contrast ratios in all themes for WCAG compliance
• Larger interactive elements: Buttons sized at 32px for easier clicking
• Consistent theming: All features including reading mode support all themes

Keyboard Accessibility

• Tab navigation through all interactive elements
• Arrow key navigation (↑↓) or vim-style (j/k) in folder tree, page list, and search results
• Enter to activate buttons, open folders/pages, and select search results
• Escape to close modals and dialogs
• ⌘K/Ctrl+K global search shortcut
• Focus indicators show keyboard-selected items with blue outline
• Mouse hover sync updates keyboard selection for seamless interaction

The accessibility features ensure Codex can be used effectively by people with:

• Visual impairments (screen readers, high-contrast mode)
• Motor disabilities (keyboard-only navigation, larger click targets)
• Color blindness (semantic colors with sufficient contrast)

🚀 Quick Start

Installation

CODE_TOKEN_2

Configuration

Create a .env file in the root directory:

CODE_TOKEN_3

Running

CODE_TOKEN_4

📋 Table of Contents

• Quick Start
• Installation
• Usage
• Project Structure
• MCP Server (AI Agent Access)
• API Documentation
• Testing
• Development
• Tech Stack
• Makefile Commands
• Troubleshooting
• Contributing

🚀 Quick Start

The fastest way to get started using the Makefile:

CODE_TOKEN_5

Then open http://localhost:3000 in your browser!

📦 Installation

Prerequisites

• Node.js 18+ and npm
• macOS, Linux, or Windows with WSL

Option 1: Using Make (Recommended)

CODE_TOKEN_6

Option 2: Using npm

CODE_TOKEN_7

Option 3: Manual Installation

CODE_TOKEN_8

🎯 Usage

Running the Application

Option 1: Using Make (Recommended)

CODE_TOKEN_9

Option 2: Using npm

CODE_TOKEN_10

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• API Health Check: http://localhost:3001/api/health

Using the Web Interface

1. Navigate Folders: Click on folders in the left pane to select them
2. Create Folders: Right-click any folder and select "New Folder"
3. Create Pages: Select a folder and click "+ New Page"
4. Edit Content: Click on a page to open it in the editor (center pane)
5. Rename Page: Right-click on a page and select "Rename"
6. Move Page: Right-click on a page and select "Move to..." to move it to another folder
7. Delete Page: Right-click on a page and select "Delete"
8. Preview: See live markdown preview in the right pane
9. Auto-save: Content saves automatically after 2 seconds
10. Resize Panes:
    • Drag the edge of left/right panes to resize horizontally
    • Drag the divider between folder tree and page list to resize vertically
11. Collapse Panes: Use the arrow buttons to hide left/right panes
12. Theme Toggle: Click the theme button (🌓/☀️/🌙/◐) in the header to cycle through auto/light/dark/high-contrast modes

Production Build

CODE_TOKEN_11

This creates optimized production builds in:

• server/dist/ - Compiled backend
• client/dist/ - Optimized frontend bundle

� Docker Deployment

Codex can be run in Docker for simplified deployment. In production mode, Express serves both the API and the React UI from a single port (3001).

Pre-built Images

Official multi-architecture (AMD64/ARM64) images are available on Docker Hub:

CODE_TOKEN_12

Available tags:

• latest - Latest stable release
• 2.7.0 - Specific version (example)
• 2.7 - Minor version (example)
• 2 - Major version (example)

Image verification (signed with Cosign): CODE_TOKEN_13

Supply chain security:

• Images are signed with Cosign for authenticity verification
• SBOM (Software Bill of Materials) embedded in image metadata
• Provenance attestations document the build process

To inspect the SBOM: CODE_TOKEN_14

Using Docker Compose (Recommended)

CODE_TOKEN_15

The application will be available at http://localhost:3001 (both UI and API on the same port).

Using Raw Docker

CODE_TOKEN_16

Docker Configuration

Environment Variables (in docker-compose.yml):

• NODE_ENV=production - Runs in production mode
• PORT=3001 - Server port (default)
• AUTH_PASSWORD=your-password - Set to enable authentication (optional)
• TRUST_PROXY=true - Enable when behind a reverse proxy with HTTPS

Volume Mounting:

• ./data:/app/data - Persists your wiki data outside the container

Authentication in Docker

Important: Due to secure cookie requirements, there are two ways to run Codex with authentication:

Option 1: Run Passwordless Locally (for testing)

Remove or comment out the AUTH_PASSWORD environment variable in docker-compose.yml:

CODE_TOKEN_17

This allows direct HTTP access without authentication, suitable for local testing.

Option 2: Deploy Behind a Reverse Proxy (for production)

For production with authentication, deploy behind a reverse proxy (nginx, Caddy, Traefik) that:

1. Terminates TLS/HTTPS
2. Forwards requests to Codex with the X-Forwarded-Proto: https header
3. Set TRUST_PROXY=true in the environment variables

Example with nginx: CODE_TOKEN_18

Why? In production mode, session cookies use secure: auto, which requires HTTPS. Direct HTTP access with a password set will fail because the browser won't send the secure cookie. The reverse proxy provides HTTPS termination while communicating with Codex via HTTP internally.

🤖 MCP Server (AI Agent Access)

Codex includes a https://modelcontextprotocol.io/ (MCP) server that allows AI agents like Claude, GitHub Copilot, and other MCP-compatible clients to interact with your documentation.

Quick Setup

1. Enable the MCP server by setting environment variables: CODE_TOKEN_19

2. Start the server (runs alongside the main app): CODE_TOKEN_20

3. Connect your MCP client to http://localhost:3002/mcp

Available Tools

The MCP server exposes 12 tools for AI agents:

Client Configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json): CODE_TOKEN_21

VS Code / GitHub Copilot (settings or mcp.json): CODE_TOKEN_22

For full documentation, see server/src/mcp/README.md.

📡 API Documentation

The REST API is available at http://localhost:3001/api

Health Check

CODE_TOKEN_23

Response: CODE_TOKEN_24

Folder Endpoints

Get Folder Tree

CODE_TOKEN_25

Response: CODE_TOKEN_26

Create Folder

CODE_TOKEN_27

Example: CODE_TOKEN_28

Delete Folder

CODE_TOKEN_29

Example: CODE_TOKEN_30

Rename Folder

CODE_TOKEN_31

Example: CODE_TOKEN_32

Page Endpoints

List Pages in Folder

CODE_TOKEN_33

Response: CODE_TOKEN_34

Get Page Content

CODE_TOKEN_35

Response: CODE_TOKEN_36

Example: CODE_TOKEN_37

Create Page

CODE_TOKEN_38

Example: CODE_TOKEN_39

Update Page

CODE_TOKEN_40

Example: CODE_TOKEN_41

Delete Page

CODE_TOKEN_42

Example: CODE_TOKEN_43

Rename Page

CODE_TOKEN_44

Example: CODE_TOKEN_45

Move Page

CODE_TOKEN_46

Example: CODE_TOKEN_47

Getting Help

• Check the https://github.com/yourusername/codex/issues
• Review the API documentation above
• Ensure all prerequisites are installed
• Try a clean install: make clean && make install

📄 License

MIT

🙏 Acknowledgments

• Built with https://reactjs.org/ and https://expressjs.com/
• Markdown rendering by https://github.com/remarkjs/react-markdown
• Icons from Unicode emoji

---

Made with ❤️ for taking better notes