Control your projects via Telegram using Claude CLI, Gemini CLI, or any AI coding agent
DevBridge turns your Telegram into a powerful developer control panel. Chat with AI coding agents (Claude, Gemini) about your codebase, run whitelisted commands, manage multiple projects, receive GitHub/CI notifications -- all from your phone.
- 🤖 AI Chat via Telegram -- Send messages to Claude CLI or Gemini CLI and get responses right in Telegram
- 📂 Multi-Project Support -- Switch between multiple codebases on the fly with
/project - 🔒 Security First -- Chat ID whitelist, command sandbox with whitelist-only execution, configurable AI permission levels (
readonly,read-write,full) - 🔌 Plugin System -- Extend functionality with built-in or custom plugins (Git, GitHub, and more)
- 🏃 Run Commands -- Execute pre-approved shell commands (
/run test,/run build) safely - 💬 Session Management -- Persistent conversation sessions per project with automatic TTL cleanup
- 🔔 Push Notifications -- Receive GitHub webhooks, CI results, and custom alerts via HTTP
- 🧙 Setup Wizard -- Interactive
devbridge initdetects your CLIs and scans for projects - 🖥️ OS Service Manager -- Run as a background service on macOS (launchd) or Linux (systemd)
- 📨 Smart Message Splitting -- Long responses are automatically chunked respecting Telegram's limits
npx devbridge initThe setup wizard will:
- Detect installed AI CLIs (Claude CLI, Gemini CLI)
- Ask for your Telegram bot token (get one from @BotFather)
- Ask for your Telegram Chat ID (get it from @userinfobot)
- Scan your filesystem for projects
devbridge startOpen your Telegram bot and start chatting! Any text message is forwarded to the AI agent working in your active project's directory.
DevBridge is configured via devbridge.config.json in your working directory. Run devbridge init to generate it interactively, or copy from devbridge.config.example.json.
See docs/configuration.md for detailed documentation of every option.
| Command | Description |
|---|---|
/help |
Show all available commands |
/projects |
List all configured projects with status |
/project <name> |
Switch the active project |
/sessions |
List all active AI sessions |
/switch <name> |
Switch to a different project's session |
/status |
Show current session info (adapter, model, message count) |
/clear |
Clear the current session and start fresh |
/run <alias> |
Execute a whitelisted command (e.g., /run test) |
/plugins |
List loaded plugins and their commands |
| Command | Description |
|---|---|
/notifications |
Show current notification status |
/notifications on |
Enable push notifications |
/notifications off |
Disable push notifications |
/mute <minutes> |
Temporarily silence notifications |
Git Plugin (@devbridge/plugin-git):
| Command | Description |
|---|---|
/git status |
Show working directory status with summary |
/git log [N] |
Show last N commits (default: 10, max: 50) |
/git diff [--full] |
Show diff stats, or full diff with --full |
/git branch |
List all branches sorted by last commit |
/git branch current |
Show the current branch name |
GitHub Plugin (@devbridge/plugin-github):
| Command | Description |
|---|---|
/pr list |
List the 10 most recent open pull requests |
/pr view <number> |
View details of a specific PR |
/issue list |
List the 10 most recent open issues |
/issue view <number> |
View details of a specific issue |
Any message that is not a command is sent to the AI agent (Claude or Gemini) as a conversation prompt. The AI operates within your active project's directory. The tools available to the AI depend on the project's permission_level: readonly (default) restricts the AI to reading files, read-write allows file creation and editing, and full grants shell and network access. See docs/security.md for details.
DevBridge supports plugins to extend its functionality. Plugins can register new Telegram /commands and hook into the bot lifecycle.
Add the plugin name to the plugins section of your config:
{
"plugins": {
"@devbridge/plugin-git": true,
"@devbridge/plugin-github": true,
"/path/to/local/plugin": true,
"npm-package-name": { "option": "value" }
}
}Plugins are loaded from three sources (in order):
- Built-in -- shipped in the
plugins/directory (e.g.,@devbridge/plugin-git) - Local path -- absolute path to a plugin directory
- npm package -- installed via
npm installoryarn add
Set a plugin to false to disable it without removing the config entry.
Pass a config object instead of true to provide plugin-specific options.
See docs/plugins.md for a full tutorial.
A minimal plugin:
import type { DevBridgePlugin, PluginContext, CommandContext } from 'devbridge/plugins/types';
const plugin: DevBridgePlugin = {
name: 'my-plugin',
version: '1.0.0',
description: 'My custom plugin',
commands: [
{
name: 'hello',
description: 'Say hello',
async handler(ctx: CommandContext) {
await ctx.reply(`Hello from ${ctx.project.name}!`);
},
},
],
async onLoad(context: PluginContext) {
context.logger.info('My plugin loaded!');
},
async onUnload() {},
};
export default plugin;DevBridge is designed with multiple layers of security:
-
Chat ID Whitelist -- Only Telegram users listed in
allowed_userscan interact with the bot. Unauthorized messages are silently dropped. -
Command Sandbox -- The
/runcommand only executes commands explicitly listed in thecommandsconfig. Commands are spawned withoutshell: trueto prevent injection attacks. -
Configurable AI Permission Levels -- Each project has a
permission_level(readonly,read-write, orfull) that controls which tools the AI can use. The defaultreadonlylevel restricts the AI to read-only tools (Read,Glob,Grep), preventing file modifications. Higher levels grant write or full access as needed. -
Webhook Signature Verification -- GitHub webhooks are verified using HMAC-SHA256 signatures when a
secretis configured. -
Rate Limiting -- The notification HTTP server enforces per-IP rate limits to prevent abuse.
-
Local Bind -- The notification server binds to
127.0.0.1by default, preventing external access unless explicitly configured.
See docs/security.md for a detailed breakdown.
devbridge init -- Interactive setup wizard
devbridge start -- Start the bot in foreground
devbridge stop -- Stop the background service
devbridge logs -- Show recent logs (-f to follow)
devbridge status -- Show service status
When notifications.enabled is true, DevBridge starts an HTTP server that accepts:
| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Health check (returns { status: "ok" }) |
/notify |
POST | Send a generic notification |
/webhook/github |
POST | Receive GitHub webhook events |
/webhook/ci |
POST | Receive CI pipeline results |
curl -X POST http://localhost:9876/notify \
-H "Content-Type: application/json" \
-d '{"title": "Deploy complete", "message": "v2.1.0 deployed to production", "level": "success"}'Configure your GitHub repository webhook to point to http://your-server:9876/webhook/github with content type application/json and your shared secret.
curl -X POST http://localhost:9876/webhook/ci \
-H "Content-Type: application/json" \
-d '{"status": "success", "pipeline": "build-and-test", "project": "my-app", "duration": "2m 34s"}'Q: Which AI CLIs are supported?
A: Claude CLI and Gemini CLI are supported out of the box. DevBridge uses an adapter system, so new CLIs can be added by implementing the CLIAdapter interface. See docs/adapters.md.
Q: Can the AI modify my files?
A: By default, no. Both adapters use a permission_level system that defaults to readonly, restricting the AI to read-only tools. Set permission_level to "read-write" to allow file creation and editing, or "full" for complete access including shell commands. See docs/security.md for details.
Q: Is it safe to expose the notification server to the internet?
A: The server binds to 127.0.0.1 by default. If you need external access (e.g., for GitHub webhooks), use a reverse proxy with HTTPS, configure a webhook secret for HMAC verification, and consider firewall rules. Rate limiting is built in.
Q: Can multiple people use the same bot?
A: Yes. Add multiple chat IDs to allowed_users. Each user has independent project selection and session state.
Q: What happens when the AI session gets corrupted?
A: Use /clear to reset the session. DevBridge automatically detects corrupted sessions and clears them when errors are reported by the CLI.
Q: How do sessions persist across restarts?
A: Sessions are saved to ~/.devbridge/sessions.json and restored on startup. Expired sessions (older than session_ttl_hours) are automatically cleaned up.
Q: Can I use this with other AI CLIs (Codex, Aider, etc.)?
A: Yes! Implement the CLIAdapter interface and register your adapter in the AdapterRegistry. See docs/adapters.md for a guide.
Q: What languages/frameworks does the project scanner detect?
A: The setup wizard detects Node.js (package.json), Python (pyproject.toml, requirements.txt), Go (go.mod), Rust (Cargo.toml), Java (pom.xml, build.gradle), Ruby (Gemfile), and PHP (composer.json).
Q: Where are logs stored?
A: Logs are written to ~/.devbridge/logs/devbridge.log. Use devbridge logs to view them or devbridge logs -f to follow in real-time.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
MIT -- Vinicius Machado
{ // REQUIRED: Telegram bot credentials "telegram": { "bot_token": "123456:ABC-DEF...", // From @BotFather "allowed_users": ["123456789"] // Your Telegram chat ID(s) }, // REQUIRED: One or more projects "projects": { "my-app": { "path": "/absolute/path/to/project", // Absolute path to project root "adapter": "claude", // "claude" or "gemini" "model": "sonnet", // Optional: model override "description": "My main app", // Optional: shown in /projects "permission_level": "read-write" // Optional: "readonly" (default), "read-write", or "full" }, "api-backend": { "path": "/absolute/path/to/api", "adapter": "gemini", "description": "Backend API" // permission_level defaults to "readonly" } }, // OPTIONAL: Whitelisted shell commands for /run "commands": { "test": "yarn test", "lint": "yarn lint", "build": "yarn build", "status": "git status --short", "log": "git log --oneline -10" }, // OPTIONAL: Plugins to load "plugins": { "@devbridge/plugin-git": true, "@devbridge/plugin-github": true }, // OPTIONAL: Default settings "defaults": { "adapter": "claude", // Default adapter for new projects "model": "sonnet", // Default model (adapter-specific) "timeout": 120, // AI response timeout in seconds (non-streaming) "stream_timeout": 3600, // Hard max seconds for streaming responses (1 hour) "inactivity_timeout": 300, // Kill streaming process after N seconds of no output "max_message_length": 4096, // Telegram message chunk size "session_ttl_hours": 24, // Auto-cleanup inactive sessions "command_timeout": 60 // /run command timeout in seconds }, // OPTIONAL: Push notification server "notifications": { "enabled": true, "port": 9876, // HTTP server port "bind": "127.0.0.1", // Bind address (default: 127.0.0.1) "secret": "your-webhook-secret", // GitHub webhook secret for HMAC verification "github_events": [ // GitHub event types to forward "push", "pull_request", "issues", "workflow_run" ], "watched_branches": [ // Only notify pushes to these branches "main", "master", "develop" ], "rate_limit": { "max_per_minute": 30, // Max notifications per IP per minute "cooldown_seconds": 5 // Min seconds between notifications } } }