bocan/codex repository overview

⁠📝 Codex

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.

⁠✨ 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:

```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

# Clone the repository
git clone https://github.com/bocan/codex.git
cd codex

# Install dependencies
make install

⁠Configuration

Create a .env file in the root directory:

# Required: Set your password
AUTH_PASSWORD=your-secure-password-here

# Optional: Server port (default: 3001)
PORT=3001

⁠Running

# Start both server and client
make dev

# Visit http://localhost:3000
# Login with your AUTH_PASSWORD

⁠📋 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:

# Install all dependencies
make install

# Run the application
make dev

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)

make install

⁠Option 2: Using npm

npm run install:all

⁠Option 3: Manual Installation

# Install root dependencies
npm install

# Install server dependencies
cd server && npm install

# Install client dependencies
cd ../client && npm install

⁠🎯 Usage

⁠Running the Application

⁠Option 1: Using Make (Recommended)

# Run both server and client in development mode
make dev

# Or run them separately
make dev-server    # Runs server on port 3001
make dev-client    # Runs client on port 3000

⁠Option 2: Using npm

# Run both concurrently
npm run dev

# Or run separately
npm run dev:server
npm run dev:client

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

# Using Make
make build

# Using npm
npm run build

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:

docker pull bocan/codex:latest

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):

cosign verify bocan/codex:latest \
  --certificate-identity-regexp=https://github.com/bocan/codex \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com

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:

docker buildx imagetools inspect bocan/codex:latest --format "{{ json .SBOM }}"

⁠Using Docker Compose (Recommended)

# Build and start the container
docker compose up -d --build

# View logs
docker compose logs -f codex

# Stop the container
docker compose down

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

⁠Using Raw Docker

# Build the image
docker build -t codex .

# Run the container
docker run -d \
  --name codex \
  -p 3001:3001 \
  -v $(pwd)/data:/app/data \
  -e NODE_ENV=production \
  codex

# View logs
docker logs -f codex

# Stop and remove
docker stop codex && docker rm codex

⁠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:

environment:
  - NODE_ENV=production
  - PORT=3001
  # - AUTH_PASSWORD=your-password  # Commented out

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:

server {
    listen 443 ssl;
    server_name wiki.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

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 Model Context Protocol⁠ (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:

   export MCP_ENABLED=true
   export MCP_API_KEY=your-secure-api-key
   

   Copy

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

   npm run dev:mcp -w server  # Development with hot reload
   

   Copy

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):

{
  "mcpServers": {
    "codex": {
      "url": "http://localhost:3002/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

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

{
  "servers": {
    "codex": {
      "type": "http",
      "url": "http://localhost:3002/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

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

⁠📡 API Documentation

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

⁠Health Check

GET /api/health

Response:

{
  "status": "ok"
}

⁠Folder Endpoints

⁠Get Folder Tree

GET /api/folders

Response:

{
  "name": "root",
  "path": "/",
  "type": "folder",
  "children": [
    {
      "name": "Projects",
      "path": "Projects",
      "type": "folder",
      "children": []
    }
  ]
}

⁠Create Folder

POST /api/folders
Content-Type: application/json

{
  "path": "folder-name"
}
# or nested: "parent/subfolder"

Example:

curl -X POST http://localhost:3001/api/folders \
  -H "Content-Type: application/json" \
  -d '{"path": "My Notes"}'

⁠Delete Folder

DELETE /api/folders/:path

Example:

curl -X DELETE http://localhost:3001/api/folders/My%20Notes

⁠Rename Folder

PUT /api/folders/rename
Content-Type: application/json

{
  "oldPath": "old-name",
  "newPath": "new-name"
}

Example:

curl -X PUT http://localhost:3001/api/folders/rename \
  -H "Content-Type: application/json" \
  -d '{"oldPath": "My Notes", "newPath": "Work Notes"}'

⁠Page Endpoints

⁠List Pages in Folder

GET /api/pages?folder=folder-path

Response:

[
  {
    "name": "page1.md",
    "path": "folder/page1.md",
    "type": "file"
  }
]

⁠Get Page Content

GET /api/pages/:path

Response:

{
  "path": "folder/page1.md",
  "content": "# Page Title\n\nContent here..."
}

Example:

curl http://localhost:3001/api/pages/My%20Notes/hello.md

⁠Create Page

POST /api/pages
Content-Type: application/json

{
  "path": "folder/page.md",
  "content": "# Page Title\n\nContent here..."
}

Example:

curl -X POST http://localhost:3001/api/pages \
  -H "Content-Type: application/json" \
  -d '{"path": "My Notes/hello.md", "content": "# Hello World\n\nThis is my first page!"}'

⁠Update Page

PUT /api/pages/:path
Content-Type: application/json

{
  "content": "# Updated Content"
}

Example:

curl -X PUT http://localhost:3001/api/pages/My%20Notes/hello.md \
  -H "Content-Type: application/json" \
  -d '{"content": "# Updated Hello\n\nNew content!"}'

⁠Delete Page

DELETE /api/pages/:path

Example:

curl -X DELETE http://localhost:3001/api/pages/My%20Notes/hello.md

⁠Rename Page

PUT /api/pages/rename/file
Content-Type: application/json

{
  "oldPath": "old-page.md",
  "newPath": "new-page.md"
}

Example:

curl -X PUT http://localhost:3001/api/pages/rename/file \
  -H "Content-Type: application/json" \
  -d '{"oldPath": "My Notes/hello.md", "newPath": "My Notes/welcome.md"}'

⁠Move Page

PUT /api/pages/move
Content-Type: application/json

{
  "oldPath": "folder1/page.md",
  "newFolderPath": "folder2"
}
# Returns: { "success": true, "newPath": "folder2/page.md" }

Example:

curl -X PUT http://localhost:3001/api/pages/move \
  -H "Content-Type: application/json" \
  -d '{"oldPath": "My Notes/hello.md", "newFolderPath": "Projects"}'

⁠Getting Help

• Check the GitHub Issues⁠
• Review the API documentation above
• Ensure all prerequisites are installed
• Try a clean install: make clean && make install

⁠📄 License

MIT

⁠🙏 Acknowledgments

• Built with React⁠ and Express⁠
• Markdown rendering by react-markdown⁠
• Icons from Unicode emoji

Made with ❤️ for taking better notes