# Codex

> A wiki and document store built with React + Express. Organize markdown files in folders with a beautiful three-pane UI, dark mode, live preview, full REST API, and an optional built in MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-bocan-codex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bocan](https://agentstack.voostack.com/s/bocan)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bocan](https://github.com/bocan)
- **Source:** https://github.com/bocan/codex

## Install

```sh
agentstack add mcp-bocan-codex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## 🤖 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](https://console.anthropic.com)
   - **Ollama**: Enter host (default: localhost) and port (default: 11434)
4. 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:

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

```bash
# 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:

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

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

### Running

```bash
# Start both server and client
make dev

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

## 🛠️ Development

### Project Scripts

```bash
# 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](https://www.conventionalcommits.org/) and [commit-and-tag-version](https://github.com/absolute-version/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

```bash
# 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:

```bash
# 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](https://github.com/bocan)
- **Source:** [bocan/codex](https://github.com/bocan/codex)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bocan-codex
- Seller: https://agentstack.voostack.com/s/bocan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.