Vyuha

Repo-local workflow for coding agents: tickets, worktrees, review gates, staged deploys.

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 and Known Limitations before running it on repositories you care about.

Demo

Related MCP server: jt-mcp-server

Why vyuha?

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:

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 and 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

Install

pip install vyuha
vyuha init    # scaffold .vyuha/ + .vyuha.yml in your repo

To run from source:

git clone https://github.com/sudheerdvn/vyuha
cd vyuha
pip install -e ".[dev]"

Quick start

# 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

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

# 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

vyuha promote staging          # guard → pre-promote → sync → post-promote
vyuha promote production
vyuha pipeline-status          # see what's pending where

Feature flags

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

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

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:

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:

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.

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.

Five concurrency bugs fixed versus the original orchestrator:

Testing

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:

{
  "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 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