{"id":34683637,"url":"https://github.com/untra/operator","last_synced_at":"2026-05-08T01:12:22.424Z","repository":{"id":329898726,"uuid":"1120899606","full_name":"untra/operator","owner":"untra","description":"📞 Operator! Multi-agent orchestration dashboard for AI assisted kanban shaped software development","archived":false,"fork":false,"pushed_at":"2026-01-10T23:18:22.000Z","size":2616,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T05:32:49.868Z","etag":null,"topics":["claude-code","gemini-cli","git","jira","kanban","linear","llm","tmux"],"latest_commit_sha":null,"homepage":"http://operator.untra.io/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/untra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-22T05:55:54.000Z","updated_at":"2026-01-10T23:16:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/untra/operator","commit_stats":null,"previous_names":["untra/operator"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/untra/operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untra%2Foperator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untra%2Foperator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untra%2Foperator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untra%2Foperator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/untra","download_url":"https://codeload.github.com/untra/operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untra%2Foperator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28336519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","gemini-cli","git","jira","kanban","linear","llm","tmux"],"created_at":"2025-12-24T21:36:54.250Z","updated_at":"2026-05-08T01:12:22.413Z","avatar_url":"https://github.com/untra.png","language":"Rust","funding_links":[],"categories":["Feature Dimensions"],"sub_categories":["5. Multi-Agent Orchestration"],"readme":"![Operator! logo](docs/assets/img/operator_logo.svg)\n\n# Operator!\n[![GitHub Tag](https://img.shields.io/github/v/tag/untra/operator)](https://github.com/untra/operator/releases) [![codecov](https://codecov.io/gh/untra/operator/branch/main/graph/badge.svg)](https://codecov.io/gh/untra/operator) [![VS Code Marketplace Installs](https://img.shields.io/visual-studio-marketplace/i/untra.operator-terminals?label=VS%20Code%20Installs)](https://marketplace.visualstudio.com/items?itemName=untra.operator-terminals)\n\n* **Session** [![tmux](https://img.shields.io/badge/tmux-1BB91F?logo=tmux\u0026logoColor=white)](https://operator.untra.io/getting-started/sessions/tmux/) [![cmux](https://img.shields.io/badge/cmux-333333)](https://operator.untra.io/getting-started/sessions/cmux/) [![Zellij](https://img.shields.io/badge/Zellij-E8590C)](https://operator.untra.io/getting-started/sessions/zellij/)\n\n* **LLM Tool** [![Claude](https://img.shields.io/badge/Claude-D97757?logo=claude\u0026logoColor=white)](https://operator.untra.io/getting-started/agents/claude/) [![Codex](https://img.shields.io/badge/Codex-000000?logo=openai\u0026logoColor=white)](https://operator.untra.io/getting-started/agents/codex/) [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-8E75B2?logo=googlegemini\u0026logoColor=white)](https://operator.untra.io/getting-started/agents/gemini-cli/)\n\n* **Kanban Provider** [![Jira](https://img.shields.io/badge/Jira-0052CC?logo=jira\u0026logoColor=white)](https://operator.untra.io/getting-started/kanban/jira/) [![Linear](https://img.shields.io/badge/Linear-5E6AD2?logo=linear\u0026logoColor=white)](https://operator.untra.io/getting-started/kanban/linear/) [![GitHub Projects](https://img.shields.io/badge/GitHub_Projects-181717?logo=github\u0026logoColor=white)](https://operator.untra.io/getting-started/kanban/github/)\n\n* **Git Version Control** [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github\u0026logoColor=white)](https://operator.untra.io/getting-started/git/github/) [![GitLab](https://img.shields.io/badge/GitLab-FC6D26?logo=gitlab\u0026logoColor=white)](https://operator.untra.io/getting-started/git/gitlab/)\n\nAn 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.\n\n\u003ca href=\"https://marketplace.visualstudio.com/items?itemName=untra.operator-terminals\" target=\"_blank\" class=\"button\"\u003eInstall \u003cb\u003eOperator! Terminals\u003c/b\u003e extension from Visual Studio Code Marketplace\u003c/a\u003e\n\n**Operator** is for you if:\n\n- 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/)\n- 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/)\n- 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/)\n\n- you are drowning in the AI software development soup.\n\nand you are ready to start seriously automating your work.\n\n## Overview\n\n`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:\n\n- **Queue Management**: ticket queue with priority-based work assignment, launchable from a dashboard\n- **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\n- **Notifications**: macOS and linux notifications for agent events, keeping you the human in the loop. \n- **Dashboard**: Real-time view of queue, active agents, completed work, and waiting instances seeking feedback or human review\n\nOperator 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.\n\nWhen 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.\n\nOperator 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.\n\nOperator 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.\n\n## Usage\n\n```bash\n# Launch dashboard\noperator\n\n# Quick commands (without entering TUI)\noperator queue              # Show queue status\noperator launch \u003cticket\u003e    # Launch agent for ticket (with confirmation)\noperator create             # Create a new work ticket\noperator agents             # List active agents\noperator pause              # Pause queue processing\noperator resume             # Resume queue processing\noperator stalled            # Show stalled agents awaiting input\noperator alert              # Create investigation from external alert\noperator docs               # Generate documentation from source-of-truth files\noperator api                # Start the REST API server\noperator setup              # Initialize operator workspace\n```\n\n## Installation\n\nDownload the latest release for your platform:\n\n```bash\n# macOS Apple Silicon\ncurl -L https://github.com/untra/operator/releases/latest/download/operator-macos-arm64 -o operator\nchmod +x operator\nsudo mv operator /usr/local/bin/\n\n# Linux x86_64\ncurl -L https://github.com/untra/operator/releases/latest/download/operator-linux-x86_64 -o operator\nchmod +x operator\nsudo mv operator /usr/local/bin/\n\n# Linux ARM64\ncurl -L https://github.com/untra/operator/releases/latest/download/operator-linux-arm64 -o operator\nchmod +x operator\nsudo mv operator /usr/local/bin/\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/untra/operator.git\ncd operator\ncargo build --release\nsudo cp target/release/operator /usr/local/bin/\n```\n\n## Configuration\n\nWorkspace configuration lives in `.tickets/operator/config.toml` (created by `operator setup`). An optional global override can be placed at `~/.config/operator/config.toml`.\n\n```toml\n[agents]\nmax_parallel = 5          # Maximum concurrent agents\ncores_reserved = 1        # Cores to keep free (actual max = cores - reserved)\nhealth_check_interval = 30\n\n[notifications]\nenabled = true\n\n[notifications.os]\nenabled = true\nsound = false\nevents = []               # Empty = all events\n\n[queue]\nauto_assign = true        # Automatically assign work when agents free\npriority_order = [\"INV\", \"FIX\", \"FEAT\", \"SPIKE\"]\npoll_interval_ms = 1000\n\n[paths]\ntickets = \".tickets\"      # Relative to cwd\nprojects = \".\"            # cwd is projects root\nstate = \".tickets/operator\"\n\n[ui]\nrefresh_rate_ms = 250\ncompleted_history_hours = 24\nsummary_max_length = 40\n\n[launch]\nconfirm_autonomous = true\nconfirm_paired = true\nlaunch_delay_ms = 2000\n\n[sessions]\nwrapper = \"tmux\"          # \"tmux\", \"cmux\", or \"zellij\"\n```\n\n## Ticket Priority\n\nWork is assigned in priority order (not strict FIFO):\n\n1. **INV** (Investigation) - Failures need immediate attention\n2. **FIX** - Bug fixes and follow-up work\n3. **FEAT** - New features\n4. **SPIKE** - Research (requires human pairing)\n\nWithin each priority level, tickets are processed FIFO by timestamp.\n\n## Agent Types\n\n| Type | Mode | Parallelism | Human Required |\n|------|------|-------------|----------------|\n| Investigation | Paired | Single | Yes (urgent) |\n| Spike | Paired | Single | Yes |\n| Fix | Autonomous | Parallel OK | No (launch confirm only) |\n| Feature | Autonomous | Parallel OK | No (launch confirm only) |\n\n## Dashboard Layout\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ operator v0.1.28                      ▶ RUNNING   5/7       │\n├──────────┬────────────┬──────────────────┬───────────────────┤\n│ STATUS   │ QUEUE (12) │ IN PROGRESS (5)  │ DONE (8)          │\n├──────────┼────────────┼──────────────────┼───────────────────┤\n│ ▾ Config │ INV-003 ‼️ │ A▶ backend       │ ✓ FEAT-040 12:30  │\n│   ✓ dir  │ FIX-089    │   FEAT-042  5m   │ ✓ FIX-088  12:15  │\n│   ✓ cfg  │ FIX-090    │ A▶ frontend      │ ✓ FEAT-041 11:45  │\n│   ✓ tkts │ FEAT-043   │   FIX-091  3m    │ ✓ FIX-087  11:30  │\n│ ▾ Conns  │ FEAT-044   │ C⏸ api           │                   │\n│   ✓ API  │ FEAT-045   │   SPIKE-015 12m  │                   │\n│   ✓ Web  │            │   Awaiting input │                   │\n│   tmux   │            │ A▶ admin         │                   │\n│ ▸ Kanban │            │   FEAT-047  1m   │                   │\n│ ▸ LLM    │            │ A▶ infra         │                   │\n│ ▸ Git    │            │   FIX-092  8m    │                   │\n├──────────┴────────────┴──────────────────┴───────────────────┤\n│ [Q]ueue [L]aunch [P]ause [R]esume [A]gents [?]Help [q]uit   │\n└──────────────────────────────────────────────────────────────┘\n```\n\n## Keyboard Shortcuts\n\nSee [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.\n\n## Integration Points\n\n### LLM Agent Launch\n\nAgents are launched in terminal sessions with the appropriate project folder and an initial prompt derived from the ticket.\n\n### Third-Party Integrations\n\nInvestigations can be triggered externally:\n- Webhook endpoint for alerting systems\n- File watch for alert drop files\n- CLI for manual urgent tickets\n\n```bash\n# Create urgent investigation from external alert\noperator alert --source pagerduty --message \"500 errors in backend\" --severity S1\n```\n\n## LLM CLI Tool Integration\n\nOperator launches LLM agents via CLI tools in terminal sessions. Each tool is configured via a JSON definition in `src/llm/tools/`.\n\n### Supported Tools\n\n| Tool | Detection | Models | Session Flag |\n|------|-----------|--------|--------------|\n| `claude` | `claude --version` | opus, sonnet, haiku | `--session-id` |\n| `codex` | `codex --version` | gpt-4o, o1, o3 | `--resume` |\n| `gemini` | `gemini --version` | pro, flash, ultra | `--resume` |\n\n### How Operator Calls LLM Tools\n\nEach 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:\n\n- **Prompt file**: Prompts are written to `.tickets/operator/prompts/\u003cuuid\u003e.txt` to avoid shell escaping issues with multiline prompts\n- **Session ID**: A UUID v4 is generated per launch, enabling session resumption\n- **Model aliases**: Operator uses short aliases (e.g., \"opus\", \"sonnet\") that resolve to latest model versions\n\n### Adding Support for New LLM Tools\n\nCreate a new JSON tool config following the schema in `src/llm/tools/tool_config.schema.json`. The config defines:\n\n- Tool binary name and version detection command\n- Model aliases and argument mappings\n- Command template with placeholder variables\n- Capability flags (sessions, headless, permission modes)\n\n**Requirements for the LLM tool:**\n- Must be installable as a CLI binary\n- Must accept prompt via flag (not just stdin)\n- Must support model selection\n- Should support session/conversation ID for continuity\n- Should run interactively in a terminal (for session wrapper integration)\n\n## Model Servers\n\nOperator's agent-launch hierarchy has three layers:\n\n```\n┌─ llm_tools ─────────┐   ┌─ model_servers ──────┐\n│ claude  (detected)  │   │ anthropic-api (impl.)│\n│ codex   (detected)  │   │ openai-api    (impl.)│\n│ gemini  (detected)  │   │ google-api    (impl.)│\n│                     │   │ ollama-local  (user) │\n└─────────────────────┘   └──────────────────────┘\n            ▲                        ▲\n            │                        │\n            └───── delegators ───────┘\n   name, llm_tool, model, model_server (optional)\n```\n\n- **`llm_tools`** are the agentic coding-agent CLIs (claude/codex/gemini). They're detected on PATH and drive the session.\n- **`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.\n- **`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.\n\nExample `operator.toml`:\n\n```toml\n[[model_servers]]\nname = \"ollama-local\"\nkind = \"ollama\"\nbase_url = \"http://localhost:11434\"\n\n[[delegators]]\nname = \"codex-local-qwen\"\nllm_tool = \"codex\"\nmodel = \"qwen2.5-coder\"\nmodel_server = \"ollama-local\"\n```\n\nAd-hoc launch flags:\n\n```bash\n# Named delegator (recommended)\noperator launch --delegator codex-local-qwen\n\n# Ad-hoc override\noperator launch --llm-tool codex --model qwen2.5-coder --model-server ollama-local\n```\n\n**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`.\n\nCurrent 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.\n\n## Development\n\n```bash\n# Run in development\ncargo run\n\n# Run tests\ncargo test\n\n# Build release\ncargo build --release\n```\n\n## Documentation\n\nReference documentation is auto-generated from source-of-truth files to minimize maintenance.\n\n### Available References\n\n| Generator | Source | Output |\n|-----------|--------|--------|\n| taxonomy | `src/backstage/taxonomy.toml` | `docs/backstage/taxonomy.md` |\n| issuetype-schema | `src/schemas/issuetype_schema.json` | `docs/schemas/issuetype.md` |\n| metadata-schema | `src/schemas/ticket_metadata.schema.json` | `docs/schemas/metadata.md` |\n| shortcuts | `src/ui/keybindings.rs` | `docs/shortcuts/index.md` |\n| cli | `src/main.rs`, `src/env_vars.rs` | `docs/cli/index.md` |\n| config | `src/config.rs` | `docs/configuration/index.md` |\n| OpenAPI | `src/rest/` (utoipa annotations) | `docs/schemas/openapi.json` |\n| llm-tools | `src/llm/tools/tool_config.schema.json` | `docs/llm-tools/index.md` |\n| startup | `src/startup/mod.rs` | `docs/startup/index.md` |\n| config-schema | `docs/schemas/config.json` | `docs/schemas/config.md` |\n| state-schema | `docs/schemas/state.json` | `docs/schemas/state.md` |\n| schema-index | `docs/schemas/` | `docs/schemas/index.md` |\n| jira-api | `docs/schemas/jira-api.json` | `docs/getting-started/kanban/jira-api.md` |\n\n### Viewing Documentation\n\n```bash\n# Serve docs locally with Jekyll\ncd docs \u0026\u0026 bundle install \u0026\u0026 bundle exec jekyll serve\n# Visit http://localhost:4000\n\n# View OpenAPI spec with Swagger UI\n# After starting Jekyll, visit http://localhost:4000/schemas/api/\n```\n\n### Regenerating Documentation\n\n```bash\n# Regenerate all auto-generated docs\ncargo run -- docs\n\n# Regenerate specific docs\ncargo run -- docs --only openapi\ncargo run -- docs --only config\n\n# Available generators: taxonomy, issuetype-schema, metadata-schema, shortcuts,\n# cli, config, OpenAPI, llm-tools, startup, config-schema, state-schema,\n# schema-index, jira-api\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funtra%2Foperator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funtra%2Foperator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funtra%2Foperator/lists"}