Skip to main content

CodeX Core CXC

Hello everyone, my name is Rion. This is my boredom project, which might be useful for you. This tool has several features such as:

Features

  • Download Music with yt-dlp
  • Search Music with yt-dlp
  • Video Downloader (DV)
  • Local Search (typo-tolerant)
  • mpx Music Player X (VLC / mpv)
  • AI Chat — full terminal UI built with Textual
  • Send images and text files to the AI from chat (/file)
  • Theme picker with automatic saving
  • Config manager (path, edit, reset, set, list-theme)
  • System state report (state)
  • About screen (about)
  • Self Update (checks PyPI, upgrades via pipx)

How to use

cxc help

Commands

Command Alias Description
cxc search "<title>" -S Search music information
cxc search --local "<title>" Search your downloaded files locally
cxc download "<title>" -D Search and download music to MP3
cxc DV -r "<res>" "<URL>" Download a video at a chosen quality
cxc mpx Open Music Player X
cxc chat Open the AI chat UI
cxc state Display current system state
cxc about Show information about cxc
cxc config <subcommand> Manage the cxc configuration
cxc time -t Show time, day, month, and year
cxc update -U Check PyPI and update via pipx
cxc version -v Show the current version
cxc help h Display the help menu

mpx (Music Player X)

cxc mpx opens an interactive player. It uses python-vlc when available and automatically falls back to mpv otherwise.

Command Description
play <n> Play track number <n>
play all Play every track in the folder
play <filename> Play a file by name
pause Pause / resume
resume Resume playback
stop Stop playback
next / prev Next / previous track
volume <0-100> Set volume (no argument shows it)
now Show the current track
list List all tracks
help Show the mpx help
quit Exit mpx

Note: python-vlc needs the native libvlc library. On systems without it, cxc mpx falls back to mpv (with limited controls: no pause/next/prev/volume).

AI Chat

cxc chat opens a Textual-based chat UI with Markdown rendering and streamed "typing" feedback.

Input / Key Description
<message> Send a message to the AI
/file <path> <prompt> Send a file to the AI, with an optional prompt
help Open the in-app help screen
quit Leave the chat
Ctrl+Q Quit the app
Ctrl+H Open the help screen
Ctrl+P Open the Textual command palette (theme picker, etc.)

File support:

  • Images — .jpg, .jpeg, .png, .webp are sent inline as base64 so the model can see them.
    /file ~/photo.png Look at this.
    
  • Text files — any other extension is read as UTF-8 and appended to your prompt.
    /file ~/notes.txt Summarize this.
    

The theme is saved to ~/.config/cxc/config.toml automatically when you change it, so your choice sticks between sessions.

Configuration

cxc stores its settings in ~/.config/cxc/config.toml (TOML format). The file is created automatically on first run — just edit it and restart cxc.

# CodeX Core (cxc) configuration
# Edit this file then restart cxc.

[ai]
API = "PASTE_YOUR_API_KEY"
MODEL = "gemini-2.5-flash"
# AI_PROMPT may reference other keys, e.g. {AI_NAME}
AI_PROMPT = "You Are {AI_NAME}"

[appearance]
LOADING_STYLES = "#"
AI_NAME = "Your_Ai_Name"
THEME = "catppuccin-mocha"

[folders]
MUSIC_DIR = "Music"
VIDEO_DIR = "Videos"
Key Description
API Your Gemini API key (required for cxc chat).
MODEL The AI model to use, e.g. gemini-2.5-flash.
AI_PROMPT The system prompt. May reference other keys, e.g. {AI_NAME}.
LOADING_STYLES Character used for the animated "typing" indicator in chat.
AI_NAME The name shown for the AI in chat.
THEME Textual theme used by the chat UI (see list-theme).
MUSIC_DIR Folder for downloaded music, relative to your home directory.
VIDEO_DIR Folder for downloaded videos, relative to your home directory.

Managing the config

Command Description
cxc config Show the config help
cxc config path Show the config directory
cxc config edit Open config.toml in $EDITOR/nano/vim
cxc config reset Reset the config to defaults
cxc config set <KEY> <VALUE> Set a single value in config.toml
cxc config list-theme List available Textual themes

Examples:

cxc config path
cxc config set THEME catppuccin-mocha
cxc config set AI_NAME Nova
cxc config list-theme

cxc config reset wipes all settings, including your API key. Back up first.

State

cxc state prints a quick diagnostic report:

  • distro name and ID, kernel version
  • whether ffmpeg is installed
  • whether the API key is configured
  • Python binary and version
  • whether you are inside a virtualenv
  • config file permissions (warns if not 600)
  • config directory and music directory
===========================================
CXC STATE...
===========================================
Distro      : ...
Kernel      : ...
FFmpeg      : Installed
APIKEY      : Active
Python3     : ... (3-11-0)
Env         : system
Config Mode : 0o600 (Secure)
Config DIR  : /home/you/.config/cxc/config.toml
Music  DIR  : /home/you/Music

About

cxc about shows the project name, author, license, PyPI/GitHub links, and a short description of cxc.

Config format & migration

The configuration format changed from a Python file (config.py) to TOML (config.toml). You don't need to do anything manually:

  • If you upgrade from an old version, cxc migrates automatically the first time you run it:
    1. reads your old config.py,
    2. writes the new config.toml,
    3. keeps a backup of the old file as config.py.bak,
    4. removes the old .lock file.
  • Your API key and all other settings are preserved.
  • If you have no old config, a fresh config.toml is created for you.
  • The file is stored with owner-only permissions (600) because it holds your API key.
  • cxc now requires Python 3.11+ (for the built-in tomllib).

Update

What's New in v2.0.0

  • New cxc chat — the AI chat was rebuilt as a Textual terminal UI: Markdown bubbles, animated typing indicator, help screen, themes, and a footer with key bindings.
  • Send files to the AI — /file <path> <prompt> supports images (.jpg, .jpeg, .png, .webp, sent inline) and plain-text files.
  • Config manager — cxc config path|edit|reset|set|list-theme to inspect and change settings without opening the file by hand, including a theme picker (cxc config list-theme).
  • cxc state — a system report covering distro, kernel, ffmpeg, API key status, Python/venv, config permissions, and folders.
  • cxc about — a short about screen with author, license, and project links.
  • New config keys — LOADING_STYLES and THEME, plus the TOML file is now grouped into [ai], [appearance], and [folders].

What's New in v1.1.0

  • Smarter cxc update — the updater now checks PyPI for the latest release and only offers to upgrade when a newer version exists, instead of always running pipx upgrade.
  • Download hands off to mpx — after a download finishes, cxc prints the saved track name and points you to cxc mpx to play it, instead of spawning a separate mpv player.
  • Cleanup — removed leftover mpv playback code and unused imports from cxc.py, downloader.py, and chat.py.

What's New in v1.0.0 (First Stable Release)

  • Video Downloader (DV) — download videos with yt-dlp and pick the resolution, e.g. cxc DV -r "360" "<URL>".
  • Self Update — update cxc straight from the terminal using pipx upgrade, e.g. cxc update.
  • Local Search — find your downloaded music/videos on your device with partial-title and typo-tolerant matching, e.g. cxc search --local "<music title>".
  • New config format — configuration moved from config.py to config.toml, with automatic migration from the old file. See the Configuration section.
  • VLC-based mpx — the music player now uses python-vlc with full playback controls (pause, next/prev, volume), with an automatic mpv fallback.
  • pyproject.toml — packaging moved from setup.py to the modern pyproject.toml standard.

Notes

  • Before using the chat feature, please set your configuration first in ~/.config/cxc/config.toml (see Configuration).
  • The current release is v2.0.0.
  • The 1.26.x versions were the nightly channel. v1.0.0 is the first stable release of CXC, so the versioning restarts from here.

I will update regularly but I can't guarantee it, so see you in the next update.

Metadata

Release files for cxc 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cxc 2.0.0
File Size Uploaded Provenance Actions
cxc-2.0.0.tar.gz 21.3 kB Without provenance Details for cxc-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cxc 2.0.0
File Interpreter ABI Platform Actions
cxc-2.0.0-py3-none-any.whl Python 3 none any Details for cxc-2.0.0-py3-none-any.whl

Total release size: 40.8 kB

Release files / cxc-2.0.0.tar.gz

Download URL cxc-2.0.0.tar.gz
Size 21.3 kB
Tags Source
SHA-256 checksum
How to use checksums
65df5c3e10a3f190d0e42776210dd056a0bd4f77605dc2e56889bfbd09aa5140
BLAKE2b-256 checksum
How to use checksums
3e92ee04117654b2063a79f6af9af5b930c78a06dee7298a60673ea285c5d15e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / cxc-2.0.0-py3-none-any.whl

Download URL cxc-2.0.0-py3-none-any.whl
Size 19.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8bbda03b73075fedbfb01dd5456c482d3105b1f4ec6ad406f86925fb84d673cc
BLAKE2b-256 checksum
How to use checksums
26818ba07aff21ea0036f3250f7e3fa1336167db5ae3ee893349674a60eb0475
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for cxc 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page