Installation · Quick Start · Features · Telegram · Architecture · Contributing
You're running five AI agents across five repos. Each lives in its own terminal tab. When one finishes, you don't notice for twenty minutes. When one asks for permission, you're in another window. When one errors out, it sits there burning tokens on nothing.
OpenConductor fixes this. Every agent runs in its own real PTY with full VT100 emulation. A two-layer attention system watches them all and tells you exactly when you're needed.
One keyboard. All your agents. Zero wasted time.
Every agent runs in its own real PTY. Every 500ms, the attention detector evaluates each session and assigns one of six states. Notifications flow to three channels simultaneously.
Layer 1 — Heuristics. Agent-specific pattern matching catches permission prompts, errors, spinners, idle states, and completion signals. Each agent implements AttentionChecker — adding a new agent's heuristics is a single file.
Layer 2 — LLM classifier. When heuristics are uncertain, the last ~20 terminal lines are sent to an LLM for structured classification. Throttled to once per 5s with exponential backoff. Supports Anthropic, OpenAI, and Google.
# Pre-built binary (Linux & macOS, amd64 & arm64)
# → https://github.com/wilfoa/openconductor/releases
# From source
git clone https://github.com/wilfoa/openconductor.git
cd openconductor && make build
# Via Go
go install github.com/wilfoa/openconductor/cmd/openconductor@latestPrerequisites
- Go 1.24+
- At least one AI coding agent:
| Agent | Command |
|---|---|
| Claude Code | claude |
| OpenCode | opencode |
| Codex | codex |
| Gemini CLI | gemini |
openconductor # launch the TUI
openconductor --debug # with verbose logging
openconductor persona # manage custom personas
openconductor telegram setup # set up the Telegram bridgeConfig lives at ~/.openconductor/config.yaml — or press a in the sidebar to add projects interactively.
Example config
projects:
- name: my-api
repo: ~/code/my-api
agent: claude-code # or "opencode"
persona: scale # vibe | poc | scale | custom name
auto_approve: off # off | safe | full
- name: frontend
repo: ~/code/frontend
agent: opencode
persona: vibe
# Optional: custom personas
personas:
- name: security-review
label: Security Review
instructions: |
Focus on security vulnerabilities.
- Review for OWASP Top 10
- Flag hardcoded secrets
auto_approve: off
# Optional: LLM classifier for ambiguous attention states
llm:
provider: anthropic # anthropic | openai | google
api_key_env: ANTHROPIC_API_KEY
notifications:
enabled: true
cooldown_seconds: 30
# Optional: Telegram bridge
telegram:
bot_token_env: TELEGRAM_BOT_TOKEN
chat_id: -1001234567890OpenConductor restores your open tabs on restart — your workspace persists across sessions.
|
Project sidebar with status badges, full terminal on the right. Each project runs its own agent in a real PTY with color, cursor, and alternate-screen support. Switch with a keypress, spawn multiple sessions, rename tabs with F2. |
Bidirectional bridge to a Telegram supergroup with Forum Topics. Approve permissions, answer questions, send input, and monitor every agent from your phone. Screen snapshots with every notification. |
|
Per-project permission auto-approval: |
Scroll with mouse wheel or PageUp/PageDown. Per-write capture preserves every line exactly as it appeared — tables, blank separators, repeated content. Smart pinning keeps your place while new output arrives. |
|
Click-and-drag to select text with reverse-video highlighting. Auto-copied to clipboard on release. Ctrl+Shift+C copies the entire visible panel. |
Press s to swap a project between Claude Code and OpenCode on the fly. The session tears down and restarts with the other agent. Config saved automatically. |
|
Equip each project with a behavioral persona: Vibe (move fast, skip tests), POC (working demos, basic quality), or Scale (TDD, production-grade). Each persona writes instructions, configures MCPs (context7, playwright, sequential-thinking), installs skills (TDD, code review), and enables plugins — all automatically. Press p to change, P to manage custom personas. |
Create your own personas with the built-in wizard (P in sidebar or |
| Terminal | |
|---|---|
| Ctrl+S | Toggle sidebar focus |
| Ctrl+J Ctrl+K | Previous / next tab |
| Ctrl+Shift+C | Copy terminal panel to clipboard |
| F2 | Rename active tab |
| PageUp PageDown | Scroll through history |
| Ctrl+C Ctrl+C | Exit (double-tap) |
| Sidebar | |
| j k | Navigate projects |
| Enter | Open project |
| n | New session |
| s | Switch agent |
| a | Add project |
| d | Delete project |
| p | Change persona |
| P | Manage custom personas |
| t | Telegram setup |
| Mouse | |
| Click | Select tabs, sidebar items |
| Drag border | Resize sidebar |
| Scroll wheel | Scroll terminal |
| Click + drag | Select text (auto-copied) |
Bridges every project to a Telegram supergroup with Forum Topics. Each project gets its own thread. The same permission and question flows you see in the TUI work natively through Telegram with inline reply buttons — approve permissions, pick from numbered options, or send freeform input, all from your phone.
openconductor telegram setup # interactive wizard| Event | What you see on Telegram |
|---|---|
| Permission request | Screen snapshot + [Allow Once] [Allow Always] [Deny] inline buttons. One tap approves — agent continues immediately. |
| Question dialog | Numbered buttons auto-parsed from the agent's screen (e.g. [1. Jest] [2. Vitest] [3. Playwright]). Tap to answer. |
| Needs attention | Quick-reply buttons: [yes] [no] [continue] [skip]. |
| Error | [retry] [skip] [abort] buttons with a screen snapshot showing the error. |
| Free text | Send any message in a project's thread — typed directly into the agent's PTY. |
After every button press, the original message is edited to show what action was taken and by whom.
Full setup guide: docs/TELEGRAM_INTEGRATION.md
openconductor
├── cmd/openconductor/ Entry point, flag parsing, initialization
└── internal/
├── agent/ AgentAdapter interface + implementations
│ ├── claude.go Claude Code (chrome filtering, CSI stripping, history)
│ └── opencode.go OpenCode (sidebar cropping, question dialogs)
├── attention/ L1 heuristics + L2 LLM attention detection
├── session/ PTY lifecycle, vt10x terminal, scroll-off capture
├── tui/ Bubble Tea app (tabs, sidebar, terminal, status bar)
├── llm/ Multi-provider LLM client (Anthropic, OpenAI, Google)
├── permission/ Permission classification (L1 patterns + L2 LLM)
├── telegram/ Bidirectional Telegram bot bridge
├── persona/ Persona presets (instructions, MCPs, skills, plugins)
├── config/ YAML config + app state (tab restoration)
├── notification/ Desktop notifications
├── bootstrap/ Repo scaffolding with Go templates
└── logging/ Structured JSON logger (slog)
Built with
| Bubble Tea + Lipgloss | TUI framework and terminal styling |
| vt10x | VT100/VT220 terminal emulation |
| creack/pty | PTY allocation |
| Anthropic SDK · OpenAI SDK · Google GenAI | LLM clients |
| beeep | Desktop notifications |
make build # build binary
make test # tests with race detector
make lint # golangci-lint
make coverage # tests + coverage report
make check # fmt + vet + lint + test (run before pushing)- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Run
make checkto verify everything passes - Open a Pull Request against
master
See CONTRIBUTING.md for the full guide.
MIT License · Copyright © 2026 The OpenConductor Authors