Metadata-Version: 2.4
Name: vibex-code
Version: 0.1.0
Summary: Vibe Coding Agent Platform with Web UI and Channel Interfaces
Project-URL: Homepage, https://github.com/six-ddc/vibex
Project-URL: Repository, https://github.com/six-ddc/vibex
Project-URL: Bug Tracker, https://github.com/six-ddc/vibex/issues
Author: six-ddc
License: MIT
License-File: LICENSE
Keywords: ai,claude,codex,coding-assistant,gemini,mcp,telegram,tmux,vibe-coding
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: aiofiles>=24.0.0
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: croniter>=6.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.21.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-telegram-bot[rate-limiter,webhooks]>=21.0
Requires-Dist: reportlab>=4.4.10
Requires-Dist: telegramify-markdown>=0.5.0
Requires-Dist: weasyprint>=68.1
Provides-Extra: dev
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: faster-whisper>=1.2.1; extra == 'gpu'
Requires-Dist: nvidia-cublas-cu12>=12.3; extra == 'gpu'
Requires-Dist: nvidia-cudnn-cu12>=9.0; extra == 'gpu'
Provides-Extra: stt
Requires-Dist: faster-whisper>=1.2.1; extra == 'stt'
Provides-Extra: web
Requires-Dist: fastapi>=0.115.0; extra == 'web'
Requires-Dist: pydantic>=2.10.0; extra == 'web'
Requires-Dist: sse-starlette>=2.1.3; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.34.0; extra == 'web'
Description-Content-Type: text/markdown

# Vibex

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/six-ddc/vibex/actions/workflows/ci.yml/badge.svg)](https://github.com/six-ddc/vibex/actions/workflows/ci.yml)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

**Vibe Coding Agent Platform** — Bridge Claude Code and other AI agents to Telegram and Web UI. Monitor, interact, and manage AI coding sessions running in tmux.

https://github.com/user-attachments/assets/15ffb38e-5eb9-4720-93b9-412e4961dc93

## Why Vibex?

Claude Code runs in your terminal. When you step away from your computer — commuting, on the couch, or just away from your desk — the session keeps working, but you lose visibility and control.

Vibex solves this by letting you **seamlessly continue the same session from Telegram and Web UI**. The key insight is that it operates on **tmux**, not the Claude Code SDK. Your Claude Code process stays exactly where it is, in a tmux window on your machine. Vibex simply reads its output and sends keystrokes to it. This means:

- **Switch from desktop to phone mid-conversation** — Claude is working on a refactor? Walk away, keep monitoring and responding from Telegram.
- **Switch back to desktop anytime** — Since the tmux session was never interrupted, just `tmux attach` and you're back in the terminal with full scrollback and context.
- **Run multiple sessions in parallel** — Each Telegram topic maps to a separate tmux window, so you can juggle multiple projects from one chat group.

Other Telegram bots for Claude Code typically wrap the Claude Code SDK to create separate API sessions. Those sessions are isolated — you can't resume them in your terminal. Vibex takes a different approach: it's just a thin control layer over tmux, so the terminal remains the source of truth and you never lose the ability to switch back.

In fact, Vibex itself was built this way — iterating on itself through Claude Code sessions monitored and driven from Telegram via Vibex.

## Features

- **Topic-based sessions** — Each Telegram topic maps 1:1 to a tmux window and Claude session
- **Real-time notifications** — Get Telegram messages for assistant responses, thinking content, tool use/result, and local command output
- **Interactive UI** — Navigate AskUserQuestion, ExitPlanMode, and Permission Prompts via inline keyboard
- **Send messages** — Forward text to Claude Code via tmux keystrokes
- **Slash command forwarding** — Send any `/command` directly to Claude Code (e.g. `/clear`, `/compact`, `/cost`)
- **Create new sessions** — Start Claude Code sessions from Telegram via directory browser
- **Kill sessions** — Close a topic to auto-kill the associated tmux window
- **Message history** — Browse conversation history with pagination (newest first)
- **Hook-based session tracking** — Auto-associates tmux windows with Claude sessions via `SessionStart` hook
- **Persistent state** — Thread bindings and read offsets survive restarts
- **Built-in MCP Server Support** — `vibex-agent` MCP server enabled by default for orchestrating background agent tasks
- **MCP Server Management** — Enable/disable MCP servers globally or per-conversation in the web UI
- **Multi-backend support** — Claude Code, OpenAI Codex, and Google Gemini with unified MCP interfaces
- **Web UI** — Browser-based chat interface for modern workflow integration

## Prerequisites

- **tmux** — must be installed and available in PATH
- **Claude Code** — the CLI tool (`claude`) must be installed

## Installation

### Option 1: Install from GitHub (Recommended)

```bash
# Using uv (recommended)
uv tool install git+https://github.com/six-ddc/vibex.git

# Or using pipx
pipx install git+https://github.com/six-ddc/vibex.git
```

### Option 2: Install from source

```bash
git clone https://github.com/six-ddc/vibex.git
cd vibex
uv sync
```

## Configuration

**1. Create a Telegram bot and enable Threaded Mode:**

1. Chat with [@BotFather](https://t.me/BotFather) to create a new bot and get your bot token
2. Open @BotFather's profile page, tap **Open App** to launch the mini app
3. Select your bot, then go to **Settings** > **Bot Settings**
4. Enable **Threaded Mode**

**2. Configure environment variables:**

Create `~/.vibex/.env`:

```ini
TELEGRAM_BOT_TOKEN=your_bot_token_here
ALLOWED_USERS=your_telegram_user_id
```

**Required:**

| Variable             | Description                       |
| -------------------- | --------------------------------- |
| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather         |
| `ALLOWED_USERS`      | Comma-separated Telegram user IDs |

**Optional:**

| Variable                | Default    | Description                                      |
| ----------------------- | ---------- | ------------------------------------------------ |
| `VIBEX_DIR`             | `~/.vibex` | Config/state directory (`.env` loaded from here) |
| `TMUX_SESSION_NAME`     | `vibex`    | Tmux session name                                |
| `CLAUDE_COMMAND`        | `claude`   | Command to run in new windows                    |
| `MONITOR_POLL_INTERVAL` | `2.0`      | Polling interval in seconds                      |

> If running on a VPS where there's no interactive terminal to approve permissions, consider:
>
> ```
> CLAUDE_COMMAND=IS_SANDBOX=1 claude --dangerously-skip-permissions
> ```

## Hook Setup (Recommended)

Auto-install via CLI:

```bash
vibex hook --install
```

Or manually add to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "vibex hook", "timeout": 5 }]
      }
    ]
  }
}
```

This writes window-session mappings to `$VIBEX_DIR/session_map.json` (`~/.vibex/` by default), so the bot automatically tracks which Claude session is running in each tmux window — even after `/clear` or session restarts.

## Usage

```bash
# If installed via uv tool / pipx
vibex

# If installed from source
uv run vibex
```

### Commands

**Bot commands:**

| Command       | Description                     |
| ------------- | ------------------------------- |
| `/start`      | Show welcome message            |
| `/history`    | Message history for this topic  |
| `/screenshot` | Capture terminal screenshot     |
| `/esc`        | Send Escape to interrupt Claude |

**Claude Code commands (forwarded via tmux):**

| Command    | Description                  |
| ---------- | ---------------------------- |
| `/clear`   | Clear conversation history   |
| `/compact` | Compact conversation context |
| `/cost`    | Show token/cost usage        |
| `/help`    | Show Claude Code help        |
| `/memory`  | Edit CLAUDE.md               |

Any unrecognized `/command` is also forwarded to Claude Code as-is (e.g. `/review`, `/doctor`, `/init`).

### Topic Workflow

**1 Topic = 1 Window = 1 Session.** The bot runs in Telegram Forum (topics) mode.

**Creating a new session:**

1. Create a new topic in the Telegram group
2. Send any message in the topic
3. A directory browser appears — select the project directory
4. A tmux window is created, `claude` starts, and your pending message is forwarded

**Sending messages:**

Once a topic is bound to a session, just send text in that topic — it gets forwarded to Claude Code via tmux keystrokes.

**Killing a session:**

Close (or delete) the topic in Telegram. The associated tmux window is automatically killed and the binding is removed.

### Message History

Navigate with inline buttons:

```
📋 [project-name] Messages (42 total)

───── 14:32 ─────

👤 fix the login bug

───── 14:33 ─────

I'll look into the login bug...

[◀ Older]    [2/9]    [Newer ▶]
```

### Notifications

The monitor polls session JSONL files every 2 seconds and sends notifications for:

- **Assistant responses** — Claude's text replies
- **Thinking content** — Shown as expandable blockquotes
- **Tool use/result** — Summarized with stats (e.g. "Read 42 lines", "Found 5 matches")
- **Local command output** — stdout from commands like `git status`, prefixed with `❯ command_name`

Notifications are delivered to the topic bound to the session's window.

## Running Claude Code in tmux

### Option 1: Create via Telegram (Recommended)

1. Create a new topic in the Telegram group
2. Send any message
3. Select the project directory from the browser

### Option 2: Create Manually

```bash
tmux attach -t vibex
tmux new-window -n myproject -c ~/Code/myproject
# Then start Claude Code in the new window
claude
```

The window must be in the `vibex` tmux session (configurable via `TMUX_SESSION_NAME`). The hook will automatically register it in `session_map.json` when Claude starts.

## Data Storage

| Path                            | Description                                                             |
| ------------------------------- | ----------------------------------------------------------------------- |
| `$VIBEX_DIR/state.json`         | Thread bindings, window states, display names, and per-user read offsets |
| `$VIBEX_DIR/session_map.json`   | Hook-generated `{tmux_session:window_id: {session_id, cwd, window_name}}` mappings |
| `$VIBEX_DIR/monitor_state.json` | Monitor byte offsets per session (prevents duplicate notifications)     |
| `~/.claude/projects/`           | Claude Code session data (read-only)                                    |

## File Structure

```
src/vibex/
├── __init__.py            # Package entry point
├── main.py                # CLI dispatcher (hook subcommand + bot bootstrap)
├── hook.py                # Hook subcommand for session tracking (+ --install)
├── config.py              # Configuration from environment variables
├── bot.py                 # Telegram bot setup, command handlers, topic routing
├── session.py             # Session management, state persistence, message history
├── session_monitor.py     # JSONL file monitoring (polling + change detection)
├── monitor_state.py       # Monitor state persistence (byte offsets)
├── transcript_parser.py   # Claude Code JSONL transcript parsing
├── terminal_parser.py     # Terminal pane parsing (interactive UI + status line)
├── markdown_v2.py         # Markdown → Telegram MarkdownV2 conversion
├── telegram_sender.py     # Message splitting + synchronous HTTP send
├── screenshot.py          # Terminal text → PNG image with ANSI color support
├── utils.py               # Shared utilities (atomic JSON writes, JSONL helpers)
├── tmux_manager.py        # Tmux window management (list, create, send keys, kill)
├── fonts/                 # Bundled fonts for screenshot rendering
└── handlers/
    ├── __init__.py        # Handler module exports
    ├── callback_data.py   # Callback data constants (CB_* prefixes)
    ├── directory_browser.py # Directory browser inline keyboard UI
    ├── history.py         # Message history pagination
    ├── interactive_ui.py  # Interactive UI handling (AskUser, ExitPlan, Permissions)
    ├── message_queue.py   # Per-user message queue + worker (merge, rate limit)
    ├── message_sender.py  # safe_reply / safe_edit / safe_send helpers
    ├── response_builder.py # Response message building (format tool_use, thinking, etc.)
    └── status_polling.py  # Terminal status line polling
```

## Troubleshooting

**Bot not receiving Telegram messages**
- Verify `TELEGRAM_BOT_TOKEN` is correct
- If using webhook mode, ensure the tunnel URL is reachable and `WEBHOOK_SECRET` is set
- Check that your Telegram user ID is in `ALLOWED_USERS`

**Claude auth expired / session fails to start**
- Re-run `claude` on the host to refresh credentials, then copy to `~/.vibex/claude/.credentials.json`
- Check logs for `401` or `refresh_token` errors

**tmux session not found**
- Ensure `tmux` is installed and in PATH
- Check `TMUX_SESSION_NAME` matches between config and running tmux server
- Run `tmux ls` to verify the session exists

**Codex `refresh_token_reused` errors**
- Codex uses one-time-use refresh tokens. If you used `codex` locally, re-copy the auth file:
  ```bash
  cp ~/.codex/auth.json ~/.vibex/codex/auth.json
  ```

**MCP server not connecting**
- Verify `MCP_HTTP_ENABLED=true` and `MCP_TOKEN` are set in `~/.vibex/.env`
- Test connectivity: `POST /api/mcp-servers/{name}/test` via the web API

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code quality requirements, and PR process.

## License

[MIT](LICENSE)
