🕸️ Nexum

Retro CLI Chat

A CLI Chat tool designed specifically for Windows Terminal

English | 中文

---

✨ Core Features

🎯 Session Management

• Auto-save all conversations to local sessions/
• /history to quickly switch, search, preview, rename, and delete sessions
• Support export/import for easy backup and sharing

🔌 Multi-Provider Support

• Support OpenAI and any OpenAI-compatible API
• Customize base_url, headers to adapt to various services
• One-click switching between different Providers and Models

📎 File Attachments

• /attach to select local files
• Images automatically converted to base64
• Text files automatically inlined (supports JSON, YAML, XML, etc.)

🎨 Skill System

• Define custom prompts in skills/<skill_name>/
• Type @skill_name to quickly trigger
• Auto-matching support: AI selects Skills based on context

⚡ Smooth Experience

• Streaming output: see AI responses in real-time
• Press Esc to interrupt requests at any time
• Rich rendering: Markdown, code highlighting, out of the box

---

🚀 Quick Start

1️⃣ Installation & Running

Make sure you have uv installed (recommended Python package manager)

# In project root directory
uv sync
uv run nexum

✅ First run will:

• Prompt for your nickname (user_id)
• Auto-create config directories: skills/, sessions/, export/
• Generate providers.json template (you need to fill in API Key)

2️⃣ Configure Provider

Edit providers.json in the root directory:

{
  "schema_version": "providers@v1",
  "providers": [
    {
      "name": "openai",
      "api_key": "sk-YOUR_KEY_HERE",
      "base_url": "https://api.openai.com/v1",
      "models": ["gpt-4o-mini"],
      "streaming": true
    }
  ]
}

💡 Tips:

• base_url is optional, used for third-party service compatibility
• Set streaming to false to disable streaming output
• Supports custom headers, such as special authentication methods

3️⃣ Start Chatting

After running, just type your questions like chatting with AI normally.

Want to know all commands? Type /help.

---

📖 Common Operations

💬 Basic Conversation

• Type message directly to send
• Press Ctrl+J or Esc then Enter for newline (depending on your send_key setting)
• Press Esc to interrupt ongoing response

📂 Session Management

/new          Create new session
/history      Manage sessions (switch/rename/delete/search)
/export       Export current session to export/
/import       Import session JSON

🔧 Model Switching

/provider     Manage Providers (add/list/switch/delete)
/model        Manage Models (list/switch)

📎 File Attachments

/attach       Select file to attach to next message
/attach list  View current pending attachments
/attach clear Clear attachments

🎨 Skill System

/skills       Select Skill or toggle auto-selection
/clearskill   Clear current session's Skill
@skill_name   Trigger specific Skill in input

🛠️ Other Useful Commands

/regen        Regenerate last response
/edit [text]  Edit last message and resend
/settings     Modify user settings

---

🎯 Skill System Details

What is a Skill?

A Skill is a preset prompt set designed to make AI play specific roles or focus on specific tasks.

For example:

• @python: Make AI a Python expert
• @translate: Focus on translation tasks
• @review: Code review expert

Directory Structure

Each Skill is a skills/<skill_name>/ directory:

skills/
└── python/
    ├── SKILL.md              # Main prompt
    └── references/
        ├── system.md         # System prompt (optional)
        ├── prompt.md         # Core Prompt (optional)
        └── README.md         # Documentation (optional)

The program reads these files in order and concatenates them to your system_prompt.

Triggering Methods

Manual Trigger: Type @skill_name in input, supports prefix matching:

• @py may match python
• Multiple matches will show a selection list

Auto-Selection: When enabled (/skills auto on), AI automatically selects appropriate Skill based on your question.

---

⚙️ Configuration Files

providers.json

Provider configuration:

Field	Description
name	Provider name for switching
api_key	API key
base_url	API endpoint (optional, for compatible services)
models	Available model list
headers	Custom request headers (optional)
streaming	Enable streaming output

settings.json

User settings:

Field	Description
user_id	Your nickname
active_provider	Current Provider in use
active_model	Current Model in use
send_key	Send method: enter or ctrl_enter
markdown_style	Markdown theme: dark or others
auto_skill	Enable auto Skill selection
system_prompt	Global system prompt

---

🎨 Keyboard Shortcuts

send_key=enter (default)

• Send message: Enter
• Newline: Ctrl+J or Esc then Enter

send_key=ctrl_enter

• Send message: Esc then Enter
• Newline: Enter

💡 Why Esc+Enter? Most terminals cannot distinguish Ctrl+Enter, so Esc+Enter is used instead

Interrupt Request

Press Esc to interrupt ongoing response at any time.

After interruption:

• "Half-finished" responses won't be saved
• Last user message is retained
• Use /regen to retry or /edit to modify and rerun

---

📦 Attachment Details

After selecting files via /attach, attachments are "pending" and submitted with the next user message:

File Type	Processing Method
Images (image/*)	Converted to base64
Text (text/*, JSON, YAML, XML)	Auto-read and inlined (max 200KB per file)
Other binary	Only filename description attached

⚠️ Note: If request is interrupted by Esc, attachments won't auto-restore. To retry, use /regen or re-attach with /attach.

---

💻 Project Structure

nexum/
├── app/          Application orchestration, command dispatch, chat flow
├── cli/          Terminal interaction (input, UI, interruption)
├── llm/          OpenAI client wrapper
├── config/       Config read/write and validation
├── sessions/     Session model and storage
├── skills/       Skill system
└── core/         Common utilities

---

🕸️ Why Nexum?

"The Machine doesn't act directly; it connects people, events, and consequences. Once a connection is made, things naturally happen along that chain." — Tribute to Person of Interest

Nexum in Latin means "a connection or bond that has been established." This project plays exactly that role: it doesn't create intelligence, it just reliably connects your intentions, API calls, and model capabilities.

When the connection is made, the path of action already exists.

---

🛠️ Development/Self-Check

uv sync
uv run python -m compileall nexum

---

🙏 If You Find It Useful

• ⭐ Give a Star — Let more people discover it
• 🐛 Submit Issues — Tell me what can be improved

Thank you 🎉

---

📜 License