CodexSess Console

Web-First Control Plane for Codex Account Operations

Manage multi-account API/CLI routing, usage-aware automation, and OpenAI-compatible proxy endpoints 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

• New /chat coding workspace:
  • persistent sessions and message history
  • workspace picker + path suggestions
  • WebSocket-based live activity stream (/api/coding/ws) with auto reconnect and connection status indicator ([WS Connected/Connecting/Disconnected])
  • chronological mixed timeline rendering (assistant + terminal + activity) with stable ordering for same-second events
  • compact terminal grouping for contiguous command bursts, while preserving chat boundaries between groups
  • file operation activity bubbles (Edited, Read, Created, Deleted, Moved, Renamed)
  • two-step stop control (Stop then Force Stop) for running coding turns
  • slash commands (/status, /review) and skill picker
• Zo OpenAI-compatible integration:
  • multi Zo API key management in dashboard
  • per-key request tracking (Requests + Last request)
  • cached Zo model list and mapping support
• 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)
• Zo API key operations:
  • add/remove multiple Zo API keys
  • monitor request count per key
  • use Zo model list for mapping
• Browser coding workspace:
  • /chat sessions with persisted context and activity timeline
• 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 coding area in CodexSess.

In simple terms, this is where you talk to Codex from the browser instead of opening Codex CLI manually. You create a session, choose your workspace folder, then continue coding in that same session. Your chat history and workspace context are saved, so you can leave and come back without losing the flow.

The experience is designed to feel practical for daily work:

• You can resume existing sessions from the session list.
• New session flow includes workspace picker with path suggestions.
• Assistant responses and activity updates are streamed in real time over WebSocket (/api/coding/ws).
• Timeline order is preserved across mixed bubble types (assistant, terminal, activity, subagent).
• In compact mode, terminal bubbles are grouped only for contiguous command sequences; chat/activity barriers split groups.
• File operation events appear as dedicated activity bubbles (Edited, Read, Created, Deleted, Moved, Renamed) instead of being hidden in raw logs.
• The status line shows runtime connection state ([WS Connected], [WS Connecting], [WS Disconnected]) and reconnects automatically when connection drops.
• Stop behavior is two-step for safety: first click requests graceful stop, second click escalates to force kill.
• Helpful commands like /status and /review are available in chat.
• Skill hints can be inserted quickly using $skill_name.

This makes CodexSess useful as a browser-based coding companion for desktop and remote/mobile access while keeping session context organized.

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