Metadata-Version: 2.4
Name: nillebco-varda
Version: 0.7.0
License-File: LICENSE
Summary: Routes markdown tasks to AI agents (Claude, Codex, Copilot) and tracks their lifecycle
Home-Page: https://github.com/nillebco/varda
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/nillebco/varda
Project-URL: Source, https://github.com/nillebco/varda

# Varda

**Point Varda at your issue tracker. It routes each item to the right agent, runs it in a sandbox, and reports the result back.**

Varda is a small Rust CLI. It pulls work items from Azure DevOps, GitHub Issues or Jira, matches each item's project path to a route, checks the agent is allowed there, runs it under whatever isolation you configured, posts the recap and commit back to the item, and commits everything to a git-tracked control plane.

No tracker? A folder of markdown files works too — each task is a file carrying its own project path, zero setup. One operations folder tracks work across every project you own, and Varda can run itself, spawning sandboxed workers that merge their branches back.

```sh
varda tracker setup azdo --org acme --project Platform --repo ~/dev/acme/platform   # guided, once
# Agile: tag an item `varda` AND `varda:ready` BEFORE the first pull — readiness is decided at import
# (Scrum: tag `varda` and move it to `Approved`; other processes: see docs/trackers.md)
varda tracker pull                                                                 # imports it as a `ready` task (Agile without `varda:ready`: `backlog`)
varda run                                                                          # ready items → agents → recap on the item
varda task add "Fix the flaky auth test" --exec                                    # or, with no tracker: a local markdown task
```

→ [Issue trackers](docs/trackers.md) (Azure DevOps, GitHub, Jira)

## Quickstart (local markdown tasks)

```sh
brew tap nillebco/tap && brew install varda   # or, from a checkout: make install (→ ~/.local/bin)
# Windows (PowerShell, per-user, no admin; needs Git for Windows):
#   irm https://github.com/nillebco/varda/releases/latest/download/varda-installer.ps1 | iex
# Any platform, from PyPI (or a feed proxying it, where GitHub downloads are blocked):
#   uv tool install nillebco-varda
varda init            # creates the control plane at ~/.varda
```

Route your project to an agent, then write a task:

```sh
varda project add "/path/to/project/**" --agents claude,codex
cd /path/to/project
varda task add "Summarize this project" --edit   # --edit opens $EDITOR
varda task run <task>                       # or: varda run  (runs everything ready)
varda task show <task>                      # the recap
```

For scripts (cron/launchd jobs, bots) that need only the agent's answer:

```sh
echo "say hi" | varda task add t --agent brain-eod --exec --print-result   # answer on stdout, chatter on stderr
varda task run <task> --result-file /tmp/answer.txt                        # answer written to a file
```

`--print-result` / `--result-file` mark the task `bare_result` (the agent prompt omits Varda's recap/`Files touched`/`requires_user` contract), send all Varda output to stderr (or stdout for `--result-file`), skip live streaming, and exit non-zero if the agent run fails. Interactive and background runs are unchanged (the flags conflict with `--interactive`/`--background`).

`varda init` also runs `git init` on `~/.varda`, because every task update, recap and notification is committed there.

## The loop

1. **Route** — the task's project path picks a route; the route decides which agents are allowed.
2. **Run** — Varda marks the task `running` and launches the agent, in a sandbox if the route says so.
3. **Instruct** — the agent is handed your `CLAUDE.md` / `AGENTS.md` / `copilot-instructions.md`, the task body, and a hard requirement to produce a recap listing every file it touched.
4. **Bound** — it runs under a cooperative time and token budget rather than an unbounded loop.
5. **Resolve** — the task lands on `review`, `needs_user`, or `failed`, and the recap is written.
6. **Commit** — Varda commits the task update and recap to the control plane.

`needs_user` raises a desktop notification, so a task that stalls on a question doesn't sit silently.

## Sandboxing

A route can pin a task to a sandbox, and the agent never sees your host:

```toml
[[routes]]
glob = "/path/to/project/**"
agents = ["claude"]
sandbox = "worker"
```

Providers: **docker** (or podman, via `engine = "podman"`), **microsandbox** (microVM), and **processcontainer** (Windows MXC, no admin); `varda doctor` shows which work on this host. Each box gets a scoped credential minted on the host — never your `~/.aws`, never your `~/.azure` — an egress allowlist instead of open internet, and only the mounts you declare — with identity files forced read-only and credential paths denylisted.

Credentials are named, not embedded: config references a host env var or a secret-store key, and the value is resolved at launch. A repo-committed `.varda` is treated as untrusted and clamped to a hardening floor.

### Windows without admin rights

`primitive = "processcontainer"` runs the agent in a Windows MXC BaseContainer, built on `mxc-sdk` 1.0.1. It needs no administrator rights, no Hyper-V, no Docker and no WSL, so it works on managed corporate laptops and Cloud PCs. Egress goes through a host-side proxy that enforces the same hostname allowlist as the other providers. A host service such as a local MCP broker can be allowed by naming it, e.g. `"127.0.0.1:8765"`.

From Windows 11 24H2/25H2 build **26100.9711 / 26200.9711** (the October 2026 cumulative update), git, Node's `realpath.native` and Rust's `canonicalize` resolve paths inside the container ([microsoft/mxc#1464](https://github.com/microsoft/mxc/issues/1464)). Agent CLIs like Copilot CLI therefore run there unpatched. On earlier builds they fail with "access denied". Check yours with `varda doctor`, which prints the build and marks `processcontainer` unavailable below it, or `Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion' | Select CurrentBuild, UBR`. Still unsupported: anything that starts the MSYS runtime (Git Bash, shell-script git hooks; [microsoft/mxc#1061](https://github.com/microsoft/mxc/issues/1061)) and file-target credentials (use env credentials).

→ [Sandboxing](docs/sandboxing.md)

## Orchestration

Varda can drive itself. `varda orchestrate` starts a resident agent that reads the task board, spawns sandboxed workers into isolated git worktrees, and merges their branches back — surfacing conflicts rather than clobbering them.

```sh
varda orchestrate --interactive --workspace .
```

Workers reach the host only through a narrow MCP broker: spawn, collect, integrate, and task-board tools. Nothing else crosses the boundary, and an agent can never grant itself more capability than its route allows.

→ [Orchestration](docs/orchestration.md)

## Agents

`varda init` ships four ready to use. Add any of them to a route's `--agents`.

| Agent | Backend | Permissions | Resume |
|---|---|---|---|
| `codex` | OpenAI Codex CLI | `--sandbox workspace-write` | yes |
| `claude` | Claude Code CLI | `--permission-mode acceptEdits` | yes |
| `copilot` | GitHub Copilot CLI | `--allow-all-tools` | yes |
| `opencode` | [opencode](https://opencode.ai) | `--auto` | no |

Agents can declare `max_prompt_tokens`; Varda estimates the full prompt and picks an allowed agent that fits, or tells you which ones would.

→ [Configuration](docs/configuration.md) · [The agent contract](docs/agent-contract.md)

## Daily driving

```sh
varda task list                  # tasks for this project
varda task dashboard --web --all # kanban board, every project
varda plan                       # a reviewable plan of ready work
varda task inspect <task>        # agent, route, live processes
varda task doctor <task>         # probe the last run
varda task resume <task>         # continue a needs_user task
```

→ [Tasks](docs/tasks.md) · [Git behavior](docs/git.md)

## Claude Code skill

```sh
varda skill install        # or --link to stay in sync with the repo
```

Then `/varda` in any Claude Code session to manage tasks in natural language.

## Development

```sh
make test      # tests
make fmt       # formatting
make build     # debug build
make release   # release build
make install   # install to ~/.local/bin
```

Releasing: bump `version` in `Cargo.toml`, then `git tag vX.Y.Z && git push --tags`.
The `release.yml` workflow (generated by [cargo-dist](https://opensource.axo.dev/cargo-dist/);
regenerate with `dist generate` after editing `dist-workspace.toml`) builds macOS/Linux/Windows
binaries, publishes a GitHub Release, and pushes the formula to `nillebco/homebrew-tap`
(needs the `HOMEBREW_TAP_TOKEN` repo secret).

## Documentation

| | |
|---|---|
| [Issue trackers](docs/trackers.md) | Azure DevOps / GitHub / Jira: setup, `status_map`, lifecycle, conflicts |
| [Tasks](docs/tasks.md) | creating, running, inspecting, resuming |
| [Configuration](docs/configuration.md) | routes, agents, `config.toml` reference |
| [Sandboxing](docs/sandboxing.md) | providers, credentials, isolation invariants |
| [Isolation](docs/isolation.md) | what each primitive actually blocks, verified vs not |
| [Orchestration](docs/orchestration.md) | sub-task spawning, the resident, roles |
| [The agent contract](docs/agent-contract.md) | what the agent is told, execution bounds |
| [Git behavior](docs/git.md) | what gets committed, verification gate |

## Current limitations

- Agents are driven as subprocesses — spawn the CLI, pipe the prompt on stdin, scrape the recap
  from stdout — not over the Agent Client Protocol. `kind = "acp"` is a vestigial config field
  with a single legal value that selects nothing.
- Notification is file-backed JSON plus terminal output, with a best-effort macOS native signal for tasks that need user input.
- Task handoff to another agent is represented by `review` plus recap metadata; automatic reassignment is not implemented yet.

