Metadata-Version: 2.1
Name: gmode
Version: 1.0.1
Summary: Terminal-first AI coding assistant with workspaces, tools, LSP, MCP, and Telegram control
Keywords: ai,coding-assistant,cli,terminal,tui,lsp,mcp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: textual>=0.80.0

# 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

```bash
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:

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

Useful configuration commands:

```text
/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:

```text
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:

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

### Sessions

```text
/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

```text
/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:

```text
/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:

```text
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:

```text
.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:

```text
~/.gmode-cli/
```

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

## Keyboard shortcuts

```text
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

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

## Build and publish

Install publishing tools:

```bash
python -m pip install --upgrade build twine
```

Build the distributions:

```bash
python -m build
```

Test upload first:

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

Publish to PyPI:

```bash
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.
