VerifiedPlugin
Development
alexei-led-cc-thingz
Portable skills, agents, hooks, and Pi-native extensions for Claude Code, Codex CLI, GitHub Copilot, Cursor, Grok, and Pi. Gemini is retired.
198 skills
@alexei-ledDevelopment
Plugin
ccgram
Control AI coding agents from your phone. Walk away mid-session. Keep monitoring and responding from Telegram—without losing terminal access.
Plugin Signal67/100Solid
maintained99
capable14
documented100
adopted51
Install
$ npx -y skills add alexei-led/ccgram --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
240
Stars
72
Forks
Active
Maintenance
Python
Language
MIT
License
1d ago
Last commit
6mo ago
Created
Repo: alexei-led/ccgram
What's inside
Badges
3
README
1CCGram — Control AI Coding Agents from Telegram
Control AI coding agents from your phone. Walk away mid-session. Keep monitoring and responding from Telegram—without losing terminal access.
Why CCGram?
AI coding agents run in your terminal. Other Telegram bots wrap agent SDKs into isolated API sessions you can't resume in your terminal. CCGram is different. It sits on top of your terminal multiplexer (tmux or herdr), not any agent SDK. Your agent process stays exactly where it is—your session is the source of truth.
This means:
- Desktop to phone, mid-conversation — walk away and keep monitoring from Telegram
- Phone back to desktop, anytime — attach to your terminal and you're back with full scrollback
- Multiple sessions in parallel — each Telegram topic maps to a separate tmux window or guarded Herdr agent session
How It Works
graph LR
subgraph phone["📱 Telegram Group (Forum Topics)"]
direction TB
T1["💬 api — Claude"]
T2["💬 ui — Codex"]
T3["💬 data — Gemini"]
T4["💬 ops — Shell"]
T5["💬 lab — Pi"]
end
subgraph bridge["⚡ CCGram"]
direction TB
B1["read output\n(transcripts + terminal)"]
B2["send keystrokes\n(tmux / herdr)"]
B3["instant notifications\n(Claude hooks)"]
end
subgraph machine["🖥️ Your Machine — tmux / herdr"]
direction TB
W1["window @0 · claude"]
W2["window @1 · codex"]
W3["window @2 · gemini"]
W4["window @3 · bash"]
W5["window @4 · pi"]
end
phone -- "messages / voice" --> bridge
bridge -- "responses / live view" --> phone
bridge <--> machine
style phone fill:#e8f4fd,stroke:#0088cc,stroke-width:2px,color:#333
style bridge fill:#fff8e1,stroke:#f9a825,stroke-width:2px,color:#333
style machine fill:#f0faf0,stroke:#2ea44f,stroke-width:2px,color:#333
Each Telegram topic maps to one tmux window. With Herdr, it maps instead to one guarded agent session: agent.list is the sole identity source and CCGram persists only an opaque herdr-session-v1-… target, never a tab or pane ID. Every action reads a fresh agent.list record and fails closed for missing, duplicate, malformed, sessionless, or legacy bindings. A session can still change after that guard and before Herdr dispatches, so delivery is not atomic and may be indeterminate after this post-guard race.
What You Can Do
- Bind agents to topics — one agent per Telegram topic; create via directory browser
- Auto-detect providers — Supports Claude Code, Codex, Gemini, Pi, and Shell simultaneously
- Monitor live — Terminal screenshots on demand or auto-refresh every 5 seconds
- Send commands — Slash commands, voice messages (transcribed via Whisper), or raw shell input
- Run multiple agents in parallel — each topic independent; run different agents at once
- Recover gracefully — Resume, continue, or start fresh if a session crashes
- Send workspace files — Share files to Telegram via
/send(glob, path, or substring search) - Action toolbar — Provider-specific buttons for common actions (Screenshot, Mode, Esc, Enter, etc.)
Quick Start
Install:
uv tool install ccgram # recommended
# or: pipx install ccgram | brew install alexei-led/tap/ccgram
Telegram setup:
- Create a bot via @BotFather — full instructions
- Add bot to a Telegram group with Topics enabled; promote to Admin
- Create
~/.ccgram/.env:
TELEGRAM_BOT_TOKEN=your_bot_token_here
ALLOWED_USERS=your_telegram_user_id
CCGRAM_GROUP_ID=your_telegram_group_id
Get user ID from @userinfobot. Get group ID via @RawDataBot (prefix Peer ID with -100).
Run:
ccgram
Open your Telegram group, create a topic, send a message — directory browser appears. Pick a project directory, choose your agent (Claude, Codex, Gemini, Pi, or Shell), and you're connected.
Prerequisites: Python 3.14+, tmux or herdr, and one agent CLI. CCGram does not modify agent SDKs.
Herdr setup
CCGram supports Herdr socket protocols 14–17 and 19. Install Herdr's integration before launching an agent that needs a native session identity:
herdr integration install pi
herdr integration install antigravity-cli
Restart an already-running agent after installation. Antigravity receives a native Herdr session identity after its first prompt creates a conversation.
Start new agents, or restart already-running agents, after installing the integration so they publish their agent_session identity. Then set CCGRAM_MULTIPLEXER=herdr and run ccgram hook --install as usual.
Platform Support
CCGram supports Linux, macOS, and WSL2. Native Windows is not supported.
On Windows, install and run CCGram inside WSL2. Install tmux or herdr and the agent CLI inside the WSL distribution.
Native Windows does not provide the Unix file locking, signal handling, and terminal multiplexer features that CCGram requires.
Documentation
- Guides — CLI reference, configuration, voice transcription, multi-instance setup, session recovery, testing
- Providers — Claude Code, Codex, Gemini, Pi, Shell; session modes, LLM config, custom commands, git worktrees
Optional Features
Web Dashboard — Live terminal (xterm.js), transcript search, multi-pane grid in Telegram. Disabled by default. Enable here.
Development
git clone https://github.com/alexei-led/ccgram.git && cd ccgram
uv sync --extra dev
make check # lint, format, typecheck, test
make test-e2e # end-to-end tests (requires agent CLIs; see docs/guides.md#e2e-tests)
License
File tree
527alexei-led/ccgramView on GitHub
.archfit.yaml
.claude/
rules/
architecture.md
message-handling.md
topic-architecture.md
settings.json
skills/
releasing/
SKILL.md
.env.example
.github/
pull_request_template.md
workflows/
ci.yml
release.yml
.gitignore
.markdownlint.json
CHANGELOG.md
cliff.toml
CONTRIBUTING.md
docs/
ai-agents/
architecture-map.md
codebase-index.md
extension-and-fix-playbook.md
README.md
tooling-and-tests.md
architecture-design/
2026-05-23-ccgram-target.md
2026-06-21-herdr-multiplexer-support.md
architecture-plan/
2026-05-23-window-state-feature-ports.md
architecture-review/
2026-05-23-ccgram-full.md
2026-06-27-ccgram-full.md
architecture.md
examples/
toolbar.toml
guides.md
modularity-review/
2026-05-01/
modularity-review.html
modularity-review.md
plans/
completed/
2026-04-27-telegram-ux-overhaul.md
20260404-informative-output.md
20260406-live-view.md
20260409-enhance-telegram-ux.md
20260411-send-command.md
20260412-modularity-refactor.md
20260413-architecture-refactor.md
20260414-messaging-and-polling-refactor.md
20260415-modularity-decouple.md
20260416-modularity-fixes-round-3.md
20260429-modularity-decouple-round-4-import-audit.md
20260429-modularity-decouple-round-4.md
20260429-modularity-review.html
20260429-modularity-review.md
20260501-modularity-decouple-round-5.md
20260515-rc-feedback-and-worktree-topics.md
20260522-screenshot-viewport-toolbar.md
20260621-herdr-shell-provider.md
20260621-multiplexer-seam.md
20260622-herdr-tab-topics.md
20260628-architecture-hotspot-refactor.md
ephemeral-tool-progress.md
herdr-agent-endpoint-adaptation.md
presentaions/
slides.md
style.css
providers.md
LICENSE
llm.txt
Makefile
pyproject.toml
README.md
scripts/
generate_homebrew_formula.py
git-hooks/
pre-push
lint_lazy_imports.py
restart.sh
src/
ccgram/
__init__.py
bootstrap.py
bot.py
cc_commands.py
claude_task_state.py
cli.py
command_catalog.py
config.py
doctor_cmd.py
entity_formatting.py
event_reader.py
event_stream_monitor.py
expandable_quote.py
fonts/
JetBrainsMono-Regular.ttf
LICENSE-JetBrainsMono.txt
LICENSE-NotoSansMono.txt
LICENSE-Symbola.txt
NotoSansMonoCJKsc-Regular.otf
Symbola.ttf
handlers/
__init__.py
agent_command.py
callback_data.py
callback_helpers.py
callback_registry.py
callback_tokens.py
cleanup.py
command_history.py
commands/
__init__.py
failure_probe.py
forward.py
menu_sync.py
status_snapshot.py
file_handler.py
hook_events.py
inline.py
interactive/
__init__.py
interactive_callbacks.py
interactive_ui.py
last_reply.py
live/
__init__.py
live_view.py
pane_callbacks.py
screenshot_callbacks.py
messaging_pipeline/
__init__.py
message_queue.py
message_routing.py
message_sender.py
message_task.py
tool_batch.py
topic_commands.py
polling/
__init__.py
periodic_tasks.py
polling_coordinator.py
polling_runtime.py
polling_state.py
polling_types.py
window_tick/
__init__.py
apply.py
decide.py
observe.py
reactions.py
recovery/
__init__.py
history_callbacks.py
history.py
recovery_banner.py
recovery_callbacks.py
restore_command.py
resume_command.py
resume_picker.py
transcript_discovery.py
registry.py
response_builder.py
send/
__init__.py
send_callbacks.py
send_command.py
send_security.py
sessions_dashboard.py
shell/
__init__.py
shell_capture.py
shell_commands.py
shell_context.py
shell_prompt_orchestrator.py
split_command.py
status/
__init__.py
rc_probe.py
status_bar_actions.py
status_bubble.py
topic_emoji.py
sync_command.py
telegram_origin.py
text/
__init__.py
text_handler.py
toolbar/
__init__.py
toolbar_callbacks.py
toolbar_keyboard.py
topics/
__init__.py
directory_browser.py
directory_callbacks.py
new_command.py
provider_mode_callbacks.py
topic_creation_draft.py
topic_lifecycle.py
topic_orchestration.py
topic_probe.py
window_callbacks.py
window_launch_service.py
workspace_callbacks.py
worktree.py
upgrade.py
user_state.py
voice/
__init__.py
voice_callbacks.py
voice_handler.py
herdr_targets.py
hook.py
hooks/
__init__.py
adapters.py
model.py
state_files.py
idle_tracker.py
last_unit.py
llm/
__init__.py
base.py
httpx_completer.py
summarizer.py
main.py
miniapp/
__init__.py
api/
__init__.py
terminal.py
transcript.py
auth.py
server.py
static/
index.html
panes.js
terminal.js
transcript.js
monitor_events.py
monitor_state.py
multiplexer/
__init__.py
agent_status_cache.py
base.py
herdr_events.py
herdr.py
reconciliation.py
registry.py
self_identify.py
tmux.py
topic_mapping.py
vim_state.py
window_ops.py
providers/
__init__.py
_jsonl.py
_resume.py
antigravity.py
base.py
claude.py
codex_format.py
codex_status.py
codex.py
gemini.py
pi_discovery.py
pi_format.py
pi.py
process_detection.py
registry.py
shell_infra.py
shell.py
screen_buffer.py
screenshot.py
session_lifecycle.py
session_map.py
session_monitor.py
session_query.py
session_resolver.py
session_state_ports/
__init__.py
live_session_state.py
session.py
state_persistence.py
status_cmd.py
telegram_client.py
telegram_draft.py
telegram_request.py
telegram_sender.py
terminal_parser.py
thread_router.py
tool_format.py
toolbar_config.py
topic_state_registry.py
transcript_parser.py
transcript_reader.py
tts/
__init__.py
base.py
edge.py
openai.py
user_preferences.py
utils.py
whisper/
__init__.py
base.py
httpx_transcriber.py
window_query.py
window_resolver.py
window_state_ports/
__init__.py
identity_state.py
legacy_state.py
lifecycle_state.py
pane_state.py
tool_state.py
worktree_state.py
window_state_store.py
window_view.py
tests/
ccgram/
_helpers.py
conftest.py
handlers/
__init__.py
commands/
__init__.py
test_failure_probe.py
test_forward.py
test_menu_sync.py
test_status_snapshot.py
conftest.py
interactive/
test_interactive_ui.py
live/
test_live_view.py
test_pane_callbacks.py
test_screenshot_commands.py
messaging_pipeline/
__init__.py
test_ephemeral_tool_batch.py
test_message_queue_properties.py
test_message_queue.py
test_message_routing.py
test_message_sender.py
test_message_task.py
test_tool_batch.py
test_tool_batching.py
polling/
__init__.py
test_pane_status_strategy.py
test_polling_coordinator.py
test_polling_runtime.py
test_polling_strategies.py
test_polling_types_purity.py
test_status_polling.py
test_tick_decision.py
test_window_tick.py
window_tick/
__init__.py
test_decide.py
test_native_agent_status.py
recovery/
__init__.py
test_history_callbacks.py
test_history.py
test_recovery_banner.py
test_recovery_subpackage_surface.py
test_recovery_ui.py
test_restore_command.py
test_resume_command.py
test_transcript_discovery_key.py
send/
__init__.py
test_send_callbacks.py
test_send_command.py
test_send_security.py
shell/
__init__.py
test_shell_capture.py
test_shell_commands.py
test_shell_prompt_orchestrator.py
status/
test_rc_probe.py
test_status_bar_actions.py
test_status_bubble.py
test_status_buttons.py
test_status_recall_callback.py
test_status_singleton.py
test_topic_emoji.py
test_agent_command.py
test_bot_callbacks.py
test_callback_auth.py
test_callback_registry.py
test_callback_tokens.py
test_cleanup_gaps.py
... 202 moreMore Flows by @alexei-led.
@alexei-ledFAQ
ccgram is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes releasing. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is ccgram?
- Control AI coding agents from your phone. Walk away mid-session. Keep monitoring and responding from Telegram—without losing terminal access.
- How do I install ccgram?
- Run these in Claude Code: npx -y skills add alexei-led/ccgram --agent claude-code. Then prompt normally.
- Does ccgram auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is ccgram free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.