https://github.com/untra/operator
š Operator! Multi-agent orchestration dashboard for AI assisted kanban shaped software development
https://github.com/untra/operator
claude-code gemini-cli git jira kanban linear llm tmux
Last synced: about 2 months ago
JSON representation
š Operator! Multi-agent orchestration dashboard for AI assisted kanban shaped software development
- Host: GitHub
- URL: https://github.com/untra/operator
- Owner: untra
- License: mit
- Created: 2025-12-22T05:55:54.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-10T23:18:22.000Z (5 months ago)
- Last Synced: 2026-01-11T05:32:49.868Z (5 months ago)
- Topics: claude-code, gemini-cli, git, jira, kanban, linear, llm, tmux
- Language: Rust
- Homepage: http://operator.untra.io/
- Size: 2.49 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Operator!
[](https://github.com/untra/operator/releases) [](https://codecov.io/gh/untra/operator) [](https://marketplace.visualstudio.com/items?itemName=untra.operator-terminals)
* **Session** [](https://operator.untra.io/getting-started/sessions/tmux/) [](https://operator.untra.io/getting-started/sessions/cmux/) [](https://operator.untra.io/getting-started/sessions/zellij/)
* **LLM Tool** [](https://operator.untra.io/getting-started/agents/claude/) [](https://operator.untra.io/getting-started/agents/codex/) [](https://operator.untra.io/getting-started/agents/gemini-cli/)
* **Kanban Provider** [](https://operator.untra.io/getting-started/kanban/jira/) [](https://operator.untra.io/getting-started/kanban/linear/) [](https://operator.untra.io/getting-started/kanban/github/)
* **Git Version Control** [](https://operator.untra.io/getting-started/git/github/) [](https://operator.untra.io/getting-started/git/gitlab/)
An orchestration tool for [**AI-assisted**](https://operator.untra.io/getting-started/agents/) [_kanban-shaped_](https://operator.untra.io/getting-started/kanban/) [git-versioned](https://operator.untra.io/getting-started/git/) software development.
Install Operator! Terminals extension from Visual Studio Code Marketplace
**Operator** is for you if:
- you do work assigned from tickets on a kanban board, such as [_Jira Cloud_](https://operator.untra.io/getting-started/kanban/jira/), [_Linear_](https://operator.untra.io/getting-started/kanban/linear/), or [_GitHub Projects_](https://operator.untra.io/getting-started/kanban/github/)
- you use LLM assisted coding agent tools to accomplish work, such as [_Claude Code_](https://operator.untra.io/getting-started/agents/claude/), [_OpenAI Codex_](https://operator.untra.io/getting-started/agents/codex/), or [_Google Gemini CLI_](https://operator.untra.io/getting-started/agents/gemini-cli/)
- your work is version controlled with a git repository provider like [_GitHub_](https://operator.untra.io/getting-started/git/github/) or [_GitLab_](https://operator.untra.io/getting-started/git/gitlab/)
- you are drowning in the AI software development soup.
and you are ready to start seriously automating your work.
## Overview
`operator` is a TUI (terminal user interface) application that uses session wrappers ([tmux](https://operator.untra.io/getting-started/sessions/tmux/), [cmux](https://operator.untra.io/getting-started/sessions/cmux/), or [Zellij](https://operator.untra.io/getting-started/sessions/zellij/)) to manage multiple AI coding agents across multi-project workspaces of many codebases. It is designed to be ticket-first, launching LLM coding agents keyed off from markdown stories from a ticketing provider. It provides:
- **Queue Management**: ticket queue with priority-based work assignment, launchable from a dashboard
- **Agent Orchestration**: Launch, monitor, pause/resume LLM coding agents against kanban shaped work tickets, and track the ticket progress as it goes through your defined work implementation steps
- **Notifications**: macOS and linux notifications for agent events, keeping you the human in the loop.
- **Dashboard**: Real-time view of queue, active agents, completed work, and waiting instances seeking feedback or human review
Operator is designed to facilitate work from markdown tickets, tackling tasks across multiple code repositories by semi-autonomous agents. Operator should be started from the root of your collective work projects repository (eg, `~/Documents`), so that it may start feature or fix work in the right part of the codebase.
When started for the first time, Operator will setup configuration to consume and process work tickets, and identify local projects by scanning for LLM tool marker files (`CLAUDE.md`, `CODEX.md`, `GEMINI.md`) and git repositories.
Operator comes with a separate web component, unneeded to do work but purpose built to give you a developer portal to expand their workflows and administrate Operator with ease.
Operator starts and runs it's own REST API, which can be reached by outside clients, including by the `opr8r` wrapper client. This is included to communicate with Operator api hosts outside of where it's hosted.
## Usage
```bash
# Launch dashboard
operator
# Quick commands (without entering TUI)
operator queue # Show queue status
operator launch # Launch agent for ticket (with confirmation)
operator create # Create a new work ticket
operator agents # List active agents
operator pause # Pause queue processing
operator resume # Resume queue processing
operator stalled # Show stalled agents awaiting input
operator alert # Create investigation from external alert
operator docs # Generate documentation from source-of-truth files
operator api # Start the REST API server
operator setup # Initialize operator workspace
```
## Installation
Download the latest release for your platform:
```bash
# macOS Apple Silicon
curl -L https://github.com/untra/operator/releases/latest/download/operator-macos-arm64 -o operator
chmod +x operator
sudo mv operator /usr/local/bin/
# Linux x86_64
curl -L https://github.com/untra/operator/releases/latest/download/operator-linux-x86_64 -o operator
chmod +x operator
sudo mv operator /usr/local/bin/
# Linux ARM64
curl -L https://github.com/untra/operator/releases/latest/download/operator-linux-arm64 -o operator
chmod +x operator
sudo mv operator /usr/local/bin/
```
Or build from source:
```bash
git clone https://github.com/untra/operator.git
cd operator
cargo build --release
sudo cp target/release/operator /usr/local/bin/
```
## Configuration
Workspace configuration lives in `.tickets/operator/config.toml` (created by `operator setup`). An optional global override can be placed at `~/.config/operator/config.toml`.
```toml
[agents]
max_parallel = 5 # Maximum concurrent agents
cores_reserved = 1 # Cores to keep free (actual max = cores - reserved)
health_check_interval = 30
[notifications]
enabled = true
[notifications.os]
enabled = true
sound = false
events = [] # Empty = all events
[queue]
auto_assign = true # Automatically assign work when agents free
priority_order = ["INV", "FIX", "FEAT", "SPIKE"]
poll_interval_ms = 1000
[paths]
tickets = ".tickets" # Relative to cwd
projects = "." # cwd is projects root
state = ".tickets/operator"
[ui]
refresh_rate_ms = 250
completed_history_hours = 24
summary_max_length = 40
[launch]
confirm_autonomous = true
confirm_paired = true
launch_delay_ms = 2000
[sessions]
wrapper = "tmux" # "tmux", "cmux", or "zellij"
```
## Ticket Priority
Work is assigned in priority order (not strict FIFO):
1. **INV** (Investigation) - Failures need immediate attention
2. **FIX** - Bug fixes and follow-up work
3. **FEAT** - New features
4. **SPIKE** - Research (requires human pairing)
Within each priority level, tickets are processed FIFO by timestamp.
## Agent Types
| Type | Mode | Parallelism | Human Required |
|------|------|-------------|----------------|
| Investigation | Paired | Single | Yes (urgent) |
| Spike | Paired | Single | Yes |
| Fix | Autonomous | Parallel OK | No (launch confirm only) |
| Feature | Autonomous | Parallel OK | No (launch confirm only) |
## Dashboard Layout
```
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā operator v0.1.28 ā¶ RUNNING 5/7 ā
āāāāāāāāāāāā¬āāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāā¤
ā STATUS ā QUEUE (12) ā IN PROGRESS (5) ā DONE (8) ā
āāāāāāāāāāāā¼āāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāā¤
ā ā¾ Config ā INV-003 ā¼ļø ā Aā¶ backend ā ā FEAT-040 12:30 ā
ā ā dir ā FIX-089 ā FEAT-042 5m ā ā FIX-088 12:15 ā
ā ā cfg ā FIX-090 ā Aā¶ frontend ā ā FEAT-041 11:45 ā
ā ā tkts ā FEAT-043 ā FIX-091 3m ā ā FIX-087 11:30 ā
ā ā¾ Conns ā FEAT-044 ā Cāø api ā ā
ā ā API ā FEAT-045 ā SPIKE-015 12m ā ā
ā ā Web ā ā Awaiting input ā ā
ā tmux ā ā Aā¶ admin ā ā
ā āø Kanban ā ā FEAT-047 1m ā ā
ā āø LLM ā ā Aā¶ infra ā ā
ā āø Git ā ā FIX-092 8m ā ā
āāāāāāāāāāāā“āāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāā¤
ā [Q]ueue [L]aunch [P]ause [R]esume [A]gents [?]Help [q]uit ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
```
## Keyboard Shortcuts
See [Keyboard Shortcuts Reference](https://operator.untra.io/shortcuts/) for the full list, auto-generated from [`src/ui/keybindings.rs`](src/ui/keybindings.rs). Press `?` in the TUI to view shortcuts in-app.
## Integration Points
### LLM Agent Launch
Agents are launched in terminal sessions with the appropriate project folder and an initial prompt derived from the ticket.
### Third-Party Integrations
Investigations can be triggered externally:
- Webhook endpoint for alerting systems
- File watch for alert drop files
- CLI for manual urgent tickets
```bash
# Create urgent investigation from external alert
operator alert --source pagerduty --message "500 errors in backend" --severity S1
```
## LLM CLI Tool Integration
Operator launches LLM agents via CLI tools in terminal sessions. Each tool is configured via a JSON definition in `src/llm/tools/`.
### Supported Tools
| Tool | Detection | Models | Session Flag |
|------|-----------|--------|--------------|
| `claude` | `claude --version` | opus, sonnet, haiku | `--session-id` |
| `codex` | `codex --version` | gpt-4o, o1, o3 | `--resume` |
| `gemini` | `gemini --version` | pro, flash, ultra | `--resume` |
### How Operator Calls LLM Tools
Each tool has a JSON config in `src/llm/tools/` that defines argument mappings and a command template. Operator constructs the launch command from this config:
- **Prompt file**: Prompts are written to `.tickets/operator/prompts/.txt` to avoid shell escaping issues with multiline prompts
- **Session ID**: A UUID v4 is generated per launch, enabling session resumption
- **Model aliases**: Operator uses short aliases (e.g., "opus", "sonnet") that resolve to latest model versions
### Adding Support for New LLM Tools
Create a new JSON tool config following the schema in `src/llm/tools/tool_config.schema.json`. The config defines:
- Tool binary name and version detection command
- Model aliases and argument mappings
- Command template with placeholder variables
- Capability flags (sessions, headless, permission modes)
**Requirements for the LLM tool:**
- Must be installable as a CLI binary
- Must accept prompt via flag (not just stdin)
- Must support model selection
- Should support session/conversation ID for continuity
- Should run interactively in a terminal (for session wrapper integration)
## Model Servers
Operator's agent-launch hierarchy has three layers:
```
āā llm_tools āāāāāāāāāā āā model_servers āāāāāāā
ā claude (detected) ā ā anthropic-api (impl.)ā
ā codex (detected) ā ā openai-api (impl.)ā
ā gemini (detected) ā ā google-api (impl.)ā
ā ā ā ollama-local (user) ā
āāāāāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāā
ā² ā²
ā ā
āāāāāā delegators āāāāāāāā
name, llm_tool, model, model_server (optional)
```
- **`llm_tools`** are the agentic coding-agent CLIs (claude/codex/gemini). They're detected on PATH and drive the session.
- **`model_servers`** name the host that serves the model weights. Implicit builtins (`anthropic-api`, `openai-api`, `google-api`) exist without declaration. Users can declare additional servers for ollama, lmstudio, vllm, or any OpenAI-compatible endpoint.
- **`delegators`** are named `(llm_tool, model, model_server?)` triples used to launch a ticket. When `model_server` is omitted, the llm_tool's implicit vendor default is used.
Example `operator.toml`:
```toml
[[model_servers]]
name = "ollama-local"
kind = "ollama"
base_url = "http://localhost:11434"
[[delegators]]
name = "codex-local-qwen"
llm_tool = "codex"
model = "qwen2.5-coder"
model_server = "ollama-local"
```
Ad-hoc launch flags:
```bash
# Named delegator (recommended)
operator launch --delegator codex-local-qwen
# Ad-hoc override
operator launch --llm-tool codex --model qwen2.5-coder --model-server ollama-local
```
**Protocol compatibility.** Codex speaks the OpenAI API ā pairing with ollama requires no bridge. Claude and Gemini use their own vendor protocols and require a translating proxy (e.g. `claude-code-router`, `litellm-proxy`) between the CLI and ollama; declare the bridge URL as your `model_server.base_url`.
Current release ships the infrastructure ā ollama detection and automatic env-var injection on spawn land in the next release. See `docs/getting-started/model-servers/` for the full walkthrough.
## Development
```bash
# Run in development
cargo run
# Run tests
cargo test
# Build release
cargo build --release
```
## Documentation
Reference documentation is auto-generated from source-of-truth files to minimize maintenance.
### Available References
| Generator | Source | Output |
|-----------|--------|--------|
| taxonomy | `src/backstage/taxonomy.toml` | `docs/backstage/taxonomy.md` |
| issuetype-schema | `src/schemas/issuetype_schema.json` | `docs/schemas/issuetype.md` |
| metadata-schema | `src/schemas/ticket_metadata.schema.json` | `docs/schemas/metadata.md` |
| shortcuts | `src/ui/keybindings.rs` | `docs/shortcuts/index.md` |
| cli | `src/main.rs`, `src/env_vars.rs` | `docs/cli/index.md` |
| config | `src/config.rs` | `docs/configuration/index.md` |
| OpenAPI | `src/rest/` (utoipa annotations) | `docs/schemas/openapi.json` |
| llm-tools | `src/llm/tools/tool_config.schema.json` | `docs/llm-tools/index.md` |
| startup | `src/startup/mod.rs` | `docs/startup/index.md` |
| config-schema | `docs/schemas/config.json` | `docs/schemas/config.md` |
| state-schema | `docs/schemas/state.json` | `docs/schemas/state.md` |
| schema-index | `docs/schemas/` | `docs/schemas/index.md` |
| jira-api | `docs/schemas/jira-api.json` | `docs/getting-started/kanban/jira-api.md` |
### Viewing Documentation
```bash
# Serve docs locally with Jekyll
cd docs && bundle install && bundle exec jekyll serve
# Visit http://localhost:4000
# View OpenAPI spec with Swagger UI
# After starting Jekyll, visit http://localhost:4000/schemas/api/
```
### Regenerating Documentation
```bash
# Regenerate all auto-generated docs
cargo run -- docs
# Regenerate specific docs
cargo run -- docs --only openapi
cargo run -- docs --only config
# Available generators: taxonomy, issuetype-schema, metadata-schema, shortcuts,
# cli, config, OpenAPI, llm-tools, startup, config-schema, state-schema,
# schema-index, jira-api
```