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.

How it works

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.

Installation

# 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@latest

Prerequisites

• Go 1.24+
• At least one AI coding agent:

Agent	Command
Claude Code	claude
OpenCode	opencode
Codex	codex
Gemini CLI	gemini

Quick start

openconductor                    # launch the TUI
openconductor --debug            # with verbose logging
openconductor persona            # manage custom personas
openconductor telegram setup     # set up the Telegram bridge

Config 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: -1001234567890

OpenConductor restores your open tabs on restart — your workspace persists across sessions.

Features

Tabbed workspace 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.	Telegram remote control 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.
Auto-approve Per-project permission auto-approval: off, safe (file ops + safe shell), or full (everything). Prefers session-wide approval when the agent supports it.	Faithful scrollback 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.
Text selection & copy Click-and-drag to select text with reverse-video highlighting. Auto-copied to clipboard on release. Ctrl+Shift+C copies the entire visible panel.	Agent switching 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.
Persona presets 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.	Custom personas Create your own personas with the built-in wizard (P in sidebar or openconductor persona). Define a name, instructions, and default auto-approve level. Custom personas appear alongside built-in ones in the project form and persona picker.

Keyboard shortcuts

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)

Telegram

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

Architecture

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

Development

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)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run make check to verify everything passes
4. Open a Pull Request against master

See CONTRIBUTING.md for the full guide.

---

_{MIT License  ·  Copyright © 2026 The OpenConductor Authors}