☕ CAFFEE Terminal Text Editor

A lightweight, modern, and extensible text editor that runs in your terminal.

PyPI total downloads exceeded 10K! 🎉
PyPI total downloads exceeded 5K! 🎉

🇯🇵 日本語 | Technical Specs (JP) | Plugin Dev (JP) | Nuitka Guide | PATH Setup

Official Japanese UI Plugin | Light version(CAFFEETERIA)

CAFFEE is a terminal text editor written in Python, designed for a simple, extensible, and efficient editing experience with modern IDE-like features.

💡 Features

🎨 Modern UI & Navigation

Multi-Tab Editing - Handle multiple files simultaneously with a visual tab system (Ctrl+S, Ctrl+L, Ctrl+X).
Breadcrumb Bar - Real-time display of file paths and code symbols (functions/classes) for better context.
Vim Mode - Optional modal editing support for high-efficiency navigation and text manipulation.
Relative Line Numbers (Ctrl+U) - Toggle relative line numbers to speed up navigation.
Nerd Font Integration - High-quality icons with an automated font installation helper.
Smart Horizontal Scrolling - Nano-style smooth scrolling for long lines.

🚀 Productivity & Editing

Interactive Search & Replace (Ctrl+W) - VSCode-style interface for finding and replacing text, including "Replace All" (Ctrl+A).
System Clipboard Sync - Seamless copy-paste synchronization across Windows, macOS, and Linux.
Predictive Text - Intelligent auto-completion suggestions powered by buffer content.
Git Integration - View branch names, file status markers (~: modified, +: new), and unified diffs (Ctrl+D).
Enhanced File Explorer (Ctrl+F) - Browse and manage files with sorting, wildcard search, and full-screen mode.
Integrated Terminal (Ctrl+N) - Execute shell commands directly from the editor.
CAFFEINE Macro Language - Automate editor tasks with a dedicated, simple macro language.
Command Mode (Ctrl+P) - Execute powerful commands like :open, :saveas, :set, and :delcomm.

⚙️ Extensibility & Advanced Support

Automated Build & Run (Ctrl+B) - Optimized templates and build commands for 20+ programming languages.
Advanced Syntax Highlighting - Support for Python, JS/TS, C/C++, Go, Rust, Java, Ruby, Swift, and more.
Plugin System - Extend functionality with custom Python scripts.
Atomic File Saving - Safe file operations with automatic backup creation.
Undo/Redo - Comprehensive history management with configurable limits.

💻 Installation

Requirements

Python 3.8+
Unix-like terminal (Linux, macOS, ChromeOS Linux shell)
curses library (usually included with Python)

Quick Start

# Install from PyPI
pip install caffee

# Run the editor
caffee

# Or open a specific file
caffee /path/to/file.py

Upgrade

pip install caffee --upgrade

Optional: Speed Up with Nuitka

For significantly faster startup, compile with Nuitka. See the Nuitka Compilation Guide for detailed instructions.

⌨️ Keybindings

File Operations

Key	Action
`Ctrl+O`	Save current file
`Ctrl+X`	Close current tab / Exit
`Ctrl+S`	New tab / Start screen
`Ctrl+L`	Switch to next tab

Editing

Key	Action
`Ctrl+Z`	Undo
`Ctrl+R`	Redo
`Ctrl+K`	Cut (line or selection)
`Ctrl+V`	Paste (System Clipboard Sync)
`Ctrl+C`	Copy selection
`Ctrl+U`	Toggle relative line numbers
`Ctrl+Y`	Delete current line
`Ctrl+/`	Toggle comment

Navigation & Search

Key	Action
`Ctrl+W`	Search (with regex support)
`Ctrl+G`	Go to line number
`Ctrl+Q`	Move to beginning of line
`Ctrl+E`	Move to end of line
`Ctrl+A`	Select all / Clear selection
`Ctrl+6`	Set/Unset mark (selection start)

Panels & Tools

Key	Action
`Ctrl+F`	Toggle file explorer
`Ctrl+N`	Toggle integrated terminal
`Ctrl+U`	Toggle relative line numbers
`Ctrl+T`	Insert template
`Ctrl+B`	Build/Run current file
`Ctrl+D`	Show Git diff for the current file
`Ctrl+P`	Enter Command Mode (or Open Plugin Manager on Start Screen)
`Esc`	Return to editor from panels

🚀 Command Mode

Press Ctrl+P to enter Command Mode, then type a command and press Enter.

Command	Alias	Description
`open <file>`	`o <file>`	Open a file in a new tab.
`save`	`w`	Save the current file.
`saveas <file>`		Save the current file with a new name.
`copy`		Copy the selected range to the system clipboard.
`paste`		Paste content from the system clipboard.
`close`	`q`	Close the current tab.
`quit`	`qa`	Exit the editor (prompts for unsaved files).
`new`		Create a new empty tab.
`set <key> <val>`		Change a setting (e.g., `set tab_width 2`).
`undo`		Undo the last action.
`redo`		Redo the last undone action.
`goto <line>`		Jump to the specified line number.
`next`	`tabn`	Switch to the next tab.
`prev`	`tabp`	Switch to the previous tab.
`find <query>`		Search for the specified query.
`replace <old> <new>`		Replace occurrences of `<old>` with `<new>`.
`expw <width>`	`explorer_width`	Set the file explorer width.
`termh <height>`	`terminal_height`	Set the integrated terminal height.
`diff`		Show a Git diff of the current file in a new tab.
`delcomm`		Remove all comments from the current buffer.
`template <lang>`		Insert a template for the specified language.
`macro <file>`		Execute a CAFFEINE macro file.
`csv`		Show a formatted table preview of the current CSV buffer.
`gemini <prompt>`		Ask Google's Gemini AI a question using the buffer as context.
`openai <prompt>`		Ask OpenAI's ChatGPT a question using the buffer as context.
`claude <prompt>`		Ask Anthropic's Claude AI a question using the buffer as context.

⚙️ Configuration

User settings are stored in ~/.caffee_setting/setting.json. You can edit this file directly or use the interactive settings manager from the start screen (Ctrl+S -> [2] Choice setting).

Example Configuration

{
  "tab_width": 4,
  "history_limit": 50,
  "use_soft_tabs": true,
  "auto_indent": true,
  "backup_count": 5,
  "enable_predictive_text": true,
  
  "templates": {
    "python": "def main():\\n    print(\"Hello, world!\")\\n\\nif __name__ == \"__main__\":\\n    main()",
    "javascript": "function main() {\\n    console.log('Hello, world!');\\n}\\n\\nmain();"
  },

  "start_screen_mode": true,
  "show_explorer_default": true,
  "explorer_show_details": true,
  
  "colors": {
    "header_text": "BLACK",
    "header_bg": "WHITE",
    "keyword": "YELLOW",
    "string": "GREEN",
    "comment": "MAGENTA",
    "number": "BLUE",
    "diff_add": "GREEN",
    "diff_remove": "RED"
  }
}

Key Configuration Options

auto_indent: Enable/disable automatic indentation.
enable_predictive_text: Enable/disable auto-completion suggestions.
explorer_show_details: Show file size and modification date in the explorer.
displayed_keybindings: Customize which keybindings appear in the footer bar.
colors: Comprehensive color customization for all UI elements.

AI Configuration

To use the AI commands (:gemini, :openai, :claude), you must configure your API keys. Create a file named ~/.caffee_setting/ai_api.json with the following format:

{
  "gemini_api_key": "your_google_gemini_api_key",
  "openai_api_key": "your_openai_api_key",
  "claude_api_key": "your_anthropic_claude_api_key"
}

☕ CAFFEINE Macro Language

CAFFEINE is a simple macro language designed specifically for CAFFEE. Macros allow you to automate repetitive tasks by defining a sequence of editor actions.

Macro Syntax

Macros are stored in .caffeine files. Each line can be a command, a cursor movement, or text insertion.

Command	Description
`# comment`	Lines starting with `#` are ignored.
`:command`	Execute any CAFFEE editor command.
`MOVE <y> <x>`	Move the cursor to the specified row and column.
`INSERT "text"`	Insert the specified text at the cursor position.
`TYPE "text"`	Simulate typing text character by character.
`WAIT <ms>`	Pause execution for the specified number of milliseconds.
`COMMAND "cmd"`	Alias for executing an editor command.
`SET <var> <expr>`	Set a variable to the result of an expression.
`IF <expr>`	Conditional block. Starts with `IF`, ends with `ENDIF`.
`ELSE`	Optional block within an `IF` statement.
`LOOP <count>`	Repeat a block of commands for the specified number of times.
`ENDLOOP`	End of a `LOOP` block.

Variable Substitution

You can use variables in your macro commands using the {var_name} syntax. For example, INSERT "Iteration {i}" will insert the current value of variable i. Variables are also automatically substituted in editor commands (lines starting with :).

Advanced Macro Example

# Simple loop with variables and arithmetic
SET i 1
LOOP 5
  INSERT "Line {i}\n"
  SET i i + 1
ENDLOOP

# Conditional logic
SET x 10
IF x > 5
  INSERT "x is greater than 5\n"
ELSE
  INSERT "x is 5 or less\n"
ENDIF

Usage

To run a macro, use the :macro <filename> command in Command Mode (Ctrl+P). CAFFEE will look for the file in the current directory or in ~/.caffee_setting/macros/.

📜 Technical Documentation

For more in-depth technical information and extension guides, please refer to the following documents (currently in Japanese):

Technical Specifications (TECHNICAL_ja.md) - Details on architecture, rendering pipeline, and macro engine.
Plugin Development Guide (PLUGINS_ja.md) - Instructions for creating plugins and API reference.
Nuitka Compilation Guide - Procedures for standalone binary creation and startup acceleration.

🧩 Plugin System

Extend CAFFEE's functionality with custom Python scripts placed in ~/.caffee_setting/plugins/. Use the interactive Plugin Manager (Start Screen -> Ctrl+P) to enable or disable plugins.

Plugin API

Plugins can access the editor's state and functions via an init(editor) entry point, allowing you to:

Bind custom key combinations.
Register new syntax highlighting rules.
Add new build commands.
Manipulate buffers and the cursor.
Display custom messages in the status bar.

🛠️ Troubleshooting

Display Issues: If colors or special characters don't render correctly, ensure your terminal supports 256 colors and UTF-8. For environments like iSH, CAFFEE attempts to set a compatible TERM variable automatically.
File Access: If you encounter errors saving files or creating backups, check the permissions for ~/.caffee_setting/.
Terminal Not Working: The integrated terminal requires pty support (standard on Linux and macOS).

🤝 Contributing / Branching Strategy

Contributions are always welcome! To ensure the stability of the editor and prevent accidental deployments to PyPI, this project uses a standard branching model.

Please do not push directly to the main branch.

main: The stable, release-ready branch. (Tags created here trigger automatic PyPI deployment).
develop: The main development and integration branch. All new features and bug fixes should be merged here first for testing.

How to contribute:

Fork the repository.
Create a new feature branch branching off from develop (e.g., feature/add-new-theme or fix/typo).
Make your changes and commit them.
Push your branch to your forked repository.
Submit a Pull Request (PR) targeting the develop branch of this original repository.

📄 License

This project is licensed under the GNU General Public License v3. See the LICENSE file for details.

Made with ☕ and Python.

Name		Name	Last commit message	Last commit date
Latest commit History 253 Commits
.github/workflows		.github/workflows
docs		docs
.gitignore		.gitignore
LICENSE		LICENSE
Nuitka_Step.md		Nuitka_Step.md
PLUGINS_ja.md		PLUGINS_ja.md
README.md		README.md
Setup_PATH.md		Setup_PATH.md
TECHNICAL_ja.md		TECHNICAL_ja.md
caffee.py		caffee.py
ja-README.md		ja-README.md
preview.png		preview.png
pyproject.toml		pyproject.toml
sample.caffeine		sample.caffeine

Folders and files

Latest commit

History

Repository files navigation

☕ CAFFEE Terminal Text Editor

Table of Contents

💡 Features

🎨 Modern UI & Navigation

🚀 Productivity & Editing

⚙️ Extensibility & Advanced Support

💻 Installation

Requirements

Quick Start

Upgrade

Optional: Speed Up with Nuitka

⌨️ Keybindings

File Operations

Editing

Navigation & Search

Panels & Tools

🚀 Command Mode

⚙️ Configuration

Example Configuration

Key Configuration Options

AI Configuration

☕ CAFFEINE Macro Language

Macro Syntax

Variable Substitution

Advanced Macro Example

Usage

📜 Technical Documentation

🧩 Plugin System

Plugin API

🛠️ Troubleshooting

🤝 Contributing / Branching Strategy

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 40

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages