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.

[](https://www.typescriptlang.org/) [](https://reactjs.org/) [](https://expressjs.com/)

✨ 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
• 🤖 AI Chat: Built-in AI assistant supporting Anthropic Claude and local Ollama models with streaming responses, thinking blocks, and document context

🧩 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

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

🤖 AI Chat

Codex includes an integrated AI chat assistant for asking questions about your documents:

Supported Providers

• Anthropic Claude - Cloud-based AI with optional "thinking" mode for extended reasoning
• Ollama - Run local models like Llama, Mistral, CodeLlama, and more

Features

• Streaming Responses - See AI responses as they're generated in real-time
• Document Context - AI can reference the currently open document for context-aware answers
• Thinking Blocks - Anthropic's extended thinking feature shows the AI's reasoning process (collapsible)
• Token Usage - Track input/output tokens for cost monitoring
• Chat History - Conversation persists while the app is open
• Export Chat - Download conversation history as JSON
• Custom System Prompts - Configure how the AI behaves via settings
• Multiple Accounts - Switch between different AI providers/accounts
• Markdown Rendering - AI responses render with full markdown support including code highlighting
• Copy Support - Copy individual messages or code blocks with one click

Configuration

AI accounts are configured in Settings (gear icon):

1. Click the settings icon in the header
2. Navigate to the "AI" section
3. Add an account:

• Anthropic: Enter your API key from console.anthropic.com
• Ollama: Enter host (default: localhost) and port (default: 11434)

1. Enable "AI Search" to show the AI chat button

Usage

1. Click the robot icon (🤖) in the bottom-right corner to open AI chat
2. Select your AI account from the dropdown
3. Type your question and press Enter or click Send
4. Use the thinking toggle (brain icon) for Anthropic's extended reasoning
5. Click the settings icon to customize the system prompt

Ollama Setup

To use local AI models with Ollama:

# Install Ollama (macOS)
brew install ollama

# Start Ollama server
ollama serve

# Pull a model (in another terminal)
ollama pull llama3.2
ollama pull codellama  # Great for code questions

Then add an Ollama account in Codex settings with host localhost and port 11434.

🔐 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 `, , , , , and ` 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

🛠️ Development

Project Scripts

# Development
make dev              # Run both server and client
make dev-server       # Run server only (port 3001)
make dev-client       # Run client only (port 3000)

# Building
make build            # Build both server and client
make build-server     # Build server only
make build-client     # Build client only

# Testing
make test             # Run all tests
make test-server      # Run backend tests
make test-client      # Run frontend tests

# Maintenance
make clean            # Remove all node_modules and build artifacts
make install          # Fresh install of all dependencies
make help             # Show all available commands

Development Workflow

1. Make your changes in the appropriate files
2. Tests run automatically in watch mode (if enabled)
3. Server auto-reloads on file changes (via tsx)
4. Client hot-reloads on file changes (via Vite HMR)
5. Run make test before committing

Git Workflow & Releases

This project uses Conventional Commits and commit-and-tag-version for automated changelog generation.

Commit Message Format

type(scope): description

Examples:
feat: add search functionality
fix: resolve dark mode flicker
docs: update README
refactor(api): simplify error handling

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Pull Request Workflow

# 1. Create and switch to feature branch
git switch -c feature/my-change

# 2. Make changes, commit (repeat as needed)
git add .
git commit -m "feat: add new feature"

# 3. Push branch to GitHub
git push -u origin feature/my-change

# 4. Create PR (via GitHub CLI or web)
gh pr create --title "feat: add new feature" --body "Description"

# 5. After PR is merged, switch back to main
git switch main
git pull

Creating a Release

After merging PRs and when ready to release:

# Patch release (1.0.0 → 1.0.1) - bug fixes
npm run release

# Minor release (1.0.0 → 1.1.0) - new features
npm run release:minor

# Major release (1.0.0 → 2.0.0) - breaking changes
npm run release:major

# Push with tags
git push --follow-tags

This will:

1. Bump version in package.json
2. Update CHANGELOG.md with commits since last release
3. Create a git commit and tag (e.g., v1.1.0)

Adding New Features

Backend (Adding a new API endpoint)

1. Create controller in server/src/controllers/
2. Add route in server/src/routes/
3. Register route in server/src/index.ts
4. Add tests in server/tests/

Frontend (Adding a new component)

1. Create component in client/src/components/
2. Add corresponding CSS file
3. Import and use in parent component
4. Add tests in same directory (.test.tsx)

🏗️ Project Structure

codex/
├── 📄 Makefile                    # Build automation
├── 📄 package.json                # Root package config
├── 📄 README.md                   # This file
│
├── 📁 server/                     # Backend (Express + TypeScript)
│   ├── 📄 package.json            # Server dependencies
│   ├── 📄 tsconfig.json           # TypeScript config
│   ├── 📄 jest.config.js          # Test configuration
│   ├── 📁 src/
│   │   ├── 📄 index.ts            # Server entry point
│   │   ├── 📁 controllers/        # Request handlers
│   │   │   ├── folderController.ts
│   │   │   └── pageController.ts
│   │   ├── 📁 routes/             # API routes
│   │   │   ├── folders.ts
│   │   │   └── pages.ts
│   │   └── 📁 services/           # Business logic
│   │       └── fileSystem.ts      # File operations
│   └── 📁 tests/                  # Test files
│       └── api.test.ts
│
├── 📁 client/                     # Frontend (React + TypeScript)
│   ├── 📄 package.json            # Client dependencies
│   ├── 📄 tsconfig.json           # TypeScript config
│   ├── 📄 vite.config.ts          # Vite configuration
│   ├── 📄 vitest.config.ts        # Test configuration
│   ├── 📄 index.html              # HTML entry point
│   ├── 📁 src/
│   │   ├── 📄 main.tsx            # React entry point
│   │   ├── 📄 App.tsx             # Main app component
│   │   ├── 📄 App.css             # App styles
│   │   ├── 📁 components/         # React components
│   │   │   ├── FolderTree.tsx     # Folder navigation
│   │   │   ├── FolderTree.css
│   │   │   ├── PageList.tsx       # Page list in folder
│   │   │   ├── PageList.css
│   │   │   ├── Editor.tsx         # Markdown editor
│   │   │   ├── Editor.css
│   │   │   ├── Preview.tsx        # Markdown preview
│   │   │   ├── Preview.css
│   │   │   └── *.test.tsx         # Component tests
│   │   ├── 📁 services/           # API client
│   │   │   └── api.ts
│   │   ├── 📁 types/              # TypeScript types
│   │   │   └── index.ts
│   │   └── 📁 test/               # Test setup
│   │       └── setup.ts
│
└── 📁 data/                       # File storage
    └── Welcome.md                 # Default welcome page

📋 Table of Contents

• [Quick Start](#-quick-start)
• [Installation](#-installation)
• [Usage](#-usage)
• [Project Structure](#-project-structure)
• [AI Chat](#-ai-chat)
• [MCP Server (AI Agent Access)](#-mcp-server-ai-agent-access)
• [API Documentation](#-api-documentation)
• [Testing](#-testing)
• [Development](#-development)
• [Tech Stack](#-tech-stack)
• [Makefile Commands](#-makefile-commands)
• [Troubleshooting](#-troubleshoo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bocan
• Source: bocan/codex
• License: MIT

Install and usage instructions live in the source repository linked above.