gmode 1.0.1

Terminal-first AI coding assistant with workspaces, tools, LSP, MCP, and Telegram control

GMODE CLI

GMODE is a terminal-first AI coding assistant for project work. It provides a modern Textual terminal UI, streaming Markdown responses, tool execution, workspace/session persistence, MCP servers, LSP navigation, and optional Telegram control.

Install

pip install gmode
gmode

The package also provides the compatibility command myagent and the optional standalone gmode-telegram entry point. The normal GMODE application starts the Telegram bridge itself, so the standalone command is not required.

First setup

Set an OpenAI-compatible API key, or configure it from the CLI:

$env:GMODE_API_KEY = "your-api-key"
gmode

Useful configuration commands:

/provider ollama
/provider openai
/model gpt-4o
/set api_key YOUR_KEY
/config

GMODE works with OpenAI-compatible providers through base_url, model, and api_key configuration.

Main features

Conversation UI

• Persistent user, assistant, tool, and error history.
• Markdown headings, lists, tables, links, block quotes, and code blocks.
• Streaming responses without replacing previous messages.
• PageUp/PageDown, Home/End, arrow keys, and mouse-wheel scrollback.
• Suggestions for / commands and @ file attachments.

Tools and approvals

The agent can read files, write files, edit files, list directories, search files, and run commands. Changes show an inline Before/After preview.

Approval choices are keyboard-based:

y  allow once
a  allow for this session
n  reject

When Telegram is connected, the same approval request is also sent there.

Workspaces

Workspaces isolate configuration, personas, sessions, and conversation data:

/workspace list
/workspace create my-project
/workspace switch my-project
/workspace config
/workspace rename new-name
/workspace delete old-name

Sessions

/session
/session list
/session new feature-work
/session continue SESSION_ID
/session current
/clear
/history
/open SESSION_ID
/export conversation.md
/import conversation.json

Typing /session opens a picker with the five newest sessions and a New session option.

MCP servers

Use /mcp to open the MCP server picker. It supports multiple saved servers:

1. Add custom MCP URL
2. Select an existing MCP server

The selected MCP server is used when calling MCP with #request.

LSP code intelligence

/lsp enable [file]
/lsp status
/lsp diagnostics file.py
/lsp hover file.py 10 5
/lsp goto-definition file.py 10 5
/lsp references file.py 10 5
/lsp disable

Supported server types include Python/pyright, JavaScript and TypeScript, Go/gopls, Rust/rust-analyzer, and Java/jdtls. Install the language server you want separately; GMODE does not bundle those executables.

Telegram multi-project control

Run GMODE in each project. Each running project registers itself. Connect from any GMODE terminal:

/connect

Choose Telegram, paste the BotFather token, send /start to the bot, and enter the verification code sent by Telegram. WhatsApp and Mail are currently shown as future connection options.

After connection, Telegram shows the active projects as buttons. Select a project and send a task. The selected project executes it, sends approval requests when needed, and sends the final response or error back to Telegram.

Telegram approval buttons are:

Allow
Allow for this session
No

The first GMODE process hosts the Telegram poller in the background. Other project terminals only register themselves and process their own local jobs.

Local data and persistence

Each project automatically receives:

.gmode/
├── .gitignore
├── gmode.db
└── logs/
    └── gmode.log

The project database stores sessions, messages, tool events, file access, Telegram jobs, and Telegram approvals.

Global configuration and workspace databases are stored under:

~/.gmode-cli/

Do not commit .gmode/ or API tokens to source control.

Keyboard shortcuts

Enter          Send message
Ctrl+Enter     Insert newline
Ctrl+L         Clear input only
Ctrl+C         Exit/cancel
Ctrl+D         Exit
Ctrl+K         Session history
Ctrl+O         Open latest session
PageUp/Down    Scroll conversation
Home/End       Conversation top/bottom
F1 or ?        Help

Development

pip install -e .
python -m compileall -q gmode_cli
pytest -q

Build and publish

Install publishing tools:

python -m pip install --upgrade build twine

Build the distributions:

python -m build

Test upload first:

python -m twine upload --repository testpypi dist/*

Publish to PyPI:

python -m twine upload dist/*

Use a PyPI API token through Twine environment variables or its prompt. Never place the token in README.md, pyproject.toml, source code, or Git history.