quick-ai

Overview

quick-ai is a command-line based AI assistant. Users can execute commands in the command line to interact with AI.

Why Choose Me?

Traditional AI chat tools with UI interfaces, such as Cherry Studio, Doubao, etc., generally take a long time to start. Even for a small question, you have to wait a long time to get an answer. With quick-ai, you can get short answers directly in the command line, which is much faster. Additionally, it can work with local large model tools like LMStudio for offline use. Disadvantage: Only suitable for short answers, historical conversations need to be opened using code.

Usage Guide

1. Installation

npm -g i @vtxf/quick-ai

2. Usage

qa <user input>
qa -c <user input>

Feature Introduction

Basic Commands

• qa <user input>: Interact directly with AI in the console
• qa -c <user input>: Continue the conversation with AI based on the previous conversation content
• qa -e: Open editor to view conversation content
• qa -C: Open configuration file
• qa -p: Open system prompt configuration file
• qa -h: Display help information

Cross-platform Support

This tool supports Windows, Linux, and macOS systems.

Configuration Files

Configuration File Location

The configuration file is located at ~/.quick-ai/config.json, where the ~ symbol resolves to the user's home directory on different operating systems:

• Windows: %USERPROFILE%\.quick-ai\config.json
• Linux/macOS: ~/.quick-ai/config.json

System Prompt Configuration File

The system prompt configuration file is located at ~/.quick-ai/system_prompt.md, used to configure the system prompt for AI conversations:

• Windows: %USERPROFILE%\.quick-ai\system_prompt.md
• Linux/macOS: ~/.quick-ai/system_prompt.md

This file defines the behavior and role of the AI assistant. If the file does not exist, the system will automatically create a default system prompt.

Local Large Model Configuration Example

{
    "env": {
        "QUICKAI_OPENAI_BASE_URL": "http://localhost:1234/v1",
        "QUICKAI_OPENAI_API_KEY": "",
        "QUICKAI_OPENAI_MODEL": "qwen/qwen3-4b-2507",
        "QUICKAI_EDITOR": "code -r <QUICKAI_HISTORY_DIR> <QUICKNOTE_HISTORY_FILE_PATH>"
    }
}

Online Large Model Configuration Example

{
    "env": {
        "QUICKAI_OPENAI_BASE_URL": "https://open.bigmodel.cn/api/paas/v4",
        "QUICKAI_OPENAI_API_KEY": "your_glm_api_key",
        "QUICKAI_OPENAI_MODEL": "glm-4.5-flash",
        "QUICKAI_EDITOR": "code -r <QUICKAI_HISTORY_DIR> <QUICKNOTE_HISTORY_FILE_PATH>"
    }
}

Editor Configuration Examples

The QUICKAI_EDITOR environment variable supports various editor configurations, here are some common configuration examples:

"QUICKAI_EDITOR": "notepad <QUICKNOTE_HISTORY_FILE_PATH>"

"QUICKAI_EDITOR": "vim <QUICKNOTE_HISTORY_FILE_PATH>"

"QUICKAI_EDITOR": "code -r <QUICKAI_HISTORY_DIR> <QUICKNOTE_HISTORY_FILE_PATH>"

Users can choose appropriate editor configurations according to their preferences and system environment.

Configuration File Processing Logic

• If the configuration file does not exist, the system will automatically generate a default configuration file
• The system prioritizes reading environment variables from the configuration file
• If a certain environment variable does not exist in the configuration file, it attempts to read from the system environment variables
• QUICKAI_OPENAI_API_KEY can be left unset, as some large models do not require an API key

Environment Variable Description

• QUICKAI_OPENAI_BASE_URL: OpenAI API base URL
• QUICKAI_OPENAI_API_KEY: OpenAI API key (optional)
• QUICKAI_OPENAI_MODEL: Model name to use

Built-in Variables

• QUICKAI_HISTORY_DIR: History record directory, forcibly specified as ~/.quick-ai/history folder
• QUICKNOTE_HISTORY_FILE_PATH: History record file path, format is ~/.quick-ai/history/YYYY/YYYYMM/YYYYMMDD.jsonl, dynamically specified as the current date.

History Management

History File Storage Structure

Conversation history is stored in the ~/.quick-ai/history folder, adopting the following structure:

~/.quick-ai/history/
├── YYYY/                  # Year directory
│   ├── YYYYMM/            # Year-month directory
│   │   ├── YYYYMMDD.jsonl # Date file, one JSON conversation record per line
├── last.json              # JSON file of the most recent conversation

Conversation Record Format

Each conversation record is a JSON object, formatted as follows:

{
    "id": 1698704000000,
    "date": "20251020",
    "messages": [
        {
            "role": "user",
            "content": "Hello"
        },
        {
            "role": "assistant",
            "content": "Hello! How can I help you?"
        }
    ]
}

Field Description

• id: Unique identifier of the conversation, using millisecond-level timestamp
• date: Date when the conversation occurred, format is YYYYMMDD
• messages: Conversation content array, each element contains role (user/assistant) and content fields

Storage Rules

• last.json: Only stores the complete JSON object of the most recent conversation
• YYYYMMDD.jsonl: Stores one conversation JSON object per line (without line breaks, ensuring the entire JSON is on one line)

Detailed Command Description

qa <user input> Command

Execution process:

1. Check if last.json exists and has content
2. If it exists, append the content of last.json to the end of the YYYYMMDD.jsonl file specified by its date attribute
3. After appending, delete the last.json file (to prepare for a new conversation)
4. If it does not exist, skip history processing
5. Start a new conversation
6. Determine if an AI response is obtained
7. If an AI response is obtained, create a new last.json and save the conversation content
8. If no AI response is obtained, print error information to the console, do not create a new last.json file

flowchart TD
    A[Start executing qa command] --> B{Check if last.json exists and has content}
    B -->|Yes| C[Append last.json content to the end of the corresponding date's YYYYMMDD.jsonl file]
    B -->|No| D[Skip history processing]
    C --> E[Delete last.json file]
    D --> F[Start a new conversation]
    E --> F
    F --> G{Is AI response obtained}
    G -->|Yes| H[Create new last.json and save conversation content]
    G -->|No| I[Print error information to console]
    H --> J[End]
    I --> J

Loading

qa -c <user input> Command

Execution process:

1. Check if last.json exists
2. If it exists, read last.json to get the recent conversation content
3. If it does not exist, start as a new conversation
4. If recent conversation content exists, continue interacting with AI based on the recent conversation content
5. Determine if an AI response is obtained
6. If an AI response is obtained, update last.json to save the conversation content (note: this command does not process history files, only updates last.json)
7. If no AI response is obtained, print error information to the console, do not update the last.json file

flowchart TD
    A[Start executing qa -c command] --> B{Check if last.json exists}
    B -->|Yes| C[Read last.json to get recent conversation content]
    B -->|No| D[Start as a new conversation]
    C --> E[Continue interacting with AI based on recent conversation content]
    D --> F{Is AI response obtained}
    E --> F
    F -->|Yes| G[Create or update last.json to save conversation content]
    F -->|No| H[Print error information to console]
    G --> I[End]
    H --> I

Loading

qa -e Command

Execution process:

1. Open editor to view the day's historical conversation file YYYYMMDD.jsonl
2. Set the current directory to ~/.quick-ai/history
3. Get the QUICKAI_EDITOR environment variable
4. Replace placeholders in the environment variable:
   • <QUICKAI_HISTORY_DIR> replaced with ~/.quick-ai/history
   • <QUICKNOTE_HISTORY_FILE_PATH> replaced with the current day's history file path
5. Console should prompt the user: The most recent conversation content is in the last.json file, not in the current day's history file (only previously completed conversations are saved to the history file)
6. Execute the editor command

flowchart TD
    A[Start executing qa -e command] --> B[Set current directory to ~/.quick-ai/history]
    B --> C[Get QUICKAI_EDITOR environment variable]
    C --> D[Replace placeholders in environment variable]
    D --> E[Prompt user that the most recent conversation is in last.json]
    E --> F[Execute editor command to open current day's history file]
    F --> G[End]

Loading

qa -C Command

Execution process:

1. Check if the configuration file directory exists
2. If it does not exist, create the configuration file directory
3. Check if the configuration file exists
4. If it does not exist, create a default configuration file
5. Get the editor command, prioritizing the system default editor
6. Clean placeholders in the editor command
7. Execute the editor command to open the configuration file

flowchart TD
    A[Start executing qa -C command] --> B[Check if configuration file directory exists]
    B -->|No| C[Create configuration file directory]
    B -->|Yes| D[Check if configuration file exists]
    C --> D
    D -->|No| E[Create default configuration file]
    D -->|Yes| F[Get editor command]
    E --> F
    F --> G[Clean placeholders in editor command]
    G --> H[Execute editor command to open configuration file]
    H --> I[End]

Loading

qa -p Command

Execution process:

1. Check if the system prompt directory exists
2. If it does not exist, create the system prompt directory
3. Check if the system prompt file exists
4. If it does not exist, create a default system prompt file
5. Get the editor command, prioritizing the system default editor
6. Clean placeholders in the editor command
7. Execute the editor command to open the system prompt file

flowchart TD
    A[Start executing qa -p command] --> B[Check if system prompt directory exists]
    B -->|No| C[Create system prompt directory]
    B -->|Yes| D[Check if system prompt file exists]
    C --> D
    D -->|No| E[Create default system prompt file]
    D -->|Yes| F[Get editor command]
    E --> F
    F --> G[Clean placeholders in editor command]
    G --> H[Execute editor command to open system prompt file]
    H --> I[End]

Loading

qa -h Command

Execution process:

1. Display help information, including descriptions and usage of all available commands
2. Display configuration file location and environment variable descriptions
3. Display history record storage structure description
4. Display common questions and answers and error handling methods

History Viewing Extension

In addition to the qa -e command, users can also freely view historical conversations through the following methods:

1. Directly open any history file in the ~/.quick-ai/history directory
2. Use any text editor to view YYYYMMDD.jsonl files
3. Use command line tools (such as cat, grep, etc.) to search and filter history records

Error Handling

Configuration File Errors

• If the configuration file does not exist, automatically generate a default configuration file
• If the configuration file format is incorrect, prompt the user and use default configuration

Connection Errors

• If unable to connect to the AI service, prompt the user that the connection was unsuccessful
• Display specific error reasons (such as network issues, API key errors, etc.)
• When connection fails, end the current conversation and save the ongoing interaction to history records

Other Errors

• If the history record directory cannot be created, prompt the user and exit
• If the history record file cannot be written, prompt the user and exit

Technical Implementation Considerations

Cross-platform Compatibility

• Path separators: Windows uses \, Linux/macOS uses /
• Environment variables: Windows uses %VAR% or $env:VAR, Linux/macOS uses $VAR
• Command execution: Consider command differences on different operating systems

Conversation ID Generation

• Use millisecond-level timestamp as conversation ID
• The possibility of multiple conversations occurring within the same millisecond is extremely low, so conflict handling is not considered

API Key Handling

• Prioritize reading API keys from the configuration file
• If it does not exist in the configuration file, read from system environment variables
• If neither exists, some models may not need an API key, continue execution

Performance Considerations

• History record files are split by date to avoid single files being too large

System Prompt Function

• During each AI conversation, the system automatically reads the content of the ~/.quick-ai/system_prompt.md file as the system prompt
• The system prompt defines the role and behavior of the AI assistant.
• Users can edit the system prompt through the qa -p command to customize the function and behavior of the AI assistant
• If the system prompt file does not exist, the system will automatically create a prompt

Notes

• The last.json file is created or updated after each conversation ends, rather than being deleted!
• The system prompt file supports Markdown format and can contain detailed instructions and examples
• After modifying the system prompt, new conversations will immediately use the updated prompt content
• This is a Node.js project, avoid using external libraries unless necessary.