vyuha
by sudheerdvn
README.md
# Vyuha
[](https://pypi.org/project/vyuha/)
[](https://github.com/sudheerdvn/vyuha/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://ollama.com/)
[](https://modelcontextprotocol.io/)
Repo-local workflow for coding agents: tickets, worktrees, review gates, staged deploys.
<p align="center">
<img src="docs/assets/hero.png" alt="Vyuha: repo-local tickets, parallel worktrees, review gates, and staged deploys for coding agents" width="900">
</p>
Vyuha helps coding agents (Claude, Codex, Ollama, aider, etc.) work on the same repo without stepping on each other. Tickets live as local Markdown files, agents claim them, worktrees keep changes separate, and a file-based lock prevents overlapping work. No SaaS, no subscriptions, no external project state.
> **Experimental preview.** Vyuha is not a production orchestration platform. V1 provides git-level isolation and diff inspection; it does not sandbox agents at the OS level. See [Security Status](#security-status) and [Known Limitations](#known-limitations) before running it on repositories you care about.
---
## Demo
---
## Why vyuha?
| | vyuha | GitHub Issues | Linear | Jira |
|---|---|---|---|---|
| State lives in repo-local files | ✅ | ❌ (GitHub's servers) | ❌ (cloud) | ❌ (cloud) |
| Coordinates parallel agent worktrees | ✅ | ❌ | ❌ | ❌ |
| Works fully offline with local executors | ✅ | ❌ | ❌ | ❌ |
| No account / no SaaS dependency | ✅ | ❌ | ❌ | ❌ |
Traditional trackers store tasks. Vyuha also helps assign work, keeps parallel changes from colliding, and runs deploy steps from repo-local state.
MCP is built in — run `vyuha mcp` to expose the full command set as native tools for any MCP-compatible agent (Claude, Cursor, etc.), no shell commands required.
---
## Concepts in 30 seconds
```
.vyuha/tickets/TICK-007.md ← source of truth (YAML frontmatter)
│
▼
vyuha next ← agent asks: what should I work on?
vyuha start TICK-007 ← agent claims it; worktree + branch created
... agent works in .vyuha/worktrees/tick-007/ ...
vyuha complete TICK-007
vyuha review TICK-007
vyuha merge TICK-007 ← branch → main, worktree removed
vyuha promote production ← staged deploy with guard/pre/post hooks
```
Main command groups:
| Group | Commands |
|---|---|
| **Planning** — turn a request into scoped tickets | `create`, `analyze` |
| **Execution** — who works on what without colliding | `board`, `next`, `start`, `complete`, `review`, `merge` |
| **Delivery** — how merged code reaches environments | `promote`, `pipeline-status`, `flag` |
---
## Security Status
Vyuha is experimental software for coordinating coding agents on a local repo. Before letting it run without review, read this section.
**What Vyuha does to limit agent scope:**
- Runs each agent in a dedicated git worktree, one per ticket
- Enforces a `touches` list: files committed outside the declared scope route to `needs_review`
- Hard-blocks writes to CI/CD configs, credential files, and Vyuha's own source
- Scans ticket text for prompt injection signals before dispatch
- Optionally runs gitleaks, semgrep/bandit, pip-audit, and npm-audit on agent-produced diffs
**What Vyuha does NOT do:**
- MCP is not a sandbox. `vyuha mcp` exposes ticket lifecycle commands as native tools; an agent with access to those tools can claim tickets, create branches, and trigger merges. The MCP server authenticates nothing beyond what the MCP client config enforces.
- Host executors inherit host permissions. Agents (Claude Code, aider, Codex) run as the invoking OS user with full filesystem and network access. There is no bwrap, seccomp, or container wrapping.
- The file-based lock is single-machine, single-checkout. Two separate clones on two machines can both claim the same ticket.
**Recommendation:** use `--human-review final` when running `vyuha orchestrate` on any repository with production code. This stops after implementation and requires `vyuha merge <id>` to be run manually after you inspect the diff.
For the full threat model, executor permissions, and safe usage notes, see [SECURITY.md](SECURITY.md) and [docs/security-model.md](docs/security-model.md).
---
## Known Limitations
- **Lock scope is single-machine, single-checkout.** The file-based concurrency lock at `.vyuha/orchestrator.lock` prevents two `vyuha orchestrate` runs on the same checkout from racing, but does not coordinate across separate clones or machines.
- **No OS-level sandbox in V1.** Agents run as child processes with full user permissions. Vyuha inspects the git diff after the agent exits; it cannot observe what the agent read or sent over the network during execution.
- **Executor permissions come from the executor runtime, not from Vyuha.** When you configure `flags: ["--dangerously-skip-permissions"]` for Claude Code, that flag disables Claude Code's own per-action approval prompts so the agent can run headless. Vyuha passes the flag; the trade-off is intentional for unattended runs but means the agent acts without interactive confirmation.
---
## Platform support
| Platform | Status |
|---|---|
| Linux | Supported — primary development platform |
| macOS | Supported — CI-verified on every push |
| Windows | Core functionality works; projects using `.sh` executor scripts require WSL |
---
## Install
```bash
pip install vyuha
vyuha init # scaffold .vyuha/ + .vyuha.yml in your repo
```
To run from source:
```bash
git clone https://github.com/sudheerdvn/vyuha
cd vyuha
pip install -e ".[dev]"
```
---
## Quick start
```bash
# 1. Create a ticket file
cat > .vyuha/tickets/TICK-001.md << 'EOF'
---
id: TICK-001
title: Add rate limiting to the upload endpoint
status: open
priority: 1
touches:
- src/upload.py
- src/middleware.py
parallel_safe: true
autonomy: supervised
close_criteria: POST /upload returns 429 after 100 requests/min per user
---
## Background
A single client can saturate the worker pool with rapid uploads.
EOF
# 2. See the board
vyuha board
# 3. Agent claims and works
vyuha start TICK-001
# ... implement in .vyuha/worktrees/tick-001/ ...
vyuha complete TICK-001
vyuha review TICK-001
vyuha merge TICK-001
# 4. Deploy
vyuha promote production
```
---
## Commands
### Board & planning
```bash
vyuha board # ticket board + pipeline snapshot
vyuha next # recommend next ticket(s) + safe parallel batch
vyuha pipeline-status # commits pending at each environment stage
# Machine-readable output (any board/next/pipeline-status/flag list command):
vyuha --json board
vyuha --json next
vyuha --json pipeline-status
vyuha --json flag list
```
### Ticket lifecycle
```bash
# Draft → open
vyuha analyze TICK-007 # fill touches + close_criteria, then open the ticket
vyuha open TICK-007 # flip draft → open without re-running analysis (requires touches already set)
# Execution
vyuha start TICK-007 # claim; creates branch + worktree
vyuha complete TICK-007 # code done → code_complete
vyuha review TICK-007 # submit for review → in_review
vyuha merge TICK-007 # merge to main, delete worktree → merged
vyuha validate TICK-007 # optional post-merge validation → validated
vyuha done TICK-007 # close ticket → done
```
### Deployment
```bash
vyuha promote staging # guard → pre-promote → sync → post-promote
vyuha promote production
vyuha pipeline-status # see what's pending where
```
### Feature flags
```bash
vyuha flag list # show all flags (global)
vyuha flag list --env staging # show flags for 'staging' environment
vyuha flag enable new_checkout_flow --env staging
vyuha flag disable new_checkout_flow --env production
```
### MCP server
```bash
vyuha mcp # start stdio MCP server; attach any MCP-compatible client
```
Exposed tools: `board`, `next_ticket`, `pipeline_status`, `flag_list`, `flag_set`,
`start`, `complete`, `review`, `merge`.
### Utilities
```bash
vyuha init # scaffold .vyuha/ + .vyuha.yml
vyuha install-commands # copy Claude slash commands into .claude/commands/
vyuha gh-sync # mirror tickets to GitHub Issues (manual visibility sync; read-only view, not bidirectional)
vyuha gh-sync --dry-run # preview what would be created or updated
```
---
## Configuration
`.vyuha.yml` in your repo root (walk-up discovery — run from any subdirectory):
### Executors
vyuha dispatches tickets to whichever executor you configure. Each executor CLI has its own flag for non-interactive operation — pass those flags via `executors.<name>.flags` so the orchestrator can run without waiting for prompts:
```yaml
executor: claude # default executor for orchestrate
executors:
claude:
flags: ["--dangerously-skip-permissions"] # required for headless; disables Claude Code's per-action prompts — see Known Limitations
aider:
flags: ["--yes-always"] # auto-confirm all prompts; skip editor
codex:
flags: ["--approval-policy=never"] # no per-action approval prompt
ollama:
models:
implement: llama3.1
review: qwen2.5-coder
```
Per-executor `bin` overrides the binary name for a supported executor; `flags` are prepended before the prompt.
For human review, set `reviewer: human`. `vyuha orchestrate` will stop after implementation is complete and wait for `vyuha review <ticket> --verdict approved` or a changes-requested verdict before merge.
For fully local/offline runs, set `executor: ollama` and choose local models:
```yaml
executor: ollama
models:
analyze: llama3.1
implement: qwen2.5-coder
review: qwen2.5-coder
```
Vyuha will invoke `ollama run <model> <prompt>`; install and pull those models with Ollama first.
```yaml
ticket_prefix: TICK
tickets_dir: .vyuha/tickets
worktrees_dir: .vyuha/worktrees
executor: claude
core_files:
- src/core/auth.py
core_patterns:
- "src/db/**"
lock_statuses: [in_progress, code_complete, in_review]
flag_file: ~/.vyuha/feature_flags.json
environments:
- name: staging
branch: staging
from: main
trigger: auto # driven by git post-commit hook; vyuha reports status
flag_file: ~/.vyuha/staging.feature_flags.json
- name: production
branch: production
from: main
trigger: manual # Vyuha promote production runs the full sequence
guard_script: scripts/check-deploy-window.sh
pre_promote:
- scripts/run-integration-tests.sh
post_promote:
- scripts/restart-service.sh
flag_file: ~/.vyuha/feature_flags.json
```
---
## Concurrency model
**Scope: single git checkout, single machine.**
The `touches` list in each ticket is the lock. vyuha holds the lock from
`in_progress` through `in_review` — releasing only at `merged`. This prevents
merge conflicts when multiple agents work in parallel.
```
Agent A: TICK-003 touches: [src/auth.py] status: in_progress → LOCKED
Agent B: TICK-007 touches: [src/billing.py] status: in_progress → LOCKED
Agent C: TICK-009 touches: [src/auth.py] status: open → BLOCKED (overlaps A)
```
**What this does NOT prevent:** two separate git clones on two machines claiming the same ticket. `check_local_not_behind_remote` runs on every `start` to reduce this window, but it does not close it entirely — this is a V1 limitation covered in [Known Limitations](#known-limitations).
Five concurrency bugs fixed versus the original orchestrator:
| Bug | Fix |
|---|---|
| Lock released at `code_complete` | Lock held until `merged` |
| TOCTOU on `start` | Re-read ticket from disk immediately before write |
| Merge worktree leaked | Capture worktree path before nulling the field |
| Case mismatch on macOS | Worktree dirs always lowercased |
| Substring dedup in gh-sync | Exact `[TICK-N]` prefix match |
---
## Testing
```bash
venv/bin/pytest tests/ -q
```
880+ tests across 21 modules. All concurrency and security fixes have dedicated test coverage.
---
## MCP integration
Add to your MCP client config:
```json
{
"mcpServers": {
"vyuha": {
"command": "vyuha",
"args": ["mcp"]
}
}
}
```
The server starts on stdio. An AI agent can then call `board()`, `next_ticket()`,
`start("TICK-007")`, etc. as native tools — no shell commands required.
---
## Roadmap
Planned work:
- Per-task executor selection
- Stronger sandboxing for agent runs
- Executor conformance tests
- Distributed ticket coordination
See [ROADMAP.md](ROADMAP.md) for details.
---
## Docs
- `docs/demo-walkthrough.md` — end-to-end walkthrough: idea → analyze → parallel worktrees → review → merge, using a toy calculator project; includes a dry-run path for users without an executor configured
- `docs/troubleshooting.md` — FAQ and debug steps: executor hangs, stuck tickets, worktree cleanup, lock files, MCP setup, and more
- `SECURITY.md` — security policy, reporting vulnerabilities, and what Vyuha does and does not do
- `docs/security-model.md` — full threat model, trust boundaries, executor permission matrix, MCP trust model, V1 limitations, and safe usage recommendations
- `docs/ARCHITECTURE.md` — built architecture, module map, and design invariants
- `docs/config-reference.md` — supported `.vyuha.yml` keys and defaults
- `docs/executor-capabilities.md` — capability matrix comparing Claude, Codex, Aider, and Ollama across headless support, prompt transport, local model support, auto-commit behavior, and sandbox status
- `.vyuha.yml.example` — annotated example configuration
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessSyncing