CodexSess Console

Web-First Control Plane for Codex Accounts and `/chat` Workspaces

Manage multi-account API/CLI routing, usage-aware automation, and a persistent browser coding workspace in one binary.

English | Bahasa Indonesia

Overview • Latest Major Updates • Installation • Core Capabilities • Web Coding Workspace • GitHub Code Review Workflow • TODO • UI Preview • Authentication • Environment

Overview

CodexSess is a web-first account gateway for Codex/OpenAI usage.

It is designed for operators who need:

• fast account switching
• separate active account targets for API and Codex CLI
• usage-aware automation (alert + auto switch)
• OpenAI-compatible API surface in production-friendly form

For normal usage, download binaries/packages from the latest release page:

• https://github.com/rickicode/CodexSess/releases/latest

Latest Major Updates

• Refactored /chat into a normal chat-first coding workspace:
  • persistent sessions, message history, and workspace context
  • workspace picker + path suggestions for starting or resuming work quickly
  • one chronological conversation timeline instead of planner/executor mode switching
  • Codex-style event bubbles for assistant replies, terminal output, MCP/tool activity, subagents, and file operations
  • WebSocket-based live activity stream (/api/coding/ws) with auto reconnect and connection status indicator ([WS Connected/Connecting/Disconnected])
  • two-step stop control (Stop then Force Stop) for running coding turns
  • slash commands (/status, /review) and skill picker
• Direct API and routing automation upgrades:
  • direct API mode improvements for OpenAI-compatible + Claude-compatible clients
  • codex CLI strategy supports round_robin (scheduled rotation) and manual (threshold-based switch)
  • default auto-switch threshold set to 15%
  • backend scheduler handles periodic usage checks and active-account fallback
• New system observability:
  • System Logs page with DB-backed log rotation
  • clearer usage refresh source and CLI/API switch logs

Why CodexSess Exists

CodexSess was built to simplify multi-account Codex operations without splitting tools.

Instead of juggling scripts, manual token edits, and separate dashboards, CodexSess centralizes:

• active API account control
• active CLI account control
• account usage visibility
• automated fallback decisions when limits are low

Installation (Linux)

Use installer from repository raw script:

curl -fsSL https://raw.githubusercontent.com/rickicode/CodexSess/main/scripts/install.sh | bash

Mode examples:

# auto (default)
curl -fsSL https://raw.githubusercontent.com/rickicode/CodexSess/main/scripts/install.sh | bash -s -- --mode auto

# gui package install (.deb/.rpm)
curl -fsSL https://raw.githubusercontent.com/rickicode/CodexSess/main/scripts/install.sh | bash -s -- --mode gui

# server / cli install
curl -fsSL https://raw.githubusercontent.com/rickicode/CodexSess/main/scripts/install.sh | bash -s -- --mode server

# update existing install type (auto-detect gui/server)
curl -fsSL https://raw.githubusercontent.com/rickicode/CodexSess/main/scripts/install.sh | bash -s -- --mode update

GUI mode public access toggle (via ~/.bashrc):

echo 'export CODEXSESS_PUBLIC=true' >> ~/.bashrc
source ~/.bashrc

Then restart CodexSess GUI session.

Windows installation:

• Download .exe directly from:
  • https://github.com/rickicode/CodexSess/releases/latest

Core Capabilities

• OpenAI-compatible and Claude-compatible proxy endpoints:
  • POST /v1/chat/completions (including SSE streaming)
  • GET /v1/models
  • POST /v1/responses
  • POST /claude/v1/messages
• Separate active account state:
  • API active account
  • CLI (Codex) active account
• Multi-account routing strategy:
  • CLI round_robin rotation (default scheduler interval: 5 minutes)
  • round-robin avoids immediate account reuse and prefers accounts that were not used in the recent window, while still falling back when options are limited
  • round-robin never activates a CLI account with weekly usage equal to 0
  • CLI manual auto-switch when remaining usage is below threshold
• Usage refresh and automation:
  • threshold alerts
  • configurable auto-switch behavior
  • default auto-switch threshold is 15% (configurable in Settings/API)
• Browser coding workspace:
  • /chat sessions with persisted context, one chat-first timeline, and Codex-style event bubbles
• System observability:
  • System Logs view with automatic log rotation
• Embedded web console and API proxy in one binary

Web Coding Workspace (/chat)

/chat is the normal browser coding workspace in CodexSess.

You open a session, pick a workspace, and keep working in that same conversation instead of jumping between hidden planning or executor modes. History, runtime state, and workspace context stay attached to the session, so the browser view behaves like a practical Codex workbench rather than a temporary prompt box.

The /chat flow is optimized for everyday coding:

• Resume existing sessions from the session list without rebuilding context.
• Start new sessions with the workspace picker and path suggestions.
• Follow one chronological timeline that mixes assistant replies with runtime activity in the order it happened.
• Read Codex-style event bubbles for terminal output, MCP/tool activity, subagents, and file operations (Edited, Read, Created, Deleted, Moved, Renamed) without digging through raw logs.
• Watch live updates over WebSocket (/api/coding/ws) with automatic reconnect and visible connection state.
• Stop runs safely with the retained two-step Stop -> Force Stop control.
• Use chat-native helpers like /status, /review, and $skill_name insertion directly from the composer.

This keeps /chat useful for desktop, remote, and mobile access while preserving one clear mental model: talk to Codex in a persistent coding session and watch the work happen in-line.

UI Preview

Authentication & Session

• Management console requires login.
• First-run default credential:
  • username: admin
  • password: hijilabs
• Session remember duration: 30 days.
• Password change via CLI:
  • --changepassword

API compatibility routes under /v1/* and /claude/v1/* remain API-key style routes and are not blocked by web login UI flow. This means OpenAI clients and Claude-style clients can both be routed through CodexSess.

GitHub Code Review Workflow

To use CodexSess automated PR review/autofix in GitHub:

• Use workflow file: .github/workflows/code-review.yml
• Add required repository secrets:
  • CODEXSESS_URL
  • CODEXSESS_API_KEY
• Optional secret:
  • EXA_API_KEY (enables Exa MCP server in workflow)
• Trigger modes:
  • automatic on pull_request events
  • manual via workflow_dispatch
• Manual inputs (workflow_dispatch):
  • target_ref (optional, branch/tag/sha; default main)
  • review_scope (diff or full)
  • review_focus (optional focus area)

Behavior:

• Automatic PR run: posts review to PR and pushes autofix to PR branch when allowed.
• Manual run: reviews selected target_ref; if autofix exists, workflow creates and pushes a new branch automatically.
• Workflow configures default MCP servers for Codex in CI:
  • filesystem (free)
  • sequential_thinking (free)
  • memory (free)
  • exa (enabled when EXA_API_KEY is provided)

TODO

• Continue parity improvements with Codex CLI core flow:
  • start/resume/stop interactive sessions
  • stream tool/terminal output in real time
  • workspace-aware file editing and diffs
  • approval/sandbox controls exposed in web UI
• Implement session isolation and security guardrails before public multi-device usage:
  • per-session workspace boundaries
  • strict command policy and audit logs
  • rate limits and timeout controls

Environment Variables

Variable	Default	Example	Description
PORT	3061	PORT=8080	HTTP server port.
CODEXSESS_PUBLIC	false	CODEXSESS_PUBLIC=true	Enable network/public bind (0.0.0.0:<PORT>). When false, bind is local-only (127.0.0.1:<PORT>).
CODEXSESS_NO_OPEN_BROWSER	false	CODEXSESS_NO_OPEN_BROWSER=true	Disable automatic browser opening on startup. Truthy values: 1, true, yes.
CODEXSESS_CODEX_SANDBOX	full-access	CODEXSESS_CODEX_SANDBOX=full-access	Sandbox mode passed to codex exec (write/workspace-write is normalized to full-access).
CODEXSESS_CLEAN_EXEC	true	CODEXSESS_CLEAN_EXEC=false	Run Codex execution in isolated mode (true) or normal environment (false).
CODEXSESS_USAGE_SCHEDULER_REFRESH_TIMEOUT_SECONDS	120	CODEXSESS_USAGE_SCHEDULER_REFRESH_TIMEOUT_SECONDS=240	Timeout for scheduled usage refresh tick. Bounded to 30..600 seconds.
CODEXSESS_USAGE_SCHEDULER_SWITCH_TIMEOUT_SECONDS	45	CODEXSESS_USAGE_SCHEDULER_SWITCH_TIMEOUT_SECONDS=90	Timeout for autoswitch check phase (API/CLI) in scheduler tick. Bounded to 10..300 seconds.
CODEXSESS_CLI_SWITCH_NOTIFY_CMD	``	CODEXSESS_CLI_SWITCH_NOTIFY_CMD="peon preview resource.limit"	Optional command executed when CLI active account changes. Env: CODEXSESS_CLI_SWITCH_FROM, CODEXSESS_CLI_SWITCH_TO, CODEXSESS_CLI_SWITCH_REASON, CODEXSESS_CLI_SWITCH_TO_EMAIL.

Notes:

• On Windows, data directory defaults to %APPDATA%\\codexsess when APPDATA is available.
• CODEX_HOME is set internally per selected account and is not intended as an external switch for CodexSess itself.

Project Scope

CodexSess focuses on operational reliability for Codex account usage:

• predictable account selection
• clear active-state visibility
• usage-aware automation and fallback
• OpenAI-compatible integration surface